docs: define PikaOA global resource ids
This commit is contained in:
Codex
@@ -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)。
|
||||
|
||||
@@ -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. 全局验收契约
|
||||
|
||||
Reference in New Issue
Block a user