Spaces:
Sleeping
Sleeping
|
Download docs/11_Workspace_Service/README.md from dellweb3/workos-office: direct link, hf CLI and curl.
- Browser
- Download file 28.9 kB
-
https://huggingface.co/spaces/dellweb3/workos-office/resolve/main/docs/11_Workspace_Service/README.md
- Command line
-
hf download hf://spaces/dellweb3/workos-office/docs/11_Workspace_Service/README.md
-
curl -L -o README.md https://huggingface.co/spaces/dellweb3/workos-office/resolve/main/docs/11_Workspace_Service/README.md
28.9 kB
| # Work OS MVP · Workspace Service 系统架构与功能设计 v1.0 | |
| > 状态:设计基线,已有首版 PC 持久化实现;与全部需求清单的完成状态请看 [实现说明](../../WorkspaceService/README.md)。日期:2026-10-10。目标:2026-10-18 前完成 PC 演示,随后腾讯云验收,再验证银河麒麟/海光。配套资料:[总体设计](../06_系统设计文档.md)、[API Gateway 设计及 OpenAPI](../10_API_Gateway/README.md)、[细化任务表](../03_细化任务与依赖表.md)。原 Gateway 演示桩已替换为 [Workspace 首版代码](../../WorkspaceService/README.md);目前 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. 系统架构、技术栈与小模块 | |
| ```mermaid | |
| 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](../10_API_Gateway/openapi.json) 为字段、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](../10_API_Gateway/openapi.json)同步定义。 | |
| ### 3.2 内部 Port 代码骨架 | |
| ```python | |
| @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. 数据模型和关键不变量 | |
| ```mermaid | |
| 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 的[官方行锁文档](https://www.postgresql.org/docs/current/explicit-locking.html)支撑同一聚合的串行化。分库后不承诺跨库本地事务,改用 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 文档](https://min.io/docs/minio/linux/index.html)是适配依据,具体产品部署时再选并实测。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](../09_架构契约/event-envelope.schema.json):后者强制 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 腾讯云沿用[两阶段部署方案](../07_两阶段部署与成本.md)的 4 vCPU/8 GiB 单机、PostgreSQL 与受限数据盘或 S3 兼容存储;Qwen 继续走公网 API,Workspace 不另购 GPU。实际费用按部署方案及购买时价格复核。 | |
| **国产化**:银河麒麟 V10 SP3 官方资料列出[海光平台支持](https://www.kylinos.cn/productPc/server/serverMain/additional),但不表示 Python native wheel 已在目标环境验证。迁移时记录具体 OS/CPU 版本,实测 Python、psycopg、pydantic-core、cryptography、libpq/TLS、PostgreSQL、文件权限、systemd;运行相同 Alembic 迁移、接口合同、双用户越权、附件 hash、并发版本与备份恢复。容器镜像也须在目标机实测架构及运行时。PostgreSQL 方言封装于 Repository;不假设国产数据库零代码替换。国密/等保要求待客户定级和产品选型,不宣称 P0 已达标。 | |
| ## 6. 办文工作流示例:Workspace 如何运行 | |
| ```mermaid | |
| 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](../10_API_Gateway/openapi.json)为准。 | |
| ```http | |
| 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年度培训通知"} | |
| ``` | |
| ```json | |
| {"workspace_id":"ws-a-01","parent_id":"home-a","title":"2026年度培训通知","version":1,"status":"new"} | |
| ``` | |
| ```http | |
| PATCH /api/v1/artifacts/art-a-01 HTTP/1.1 | |
| Authorization: Bearer <token-for-user-a> | |
| Content-Type: application/json | |
| {"content":"关于开展年度培训的通知……","expected_version":1} | |
| ``` | |
| ```json | |
| {"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、正文、路径或内网地址。 | |
| ```json | |
| {"code":"artifact_version_conflict","message":"草稿已更新,请刷新后重试","trace_id":"tr-001","details":{"current_version":2}} | |
| ``` | |
| ## 8. 开发顺序与验证方式 | |
| 沿用[任务表 W01–W08](../03_细化任务与依赖表.md)的依赖链: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](../10_API_Gateway/openapi.json)、[总体架构与 Run 事件契约](../09_架构契约/README.md)、[PostgreSQL 官方行锁文档](https://www.postgresql.org/docs/current/explicit-locking.html)、[麒麟 V10 SP3 平台信息](https://www.kylinos.cn/productPc/server/serverMain/additional)、[MinIO S3 接口文档](https://min.io/docs/minio/linux/index.html)。 | |
| ## 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 演示,但不得标为已完成。 | |