docs(P19-1,P19-2,P19-3,P19-4): 冻结事件清单与集成边界

2026-03-07 23:23:34 +08:00
@@ -0,0 +1,63 @@
+# 领域事件清单（P19 冻结版）
+
+**快照日期**：2026-03-07  
+**目标**：冻结 `hyb-oa` 当前采购与资产域对外发布的标准事件名称、触发时机与最小载荷，为未来 ERP / IM / AI 适配提供统一事实源。
+
+## 1. 使用原则
+- 本文档只定义**领域事件名与边界**，不代表当前已实现事件总线。
+- 未来若落地 Outbox / webhook / MQ，事件名与载荷应保持向后兼容。
+- 事件仅表达“已经发生的领域事实”，不表达待办命令。
+
+## 2. 标准事件清单
+
+| 事件名 | 触发时机 | 领域对象 | 最小载荷字段 | 推荐消费者 | 备注 |
+| --- | --- | --- | --- | --- | --- |
+| `purchase_request.submitted` | 采购申请提交成功后 | `purchase_request` | `purchaseRequestId`, `requestNo`, `applicantId`, `departmentId`, `legalEntityId`, `costCenterId`, `supplierId`, `budgetPoolId`, `totalAmount`, `status` | IM 通知、ERP 预处理、AI 摘要 | 仅表示进入 `reviewing` |
+| `purchase_request.approved` | 采购申请审批通过后 | `purchase_request` | `purchaseRequestId`, `requestNo`, `approvedBy`, `legalEntityId`, `costCenterId`, `supplierId`, `budgetPoolId`, `totalAmount`, `status` | ERP、IM、AI | 对应预算 `confirm` 已完成 |
+| `purchase_request.rejected` | 采购申请审批驳回后 | `purchase_request` | `purchaseRequestId`, `requestNo`, `actorId`, `reason`, `status` | IM、AI | 若存在预算预留，应已释放 |
+| `purchase_request.withdrawn` | 申请人撤回采购申请后 | `purchase_request` | `purchaseRequestId`, `requestNo`, `actorId`, `status` | IM、AI、ERP 补偿 | 表示由 `reviewing` 回到 `draft` |
+| `asset.card.created` | 资产卡片创建成功后 | `asset_card` | `assetId`, `assetNo`, `name`, `categoryId`, `legalEntityId`, `costCenterId`, `purchaseRequestId`, `status` | ERP、IM、AI | 资产域不接 workflow |
+| `asset.assigned` | 资产领用成功后 | `asset_card` | `assetId`, `assetNo`, `employeeId`, `assignedAt`, `location`, `status` | IM、AI | 对应新增 open assignment |
+| `asset.returned` | 资产归还成功后 | `asset_card` | `assetId`, `assetNo`, `employeeId`, `returnedAt`, `location`, `status` | IM、AI | 对应关闭 open assignment |
+| `asset.transferred` | 资产调拨成功后 | `asset_card` | `assetId`, `assetNo`, `fromEmployeeId`, `toEmployeeId`, `fromLocation`, `toLocation`, `transferredAt`, `status` | ERP、IM、AI | 可只改位置，不一定改归属人 |
+| `inventory_check.completed` | 盘点任务完成后 | `inventory_check` | `inventoryCheckId`, `checkNo`, `scopeType`, `scopeRefId`, `completedAt`, `itemCount`, `summary` | ERP、IM、AI | `summary` 建议包含 matched/missing/extra/damaged 计数 |
+
+## 3. 事件名与运行时对象映射
+
+| entityType | 推荐事件前缀 | 当前事实源 |
+| --- | --- | --- |
+| `purchase_request` | `purchase_request.*` | `P17A` / `P17B` |
+| `asset_card` | `asset.*` | `P18A` / `P18B` |
+| `inventory_check` | `inventory_check.*` | `P18B` |
+
+## 4. 最小 Envelope 建议
+
+未来若落地事件投递，建议统一使用如下 envelope：
+
+```json
+{
+  "eventName": "purchase_request.submitted",
+  "eventId": "uuid",
+  "occurredAt": "2026-03-07T23:22:00+08:00",
+  "actorId": "user-id",
+  "entityType": "purchase_request",
+  "entityId": "entity-id",
+  "payloadVersion": 1,
+  "payload": {}
+}
+```
+
+## 5. 兼容性规则
+- 事件一旦对外承诺，名称不得随意修改。
+- 新增字段必须保持向后兼容；删除字段需要单独版本升级。
+- 载荷字段命名应与 HTTP camelCase 输出保持一致，不直接暴露数据库 snake_case 列名。
+
+## 6. 明确不纳入 P19 的事件
+- `purchase_request.archived`：待未来需要对接采购归档通知时再冻结
+- `inventory_check.started`：当前不作为外部关键事实源
+- `asset.repaired` / `asset.retired`：待未来维修/报废专项后再定义
+
+## 7. 推荐的首批消费场景
+- IM：采购提交、采购审批结果、资产领用归还、盘点完成提醒
+- ERP：采购审批通过摘要、资产卡片新增摘要、盘点完成摘要
+- AI：审批摘要、异常提示、主数据重复建议、盘点结果总结