From 167deae0b3cc3f7857ac6cc82b2603b7e966ecdf Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 14 Jul 2026 06:19:58 +0200 Subject: [PATCH] docs: define PikaOA global resource ids --- docs/MDTODO/pikaoa-enterprise-platform.md | 8 ++++ .../PJ2026-03/specs/PJ2026-03-pikaoa.md | 39 +++++++++++++++---- 2 files changed, 39 insertions(+), 8 deletions(-) diff --git a/docs/MDTODO/pikaoa-enterprise-platform.md b/docs/MDTODO/pikaoa-enterprise-platform.md index 8e3fc65b..1a33dd57 100644 --- a/docs/MDTODO/pikaoa-enterprise-platform.md +++ b/docs/MDTODO/pikaoa-enterprise-platform.md @@ -37,6 +37,14 @@ #### R1.3.4 [completed] 实现 pgx 同事务审计、PostgreSQL outbox、Watermill handler pipeline、幂等 Worker 与 OTel/Prometheus，执行记录见 [pikasTech/unidesk#1985](https://github.com/pikasTech/unidesk/issues/1985)，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.3.4_Task_Report.md)。 +#### R1.3.5 + +实现统一业务伙伴、甲方分类、角色、联系人、标签、归档、筛选和 CLI；持久化 REST 资源使用 UUIDv7，伙伴与分类只通过 typed ID 关联，并将业务、审计、outbox 保持同事务，执行记录见 [pikasTech/unidesk#1990](https://github.com/pikasTech/unidesk/issues/1990)，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.3.5_Task_Report.md)。 + +#### R1.3.6 + +实现统一附件元数据、对象引用、可替换存储端口、完整性校验、授权 API 和 CLI；附件使用 UUIDv7 平级资源身份，业务对象仅通过 typed ID 关联，执行记录见 [pikasTech/unidesk#1991](https://github.com/pikasTech/unidesk/issues/1991)，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.3.6_Task_Report.md)。 + ### R1.4 在 R1.3 CLI 后端验收通过后实现 HWLAB v0.3 同族 Vue 工作台、响应式页面与同路径业务流，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.4_Task_Report.md)。 diff --git a/project-management/PJ2026-03/specs/PJ2026-03-pikaoa.md b/project-management/PJ2026-03/specs/PJ2026-03-pikaoa.md index acda64e5..55fe8d79 100644 --- a/project-management/PJ2026-03/specs/PJ2026-03-pikaoa.md +++ b/project-management/PJ2026-03/specs/PJ2026-03-pikaoa.md @@ -5,6 +5,7 @@ | 版本 | 对应 commit id | 更新日期 | 变更说明 | | --- | --- | --- | --- | | v0.1 | 待本版本提交 | 2026-07-13 | 创建企业办公平台预期终态、模块架构和首批合同与发票能力规格。 | +| v0.2 | 待本版本提交 | 2026-07-14 | 统一平级 REST 资源、UUIDv7 全局标识和仅通过 typed ID 建立对象关联的契约。 | 修改历史只记录规格语义变更，不记录实现进度、阶段基线或一次性证据。 @@ -56,7 +57,8 @@ PikaOA 终态必须同时具备： - 统一员工身份、组织成员、角色、权限和会话； - 统一业务伙伴、分类、标签、联系人和归档状态； - 统一附件、审计、模块注册、搜索和分页契约； - - 统一 API 错误、字段校验和幂等写入语义。 + - 统一 API 错误、字段校验和幂等写入语义； + - 统一持久化 REST 资源的 UUIDv7 全局标识和 typed ID 关联语义。 - CLI-first 交付： - 每个后端业务用例先提供稳定 CLI 入口； - CLI 与 Web 复用同一 HTTP API、身份、权限和业务语义； @@ -114,10 +116,11 @@ PikaOA 终态必须同时具备： | 普通员工 | 可以使用被授予模块能力但不能管理系统身份与权限的员工角色。 | | 业务伙伴 | 与公司发生业务关系的外部组织或个人；甲方是业务伙伴的一种业务角色。 | | 甲方分类 | 用于组织、筛选和汇总甲方的可维护分类。 | -| 合同主记录 | 表示一份合同长期身份、甲方、编号、状态和当前版本指针的聚合根。 | -| 合同版本 | 合同在某一时点的不可变业务内容快照，具有合同内单调递增的版本号。 | +| 合同主记录 | 表示一份合同长期身份、甲方、编号、状态和当前版本 ID 指针的独立业务资源。 | +| 合同版本 | 具有全局唯一 ID 的独立业务资源，通过合同 ID 和前一版本 ID 建立关联，并具有合同内单调递增的版本号。 | | 当前版本 | 合同主记录明确指向、供默认查询和新关联使用的合同版本。 | | 发票废弃 | 保留发票记录并记录废弃人、时间和原因，使其不再计入有效业务结果。 | +| Typed ID 关联 | 资源只保存关联对象的资源类型和全局唯一 ID，不复制关联对象私有载荷，也不以嵌套路径或表级从属关系定义资源身份。 | | 模块 | 具有独立领域边界、权限、迁移、API、事件和前端入口的可插拔业务能力。 | | 领域事件 | 模块完成业务事务后写入的结构化事实，用于同进程订阅或异步扩展。 | @@ -158,6 +161,13 @@ PikaOA 终态必须同时具备： - 审计动作、资源类型和可安全披露的变更摘要； - 健康、迁移和部署后验证入口。 +所有持久化 REST 资源必须遵循统一对象契约： + +- 由服务端生成不可变 UUIDv7，业务编号、名称、版本号和外部标识不得充当资源主键； +- 伙伴、合同、合同版本、发票和附件等资源在 REST、领域模型和存储层均保持平级身份； +- 关联只使用 typed ID 字段或显式关联记录，不使用嵌套 REST 路径、级联从属对象或复制载荷形成第二关系真相； +- 删除、归档、废弃或改名不得改变其他资源的 ID，也不得使历史关联失效。 + 新增模块不得通过修改其他模块私有表完成集成。跨模块读取使用应用端口或稳定对象引用；异步扩展使用事务内写入的领域事件/outbox，不新增第二业务真相。 ## 5. 目标架构和数据流 @@ -304,7 +314,11 @@ PikaOA 必须以第 4.3 节的模块接入合同组织业务能力。模块必 ### 6.4 PIKAOA-L0-REQ-004 合同多版本 -每份合同必须有稳定主记录和一个或多个不可变版本。合同内版本号单调递增；创建新版本必须保留旧版本、更新当前版本指针并记录变更说明、操作者和时间。 +- 每份合同和每个合同版本都是具有独立 UUIDv7 的平级 REST 资源； +- 合同版本通过 `contractId` 关联合同，并通过可选 `previousVersionId` 关联前一版本； +- 合同通过 `currentVersionId` 关联当前版本； +- 合同内版本号单调递增，但版本号不得充当资源主键； +- 创建新版本必须保留旧版本、更新当前版本 ID 指针并记录变更说明、操作者和时间。 每个版本至少包含： @@ -317,13 +331,18 @@ PikaOA 必须以第 4.3 节的模块接入合同组织业务能力。模块必 接受标准包括： - 详情默认显示当前版本并可查看全部历史版本； +- 任一版本可以通过 `/api/v1/contract-versions/{id}` 独立读取，版本关系只由 ID 字段表达； - 历史版本不可被当前编辑覆盖； - 并发创建相同下一版本时只能有一个事务成功； - 合同可以按甲方、分类、编号、状态和日期筛选。 ### 6.5 PIKAOA-L0-REQ-005 发票管理和废弃 -发票必须支持号码、类型、开票日期、金额、税额、价税合计、币种、甲方、合同和可选合同版本关联。发票不得物理删除；废弃动作必须保留原记录，并记录废弃人、废弃时间和非空原因。 +- 发票是具有独立 UUIDv7 的平级 REST 资源； +- 发票通过 `partnerId`、可选 `contractId` 和可选 `contractVersionId` 建立关联； +- 发票必须支持号码、类型、开票日期、金额、税额、价税合计和币种； +- 发票不得物理删除； +- 废弃动作必须保留原记录，并记录废弃人、废弃时间和非空原因。 接受标准包括： @@ -335,7 +354,10 @@ PikaOA 必须以第 4.3 节的模块接入合同组织业务能力。模块必 ### 6.6 PIKAOA-L0-REQ-006 附件完整性 -合同版本和发票可以关联附件。附件元数据必须记录原文件名、媒体类型、字节数、内容哈希、存储键、上传人和上传时间。存储实现通过端口替换，业务表不保存宿主绝对路径。 +- 附件是具有独立 UUIDv7 的平级 REST 资源； +- 合同版本和发票通过显式 typed ID 关联记录引用附件，不把附件作为嵌套从属对象； +- 附件元数据必须记录原文件名、媒体类型、字节数、内容哈希、存储键、上传人和上传时间； +- 存储实现通过端口替换，业务表不保存宿主绝对路径。 接受标准包括： @@ -433,11 +455,12 @@ Web、API、Worker 和 CI/CD 必须输出结构化日志、健康状态和 trace - 外部 HTTP API 使用 `/api/v1` 版本前缀。 - 模块路由使用稳定复数资源名和标准分页参数。 - 写请求返回稳定业务错误码、字段路径和可读消息。 -- ID 使用不可枚举、全局唯一的稳定标识。 +- 所有持久化 REST 资源 ID 使用服务端生成、不可枚举、不可变的 UUIDv7。 +- 集合和单资源路径使用平级复数资源名，例如 `/api/v1/contracts/{id}`、`/api/v1/contract-versions/{id}` 和 `/api/v1/invoices/{id}`；嵌套路径只可作为有界查询入口，不得成为资源唯一身份。 - 时间以 UTC 保存并在用户界面按配置时区显示。 - 金额使用定点十进制语义，不使用二进制浮点保存。 - 数据库迁移单向、版本化、可审计；应用启动不静默修改未知结构。 -- 跨模块对象引用包含资源类型和稳定 ID，不复制私有载荷。 +- 跨模块对象引用包含资源类型和 UUIDv7，只建立 ID 关联，不复制私有载荷或形成对象隶属真相。 - 兼容归一化只处理可安全解释的旧字段；不可解释业务数据返回字段级错误。 ## 8. 全局验收契约