7.0 KiB
7.0 KiB
实施计划：审批退回结果通知缺失治理
实施顺序
- 在通知类型常量中新增
leave.returned、purchase_request.returned、travel_request.returned，加入 IM 支持表和领域映射。 - 扩展 workflow returned outcome 映射；不改 return 路由事务、状态、释放、allowedActions 或其他 outcome。
- 补齐纯函数测试：逐个断言三个新类型在类型对象、IM 支持清单、领域映射三处注册完整，并覆盖五类 returned 矩阵及四类“可修改后重新提交”文案/摘要/deeplink。
- 补齐 route/side-effect 测试：三类站内通知、收件人去重、email task、IM dispatch task、失败不回滚；若现有 harness 不足，只提取最小可测试编排 helper，不改变运行时职责。
- 补齐 IM routing 和通知渠道 schema 测试：三种新类型的允许/拒绝矩阵，既有类型不漂移。
- 回归报销 returned、所有 approved/rejected、请假额度释放、采购/差旅预算释放、补卡无 return 和通知失败容错。
- 更新
docs/领域事件清单.md、docs/集成边界.md与.trellis/spec/hyb-oa/approval-workflow.md，只沉淀稳定 notification type 和副作用合同。 - 完成本地质量门禁与只读 review。此任务涉及 workflow 和生产路由，reviewer 不得改代码。
- 分别取得 commit、push、部署授权后发布代码候选；部署前不修改生产 routing。
- 代码生产验收通过后，另行请求生产配置写入授权；按脱敏快照、有效矩阵 diff、管理 API PATCH、读回、审计顺序放行 routing。
- 只有出现自然 return 或取得受控生产数据写入授权后才做真实两渠道验收；否则明确记录
BLOCKED。
风险文件
server/src/constants/notificationTypes.js：共享通知枚举与路由白名单，任何遗漏都会造成站内有通知但 IM 被静默跳过。server/src/routes/workflow.js：五类审批共用，必须只扩展 returned 类型映射。server/src/routes/notifications.js：管理 API schema 由支持清单生成，需证明新 routing 可写且旧配置兼容。server/src/services/notifications/imRouting.js：原则上不改；测试需证明三维过滤仍是 AND 关系。docs/领域事件清单.md与docs/集成边界.md：必须区分运行时 notification type 与领域 Outbox 事件，不能误写成新增消息总线事件。
预期验证命令
cd server && npm run prisma:validate
cd server && node --check src/constants/notificationTypes.js
cd server && node --check src/routes/workflow.js
cd server && npm test -- tests/unit/constants/notificationTypes.test.js tests/unit/routes/workflow.travel.test.js
cd server && npm test -- tests/unit/services/imRouting.test.js tests/unit/services/imEnqueue.test.js tests/unit/services/notificationDispatcher.test.js
cd server && npm test -- tests/unit/routes/notifications.test.js
cd server && npm test -- tests/unit/routes/workflow.permissions.test.js tests/unit/routes/workflow.batch.test.js
node scripts/qa/check-process-contract.mjs --baseline --json
node scripts/qa/audit-docs.mjs --check-registry
node scripts/qa/check-trellis-governance.mjs
python3 ./.trellis/scripts/task.py validate 09-04-approval-return-notification-gap
git diff --check
实施时若新增聚焦 route test 文件，将其追加到命令，不用扩大为无关全仓测试来掩盖缺口。
Review 清单
- 三种新类型是否在
NOTIFICATION_TYPES、IM_SUPPORTED_NOTIFICATION_TYPES、领域映射三处注册齐全，且三种渠道全部由resolveWorkflowOutcomeNotificationType的同一返回值驱动。 - 三类收件人与 deeplink 是否复用现有实体元数据且正确去重。
- 通知异常是否仍不回滚状态、history、假期或预算释放。
- 报销 returned、其他 outcome、补卡和 allowedActions 是否零变化。
- 生产 routing 变更是否被留在部署后独立授权阶段，代码或脚本中没有静默改生产配置。
- 日志、测试 fixture、task 与证据中是否无真实人员、单据、通知正文、外部 ID、Secret 或原始 payload。
- 退回通知是否明确“可修改后重新提交”，且没有复用驳回措辞。
提交与部署边界
- commit message 使用中文并引用
09-04-approval-return-notification-gap。 - 实施完成后先交 diff 与只读 review 结果；用户批准后才能提交。
- commit、push、应用部署、生产 routing 写入、受控生产单据创建/退回分别授权，不合并推定。
- 代码阶段无 migration、schema、seed、flag 或生产数据改动。
生产验收清单
代码候选
- provenance、工作区与候选 SHA 一致；部署前现有 routing 只读快照未变化。
/ready返回候选短 SHA；服务端日志无新类型/领域解析错误。- 报销 returned、approved/rejected、待办及五类审批 smoke 正常。
- 生产渠道配置在独立授权前仍不放行三种新类型。
routing 配置
- 变更前保存脱敏 routing 快照和有效允许矩阵。
- 管理 API PATCH 只增加三个 type 与所需 domain；其他配置不变。
- 变更后读回值、有效矩阵与审计记录一致，新增有效能力严格等于目标三种 returned。
- 回滚演练至少完成静态命令与快照核对；不得为了演练反复写生产。
真实事件
- 目标用户站内只收到一份“已退回”通知，意见、目标类型和目标 ID 正确。
- 企业微信 delivery 成功，真机收到消息并可点击回到有权限的 OA 页面。
- 通知结果与业务对象 draft、workflow returned/history 以及假期/预算释放一致。
- 无真实样本或授权时记录
BLOCKED，不标记 PASS。
本地实施结果（2026-09-04）
- 已完成三个 returned 通知类型、IM 支持清单和领域映射的同步注册；管理 API schema 测试保留既有
workflow.task_assigned覆盖并新增三个 returned 值。 - 已由统一 workflow outcome 投影生成三类站内通知、email task 与 IM dispatch task；退回正文统一明确“已退回，可修改后重新提交”。
- 已增加 route 级容错回归：站内通知创建抛错时，接口仍成功，task 为
completed/returned、业务对象回draft、return history 保留。 - 产品状态机、allowedActions、假期/预算释放分支、Prisma schema、前端和生产 routing 均未修改。
- 聚焦通知测试 53/53、全部 workflow route 测试 49/49、假期/预算服务测试 14/14 通过；Prisma validate、Node syntax、process contract、Trellis governance、task validate、docs registry 检查和
git diff --check通过。 - 全量后端测试为 1384/1387 通过；三条失败均来自当前环境缺少受控 BIFF8 生成依赖
xlwt，集中在付款指令导出测试，与本任务改动文件和通知/workflow 路径无关。聚焦重跑全部通过，未修改或弱化这三条断言。 - AC9–AC11 尚未执行：未 commit、未 push、未部署、未写生产 routing，也未创建或退回生产测试单。真实企业微信送达继续保持未验证。