dellweb3's picture
Work OS validated demo local-v0.8
99caad5 verified
|
Raw History Blame Contribute Delete
28.9 kB

Work OS MVP · Workspace Service 系统架构与功能设计 v1.0

状态:设计基线,已有首版 PC 持久化实现;与全部需求清单的完成状态请看 实现说明。日期:2026-10-10。目标:2026-10-18 前完成 PC 演示,随后腾讯云验收,再验证银河麒麟/海光。配套资料:总体设计、API Gateway 设计及 OpenAPI、细化任务表。原 Gateway 演示桩已替换为 Workspace 首版代码;目前 SQLite 模式已实测,PostgreSQL 与目标国产平台仍待实测,以下需求清单不可自动视为全部完成。

1. 模块定位与范围

Workspace 是用户个人工作台和每件公文事项的事实账本:保存事项归属、会话、附件引用、技能选择、草稿和不可变版本。所有数据以服务端核验的 tenant_id + owner_user_id + workspace_id 隔离。PC 可将 tenant_id 固定为 demo,字段、索引和校验仍须存在。

负责 不负责
个人空间唯一性;事项创建、列表、重命名、状态投影 登录与令牌校验(Identity/Gateway)
事项消息;附件元数据、文件引用、授权下载 文件解析、知识索引/检索(Knowledge)
事项 Skill ID/版本绑定;草稿正文、引用、版本及哈希 Skill 定义、数字员工编排、模型调用(Agent Runtime)
授权的内部读写 Port;可靠领域事件 DOCX 生成与本机执行(Tool);通知投递(Notification)

P0 指 10 月 18 日前的 PC 真服务;P1 指随后腾讯云单机;P2 指麒麟海光及企业级扩展。管理端、跨用户共享、正式 OA 发文不在 P0。

2. 系统架构、技术栈与小模块

flowchart TB
  Portal[Portal Web / 后续 Admin] --> G[API Gateway /api/v1]
  Identity[Identity Principal] --> G
  G --> W[Workspace Application Service]
  W --> A[WS01 个人/事项]
  W --> B[WS02 事项消息]
  W --> C[WS03 附件]
  W --> D[WS04 草稿版本]
  A & B & C & D --> R[Repository Ports]
  R --> PG[(PostgreSQL)]
  C --> S[StoragePort: 本机文件/S3兼容]
  W --> O[(Workspace outbox)]
  O -.变更事件.-> Context[Context]
  O -.解析请求.-> K[Knowledge]
  Runtime[Agent Runtime] <--> W
  Tool[Tool Gateway] --> W

PC 采用模块化单体中的真实 Workspace 模块:Gateway 路由调用进程内 WorkspacePort;设计目标是真连 PostgreSQL、真写受限文件目录。当前首版在无 PostgreSQL 服务的 PC 上以 SQLite 验证同一领域模型和文件落盘;切换 PostgreSQL 仍须现场验证。云阶段可继续同进程,或以内部 HTTPS 适配器承载同一 Port/DTO。业务服务不通过 HTTP 回调自身,也不直接调用其他模块的数据库表。

层 推荐技术/框架 设计依据与替换点
HTTP/DTO 复用 Gateway 的 FastAPI、Pydantic 2、OpenAPI 3.1 复用已冻结外部 URL;DTO 映射与领域服务分离
领域/装配 Python 3.11+、Protocol、依赖注入/app factory WS01–04 可独立编码;新实现只换 provider
持久化 SQLAlchemy 2、Alembic、psycopg 3、PostgreSQL 事务、唯一约束、版本并发和 outbox;版本锁进依赖文件
附件 StoragePort;PC 文件系统、云 S3 兼容适配器 DB 只存随机逻辑键,不存 Windows 盘符/公网直链
事件 同库 outbox;PC 表轮询、云可换 RabbitMQ/Kafka 业务写入和事件同事务;消费者按 event_id 幂等
运维 JSON 日志、trace_id、指标、manifest 备份 日志仅记 ID/状态/哈希,不记正文或令牌
小模块 聚合/服务 主要方法 P0 最小交付
WS01 个人/事项 WorkspaceService、Matter get_or_create_home、list/create/get/rename_matter、assert_access、bind_skills A/B 各有唯一 home;事项真实落库,所有子资源先查归属
WS02 消息 MessageService、Message append_user_message、append_assistant_message、list_messages 当前事项独立、稳定分页、重试不重复
WS03 附件 AttachmentService、Attachment upload、list、open_authorized、apply_ingest_result 真落盘、hash、受控下载、解析状态
WS04 草稿版本 ArtifactService、ArtifactVersion create_draft、edit_draft、get_version、resolve_approved_version 不可变版本、409 并发冲突、确认绑定版本/hash

事项 Skill 绑定归 WS01,只存 skill_id,skill_version,position;Skill 内容、可用性及注入策略由 Agent/Skill Catalog 决定。客户端不能通过更改 Skill 名称注入执行指令。

3. 上层接口、下层对接和灵活扩展

浏览器流量只经 Gateway;Identity 验证后由 Gateway 构造不可由请求体覆盖的 Principal(tenant_id,user_id,roles,trace_id)。Workspace 再次用数据库 owner 校验。内部工作者须有服务认证和最终用户/任务委托上下文;不能用系统身份绕过归属。管理员代读另行设计。

对接 方式与内容 模块更换时改动
Portal → Gateway → Workspace 外部 HTTPS/REST;PC 进程内 Port;13 个既有 /api/v1 操作 新业务加 DTO/Port/路由装配/合同测试,旧 URL 语义不变
Identity → Workspace Gateway 注入 Principal;Workspace 校验 owner SSO/LDAP 变化只换 Identity adapter
Agent Runtime ↔ Workspace WorkspacePort 或内网 mTLS HTTPS;起跑校验事项、读取 Skill 快照;写助手消息/草稿必须带 run_id 与幂等键 新数字员工流程复用 Port,不能直写 WS 表
Context → Workspace 只读 ContextReadPort;带 owner 的当前事项消息/附件/版本引用 换 Context 实现只改 adapter
Workspace → Knowledge document.ingest.requested 事件;结果回执更新附件状态投影 换解析/索引引擎不改公共附件 API
Tool Gateway → Workspace ApprovedArtifactReadPort;执行后绑定导出文件/回执 新工具复用精确版本/hash 约束
Workspace → Context/Notification outbox 变更事件,payload 只含必要 ID/版本/状态 新消费者订阅版本化事件,不改写路径

扩展的最低前提是 DTO 合同兼容、授权语义不弱化、事件版本受控、数据迁移通过。配置新 URL 并不能自动证明 owner 过滤或事务正确,替换实现必须跑双用户和幂等测试。

3.1 对外接口列表

以 Gateway OpenAPI 为字段、header、状态码和错误体的权威来源。以下 13 项为 Workspace 所有;所有路径前缀 /api/v1。越权资源与不存在统一 404;POST 创建/消息/上传要求 Idempotency-Key。

API 方法及路径 子模块 核心输入/结果
05 GET /workspaces WS01 本人事项稳定分页;200
06 POST /workspaces WS01 title、幂等键;201 同键重试同 ID
07 GET /workspaces/{workspace_id} WS01 本人事项;200/404
08 PATCH /workspaces/{workspace_id} WS01 title、expected_version;成功版本+1,旧版 409
09 GET /workspaces/{workspace_id}/messages WS02 游标/limit;事项消息分页
10 POST /workspaces/{workspace_id}/messages WS02 content、幂等键;201
11 GET /workspaces/{workspace_id}/attachments WS03 只返回元数据/解析状态
12 POST /workspaces/{workspace_id}/attachments WS03 单件 multipart、幂等键;201/413/422
13 GET /attachments/{attachment_id}/content WS03 授权流式下载;200/404
22 PUT /workspaces/{workspace_id}/skills WS01 skill_ids、expected_version;200/409/422
28 GET /artifacts/{artifact_id} WS04 当前草稿正文、版本、hash、引用
29 PATCH /artifacts/{artifact_id} WS04 content、expected_version;新版本或 409
30 GET /artifacts/{artifact_id}/versions/{version}/content WS04 该版本生成文件;200/404

API-23 任务启动和 API-27 人工确认归 Agent Runtime;API-14 上下文归 Context。Workspace 供其授权数据,不接管 run 状态机与 SSE。

Workspace 响应新增可选 latest_artifact_id(无草稿时为 null):客户端重启后可用既有 API-28 重新读取最新草稿,不新增路由。该指针仅在已授权事项响应中返回;Gateway OpenAPI同步定义。

3.2 内部 Port 代码骨架

@dataclass(frozen=True)
class Principal:
    tenant_id: str
    user_id: str
    roles: frozenset[str]
    trace_id: str

class WorkspacePort(Protocol):
    def assert_access(self, principal: Principal, workspace_id: str) -> MatterRef: ...
    def append_assistant_message(self, principal: Principal, workspace_id: str,
                                 run_id: str, step_id: str, content: str,
                                 idempotency_key: str) -> MessageRef: ...
    def create_draft(self, principal: Principal, workspace_id: str,
                     run_id: str, content: str, citation_ids: list[str],
                     idempotency_key: str) -> ArtifactRef: ...
    def resolve_approved_version(self, principal: Principal, artifact_id: str,
                                 version: int, expected_hash: str) -> ArtifactVersionRef: ...

建议文件布局:workspace/contracts/v1.py、ports.py、domain/、application/、adapters/postgres.py、adapters/storage_fs.py、tests/contract/、alembic/versions/。分进程时由服务认证封装委托主体;不允许前端直接提交内部 Principal JSON。

4. 数据模型和关键不变量

erDiagram
  PERSONAL_WORKSPACE ||--o{ MATTER_WORKSPACE : contains
  MATTER_WORKSPACE ||--o{ MESSAGE : contains
  MATTER_WORKSPACE ||--o{ ATTACHMENT : contains
  MATTER_WORKSPACE ||--o{ WORKSPACE_SKILL_BINDING : selects
  MATTER_WORKSPACE ||--o{ ARTIFACT : owns
  ARTIFACT ||--o{ ARTIFACT_VERSION : has
  MATTER_WORKSPACE ||--o{ WORKSPACE_OUTBOX : emits
表/主键 必需字段(不含时间戳) 唯一/索引与写入规则
personal_workspace(home_id) tenant_id,owner_user_id UNIQUE(tenant_id,owner_user_id);并发登录 INSERT ... ON CONFLICT ... RETURNING
matter_workspace(workspace_id) home_id,tenant_id,owner_user_id,title,status,version FK home;断言 home 同 tenant/owner;INDEX(tenant_id,owner_user_id,updated_at,workspace_id)
workspace_message(message_id) workspace_id,tenant_id,owner_user_id,seq,role,content,run_id?,step_id? UNIQUE(workspace_id,seq);带幂等键时按主体+事项+操作唯一;只追加
attachment(attachment_id) workspace_id,filename,mime,byte_size,sha256,storage_key,parse_status,knowledge_document_id? 随机 storage_key;INDEX(workspace_id,created_at,id);解析状态由回执投影
workspace_skill_binding workspace_id,skill_id,skill_version,position,binding_version UNIQUE(workspace_id,skill_id);整体 CAS;目录不可用则拒绝
artifact(artifact_id) workspace_id,kind,current_version,approval_version? 查找前校验事项归属;一个事项可有多个产物
artifact_version artifact_id,version,content,content_hash,citation_ids,source_run_id,export_storage_key? PRIMARY KEY(artifact_id,version);正文写后不可变
workspace_outbox(event_id) aggregate_id,aggregate_version,event_type,payload,trace_id,published_at? 事务内写;UNIQUE(aggregate_id,aggregate_version,event_type)
workspace_idempotency tenant_id,owner_user_id,workspace_id?,operation,key,request_hash,response_ref 相同键+hash 复用结果,异 hash 409

每个子资源同时保留 tenant/owner/workspace;高风险查询须 JOIN matter_workspace 并过滤 tenant+owner,不可只比较附件/草稿 ID。数据库 FK/唯一约束为最终防线。SQLAlchemy 用 with session.begin();版本冲突用 UPDATE ... WHERE version=:expected RETURNING 或行锁后校验,零行返回 409。PostgreSQL 的官方行锁文档支撑同一聚合的串行化。分库后不承诺跨库本地事务,改用 outbox+幂等消费+对账。

4.1 附件状态和物理文件

PC 限单件 10 MiB、单事项 5 件;支持 DOCX/PDF/TXT/MD 文本;扫描 PDF/OCR 不在 P0。上传流先写受限 staging 目录,计数/校验 MIME、扩展名、SHA-256,再移动到随机逻辑键目录,随后提交元数据及 document.ingest.requested outbox;DB 提交失败则清理新文件,清理失败由 reconcile 找回孤儿。客户端不能指定 storage_key、物理路径或对象存储 URL。解析失败只更新 parse_status=failed 与安全错误码,原文件仍可授权下载。

文件系统与 DB 非一个事务:采用 staging → verified → committed,提供 manifest(attachment_id、storage_key、sha256、bytes)与重扫作业。云可换 S3 兼容 StoragePort;MinIO S3 文档是适配依据,具体产品部署时再选并实测。Knowledge 拥有解析结果和索引,Workspace 只保存回执/状态投影;重复或乱序回执按 ingest_job_id+event_version 幂等处理。

4.2 草稿与人工确认

每次编辑在一个事务中检查 expected_version、插入 artifact_version(current+1)、更新 current_version、写 outbox;历史正文不可覆盖。content_hash=SHA-256(UTF-8 NFC 正文),相同正文再次编辑仍产生新版本以保留审计。引用保存 citation ID 和生成时所用知识文档版本,显示时由 Knowledge 再做授权与有效性检查。

Runtime 的批准请求带 artifact_id,version,content_hash。Workspace 在事务内验证请求版本等于当前版本、hash 一致,并把确认绑定到这个不可变版本。之后编辑产生未确认新版本;旧确认只允许用于旧版受控导出,不能授权新版。Tool 仅按精确三元组读取,执行回执和导出文件引用再绑定到该版本。跨进程失败用幂等键重试并对账;不能靠 approved=true 布尔值授权任意正文。

4.3 状态与事件

事项 status 是列表投影:new/running/awaiting_confirmation/completed/failed;run 真状态/进度归 Runtime。Workspace 消费 Runtime 事件只接受同一 run 的更高 run_sequence;旧事件不得倒退事项状态。客户端 PATCH 不得修改 status。

Workspace 自有领域事件不冒充RunEventEnvelope:后者强制 run_id/sequence,而 workspace.created 尚无 run。Workspace outbox v1 字段为 event_id,event_type,event_version,tenant_id,owner_user_id,workspace_id,aggregate_version,trace_id,occurred_at,payload,run_id 可选;若 Runtime 需 SSE,须转成真正带 run_id/run sequence 的 RunEventEnvelope。事件包括 workspace.created/updated、message.appended、attachment.uploaded、document.ingest.requested、attachment.ingest_succeeded/failed、artifact.version_created/confirmed、artifact.export_attached。payload 只放 ID/版本/状态/摘要,不广播正文;消费者按 event_id 去重。

5. 安全、性能、部署与国产化迁移

权限与隐私:Identity 验证后 Gateway 注入 Principal,Workspace 每次读写重验 owner。用户 A 的事项 ID 用在消息、附件下载、草稿、Skill 绑定和内部 Context/Tool 读取均返回 404。内部 worker 带真实委托主体 + run_id;日志不记令牌、全文或物理路径。P0 不开放共享事项、管理员代读或正式发文。

输入、并发和错误:标题、消息、草稿设最大长度;SQL 参数绑定;文件名只用于安全显示,下载使用安全编码的 Content-Disposition;阻断路径穿越、符号链接逃逸和双扩展名伪装。上传流限额,不能整文件读爆内存。幂等作用域含租户/用户/事项/操作;稳定游标分页。单事项最多一个活跃 run 由 Runtime 限制。

观测与恢复:跟踪 HTTP 延迟、5xx/409、outbox 积压、解析等待、孤儿文件数;审计记录谁何时创建、修改、确认及 trace,不记全文。PC 的 DB 与文件目录成套备份,恢复时对账 manifest/hash,重跑 A/B 隔离用例。P1 腾讯云沿用两阶段部署方案的 4 vCPU/8 GiB 单机、PostgreSQL 与受限数据盘或 S3 兼容存储;Qwen 继续走公网 API,Workspace 不另购 GPU。实际费用按部署方案及购买时价格复核。

国产化:银河麒麟 V10 SP3 官方资料列出海光平台支持,但不表示 Python native wheel 已在目标环境验证。迁移时记录具体 OS/CPU 版本,实测 Python、psycopg、pydantic-core、cryptography、libpq/TLS、PostgreSQL、文件权限、systemd;运行相同 Alembic 迁移、接口合同、双用户越权、附件 hash、并发版本与备份恢复。容器镜像也须在目标机实测架构及运行时。PostgreSQL 方言封装于 Repository;不假设国产数据库零代码替换。国密/等保要求待客户定级和产品选型,不宣称 P0 已达标。

6. 办文工作流示例:Workspace 如何运行

sequenceDiagram
  participant U as 用户/Portal
  participant G as API Gateway
  participant W as Workspace
  participant K as Knowledge
  participant C as Context
  participant A as Agent Runtime
  participant T as Tool Gateway
  U->>G: 创建“年度培训通知”事项
  G->>W: create_matter(Principal,title,key)
  W-->>G: workspace_id/version=1
  U->>G: 上传制度PDF,发送写作要求
  G->>W: upload / append_user_message
  W-->>K: outbox: document.ingest.requested
  K-->>W: ingest_succeeded(document_id)
  U->>G: 调用公文写作数字员工
  G->>A: start(run,workspace_id,skills)
  A->>W: assert_access / read_message / read_attachment_refs
  A->>C: 构建当前事项上下文和引用
  A->>W: create_draft(content,citation_ids,run_id)
  W-->>U: 草稿 v1,待人工核对
  U->>G: PATCH 草稿 expected_version=1
  G->>W: edit_draft -> v2/hash2
  U->>G: 确认 v2/hash2
  G->>A: approval(run_id,v2,hash2)
  A->>W: resolve_approved_version(v2,hash2)
  A->>T: 导出 v2/hash2 DOCX
  T-->>W: 绑定导出文件及回执

A 创建事项 ws-a-01,B 即使拿到 ID,也不能读取该事项、消息或附件。A 把 v1 改为 v2 后再提交 v1/hash1 确认,Workspace 返回 409 artifact_version_conflict。Knowledge 故障时附件保持 parsing/failed 且本人可下载;Agent 对需要检索的步骤显示 dependency_not_ready,不假装检索成功。消息和进度流由 Runtime 组织,Workspace 留存消息及产物事实。

7. 接口示例与错误规范

以下是设计示例,不是运行实测;完整字段以Gateway OpenAPI为准。

POST /api/v1/workspaces HTTP/1.1
Authorization: Bearer <token-for-user-a>
Idempotency-Key: create-matter-20261010-a
Content-Type: application/json

{"title":"2026年度培训通知"}
{"workspace_id":"ws-a-01","parent_id":"home-a","title":"2026年度培训通知","version":1,"status":"new"}
PATCH /api/v1/artifacts/art-a-01 HTTP/1.1
Authorization: Bearer <token-for-user-a>
Content-Type: application/json

{"content":"关于开展年度培训的通知……","expected_version":1}
{"artifact_id":"art-a-01","workspace_id":"ws-a-01","version":2,"content":"关于开展年度培训的通知……","content_hash":"<sha256-hex>","approval_status":"unconfirmed","citation_ids":["cite-001"]}

错误沿用 Gateway 的 code/message/trace_id/details:401 会话无效;404 不存在或无权访问;409 版本、幂等键、附件额度冲突;413 文件超限;422 DTO、文件类型、Skill 不合法;503 必需存储依赖不可用。错误体不含他人 ID、正文、路径或内网地址。

{"code":"artifact_version_conflict","message":"草稿已更新,请刷新后重试","trace_id":"tr-001","details":{"current_version":2}}

8. 开发顺序与验证方式

沿用任务表 W01–W08的依赖链:Identity/Gateway/DB 基础 → WS01 个人与事项 → owner 校验 → WS02 消息与 WS03 附件 → WS04 版本。DTO/合同可先并行准备,但 Gateway fixture 不能代替 Workspace 验收。配置集中管理 DATABASE_URL、WORKSPACE_FILE_ROOT、MAX_UPLOAD_BYTES、OUTBOX_MODE;演示用户与 Windows 路径不写死在领域代码。

完成性证据必须是真实进程 + 真 PostgreSQL + 文件目录:A/B 各建两件事项、写消息、传文件;重启后数据仍在;B 访问 A 全部资源为 404;相同幂等键不重复;并发编辑同版仅一个成功;上传/下载 hash 相同;Knowledge 中断时解析状态显式失败或待重试。云和麒麟阶段重复同一套脚本,保留运行日志与环境版本。现有 Gateway 桩通过只证明 HTTP 演示链路。

设计依据:Gateway OpenAPI、总体架构与 Run 事件契约、PostgreSQL 官方行锁文档、麒麟 V10 SP3 平台信息、MinIO S3 接口文档。

9. 需求清单与可执行验收(客户重点)

读法:P0 是 10 月 18 日前 PC 必过;P1 是随后腾讯云;P2 是麒麟海光/后续能力。WS01–04 表示小模块从属。每一条都有可执行动作和可观察结果;未通过不得标完成。依赖列说明其他模块的前置条件,不能把其桩响应算作 Workspace 自身实现。

9.1 WS01:个人空间、事项和 Skill 绑定

ID 阶段 需求/行为 依赖 完成性检验
WS01-01 P0 首次登录为每位用户创建唯一个人空间;重复登录复用 Identity Principal、PostgreSQL A 连续登录 3 次仅 1 个 home;B 是另一个;DB 有唯一约束
WS01-02 P0 个人空间下创建、列出、进入事项;有标题、归属、状态、版本 WS01-01、Gateway API-05–07 A/B 各建 2 件,各列表只见自己的 2 件;重启后仍存在
WS01-03 P0 事项重命名按 expected_version 比对 WS01-02、API-08 旧版 PATCH 409;成功后版本+1,标题不丢
WS01-04 P0 所有子资源统一租户+用户+事项授权 Identity、WS01-02 B 对 A 的事项、消息、附件、草稿、Skill URL 读写均 404;拒绝有审计
WS01-05 P0 事项列表稳定分页,切换事项不串消息或附件 WS01-02 20+ 事项翻页不漏/不重;A1 切 A2 内容独立
WS01-06 P0 事项 Skill 选择保留 ID、版本、顺序,更新按绑定版本 CAS Agent Skill Catalog、API-22 重开事项仍保留;不可用 Skill 422;并发旧版 409;运行读同一快照
WS01-07 P0 创建事项按幂等键和请求哈希去重 WS01-02 同键同体返回同一事项;同键异体 409,无第 2 件
WS01-08 P0 事项状态投影消费 Runtime 事件并对账 Runtime run 事件 乱序/重复不倒退状态;完成后列表与 run 一致
WS01-09 P2 共享事项和管理员授权另立角色模型 客户角色矩阵 未审批前接口不开放;审批后另立验收

9.2 WS02:事项消息和对话输入

ID 阶段 需求/行为 依赖 完成性检验
WS02-01 P0 用户消息写入当前事项,带主体、顺序、时间和内容 WS01-04、API-10 A1 写 3 条,刷新/重启仍为 3 条;A2/B 看不到
WS02-02 P0 Agent 助手消息仅在授权事项及真实 run 上追加 Runtime、WS01-04 错事项/run 委托写入拒绝;合法结果只在该事项可见
WS02-03 P0 消息按服务端序号稳定分页 WS02-01、API-09 100 条分页读完 ID 与 DB 一致,无重复/遗漏
WS02-04 P0 消息写入幂等;键同而正文变化 409 WS02-01 重试不多一条;异文重用键 409
WS02-05 P1 审计、内容长度和保留策略可配置 客户留存要求 超限 422,审计无正文,客户确认策略后迁移验证

9.3 WS03:附件与资料证据链

ID 阶段 需求/行为 依赖 完成性检验
WS03-01 P0 上传 DOCX/PDF/TXT/MD,单件≤10 MiB、事项最多 5 件 WS01-04、StoragePort、API-12 四类样本可传;第 6 件/超限/非法文件给 409/413/422,不落半文件
WS03-02 P0 持久化原件及元数据:随机逻辑键、大小、MIME、SHA-256 WS03-01、PostgreSQL 重启后列表仍在;实际 hash 与记录一致;DB 无 Windows 绝对路径
WS03-03 P0 下载时重验 owner,阻断路径穿越/软链接逃逸 WS01-04、API-13 B 下载 A 的文件 404;伪造键/../ 无法越根;本人下载 hash 不变
WS03-04 P0 上传后发解析请求,展示 uploaded/parsing/ready/failed Knowledge 回执、outbox 成功为 ready、失败为 failed+安全错误码;重复回执无重复效果
WS03-05 P0 DB/文件部分失败可清理或 reconcile WS03-01/02 注入 DB 提交失败后无可见附件;扫描能报告并清理孤儿
WS03-06 P1 云对象存储 adapter 和 manifest 迁移 腾讯云存储/权限 导入后逐件 hash 相同,授权下载一致
WS03-07 P2 OCR、病毒扫描、敏感信息策略另行选型 安全/OCR 产品 新用例另立;PC 文本资料不依赖

9.4 WS04:草稿、版本和人工确认

ID 阶段 需求/行为 依赖 完成性检验
WS04-01 P0 Agent 在当前事项创建带引用的草稿 v1 WS01-04、Runtime、Knowledge 引用 生成后正文、版本、hash、引用可查;重启仍可取
WS04-02 P0 每次编辑新增不可变版本,保留历史正文/hash WS04-01、API-29 连改两次得 v1/v2/v3,v1 正文和 hash 不变
WS04-03 P0 expected_version 乐观锁防覆盖 WS04-02 两客户端同时以 v1 保存,仅一成功,另一 409;无丢失
WS04-04 P0 人工确认绑定 artifact_id+version+content_hash Runtime API-27、WS04-02 v1 确认后编辑 v2,旧确认不能导出 v2;错 hash/owner 拒绝
WS04-05 P0 Tool 只读已确认精确版本;回执与版本关联 Tool Gateway、WS04-04 v2/hash2 返回 v2;v1/hash2 拒绝;下载对应版本
WS04-06 P0 草稿及版本文件下载始终校验 owner WS01-04、API-28/30 B 对 A 草稿和各版本内容均 404
WS04-07 P1 历史比较与恢复产生新版本 WS04-02、Portal 恢复 v1 时创建 vN+1,旧版本仍可审计
WS04-08 P2 正式 OA 发文回写、电子签章另用 Adapter OA 系统/客户授权 未联通前 capability=false;另立端到端验收

9.5 跨模块非功能与交付要求

ID 阶段 需求/行为 依赖 完成性检验
WS-X01 P0 Repository 真连 PostgreSQL,迁移脚本可重复部署 DB、Alembic 空库迁移→接口写入→重启→数据仍在;fixture 不计通过
WS-X02 P0 事务内写 outbox、可重试和去重发布 WS-X01、消费者 注入发布失败再恢复,事件最终有一次业务效果,无已提交事项缺事件
WS-X03 P0 Gateway/Workspace 错误和 trace 可追踪 Gateway、日志 一次失败按 trace 找到调用;日志无 token、正文、物理路径
WS-X04 P0 完整双用户 E2E、并发与故障回归 WS01–04 自动化脚本/日志留存;PC 从空状态走完办文,不借 WS 桩
WS-X05 P1 腾讯云单机迁移、备份恢复、manifest 对账 云主机/存储 恢复后 A/B 事项、附件、版本和 hash 与迁移前一致
WS-X06 P2 麒麟 V10 SP3 + 海光目标机实测 目标硬件/OS/依赖包 同一合同及隔离脚本通过,记录 CPU/OS/包版本及失败项

P0 出门条件:WS01-01~08、WS02-01~04、WS03-01~05、WS04-01~06、WS-X01~04 全通过。其他模块仍为桩时,报告逐项标注;Workspace 自身不得替换为桩。P1/P2 不阻挡 10 月 18 日前 PC 演示,但不得标为已完成。