wangsli/hyb-oa
1
0
派生 0
代码 工单 合并请求 工作流 8 软件包 项目 发布 百科 活动

WADM1 设计企微自建留存数据模型

浏览代码
这个提交包含在：
wangsli
2026-05-19 22:26:07 +08:00
父节点 bc5a3ccd0a
当前提交 0c8fbe4ff3
共修改 12 个文件，包含 178 行新增和 33 行删除
下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件
docs/需求-统一审批中心规约.md
+42 -3
查看文件
@@ -5,7 +5,7 @@
**状态**：模块级开发规约
**上级事实源**：[海音达OA-MVP需求规格说明书](./海音达OA-MVP需求规格说明书.md)
本规约细化 `hyb-oa` 审批中心和企业微信原生审批镜像的产品边界、角色权限、状态模型、异常规则、留痕要求和验收场景。WFOC 起，审批按主办方分层；DBWFOC 后边界进一步收窄：报销、财务、采购、合同和项目类审批继续由 OA 主办；请假、补卡、外出、加班等 HR/考勤员工日常审批优先由企业微信主办，OA 同步按域镜像并保留自建历史留存、人工接管和恢复回写能力。WMSG1 已验证企业微信应用消息和 Deeplink 回流，WAPC1 后审批镜像前置工作进入配置准备清单阶段，WAPC2 已提供请假/补卡只读 POC runner，WAPC2FLIVE 已自动生成请假/补卡 OA-POC 样件并复跑通过。WCBK1 已完成只读回调 URL 验证和真实审批事件确认，结论为 `PASS_CALLBACK_EVENT_CONFIRMED`。WEGOV1 后明确先利用企微成熟审批和考勤能力，同时由 OA 保存关键历史和外部关联键。WACP3R 已自动发现 OA-POC 请假/补卡模板并公网复跑到 `PASS_WITH_FINDINGS`：补偿拉取和详情读取可用，finding 是回调证据文件未持久化。WREAD1F 后已完成请假/补卡真机可读性确认：消息卡片、列表、详情页均可看清，远端报告 `/app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T133628Z/summary.json` 为 `PASS_READABLE`；但同意按钮单击即通过，需在 WADM1/WARCH1 的审计留存、提示或操作规程中处理。后续仍必须完成 WADM1 自建留存/镜像数据模型设计和 WARCH1 最小历史留存，不能直接放行镜像实现。后续审批相关开发必须先从本规约拆分 Issue CSV，再进入技术方案和代码实现。
本规约细化 `hyb-oa` 审批中心和企业微信原生审批镜像的产品边界、角色权限、状态模型、异常规则、留痕要求和验收场景。WFOC 起，审批按主办方分层；DBWFOC 后边界进一步收窄：报销、财务、采购、合同和项目类审批继续由 OA 主办；请假、补卡、外出、加班等 HR/考勤员工日常审批优先由企业微信主办，OA 同步按域镜像并保留自建历史留存、人工接管和恢复回写能力。WMSG1 已验证企业微信应用消息和 Deeplink 回流，WAPC1 后审批镜像前置工作进入配置准备清单阶段，WAPC2 已提供请假/补卡只读 POC runner，WAPC2FLIVE 已自动生成请假/补卡 OA-POC 样件并复跑通过。WCBK1 已完成只读回调 URL 验证和真实审批事件确认，结论为 `PASS_CALLBACK_EVENT_CONFIRMED`。WEGOV1 后明确先利用企微成熟审批和考勤能力，同时由 OA 保存关键历史和外部关联键。WACP3R 已自动发现 OA-POC 请假/补卡模板并公网复跑到 `PASS_WITH_FINDINGS`：补偿拉取和详情读取可用，finding 是回调证据文件未持久化。WREAD1F 后已完成请假/补卡真机可读性确认：消息卡片、列表、详情页均可看清，远端报告 `/app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T133628Z/summary.json` 为 `PASS_READABLE`；但同意按钮单击即通过，需在 WARCH1 的审计留存、提示或操作规程中处理。WADM1 已完成自建留存/镜像数据模型设计；后续仍必须完成 WARCH1 最小历史留存，不能直接放行镜像实现。后续审批相关开发必须先从本规约拆分 Issue CSV，再进入技术方案和代码实现。
---
@@ -355,7 +355,7 @@ WF8-3、WF8-4、WF8-5 实现前必须基于本设计给技术方案；实现后
- 采购单附件、合同正文、报价、供应商资料、发票、银行回单、代账资料和其他高敏附件不进入企业微信原生审批或企业微信附件；企业微信只做提醒、deeplink 和免登录回流。
- 按域镜像是默认规则：企微主办 HR/考勤域镜像到 OA；OA 主办采购、合同、项目、财务和报销域不反向全量镜像到企微。
- WFDG 后，审批相关页面和接口必须区分 `OA 主办`、`企微镜像` 和 `OA 应急接管`；企微镜像不得被误用为 OA 日常新建入口，OA 应急接管单据必须带 `EMERGENCY` 并进入恢复回写队列。
- WAPI/WRRA/WOUA-FIX/WAPC1/WAPC2/WPROC1/WEGOV1 后，审批相关运行时迁移必须先读 [企微优先开发路线图](./企微优先开发路线图.md) 和 [企微 API 能力目录](./企微API能力目录.md)，按 `wecom_hr_master_sync_v1` -> `runtime_first_wecom_enablement` -> `WOUA-FIX / WECOM-RUNTIME-READY-V1` -> `WAPC1 审批配置准备` -> `WAPC2 请假/补卡只读 POC` -> `WAPC2F 自动生成 POC 样件` -> `WAPC2FLIVE live 创建与 WAPC2 自动复跑` -> `WCBK1 回调只读 POC` -> `WEGOV1 企微主办治理与自建留存路线修正` -> `WACP3/WACP3R 补偿拉取 POC` -> `WREAD1 审批可读性与误审批防护门禁` -> `WADM1 自建留存/镜像数据模型设计` -> `WARCH1 最小自建历史留存实现` -> `wecom_attendance_approval_mirror_v1` -> `oa_hr_emergency_mode_v1` -> `wecom_recovery_writeback_v1` 的顺序拆单功能 Issue CSV；WOUA-FIX 只收口了用户一致性测试账号差异和处理决策，WRV1/WRA1/WMSG1 只验证入口、OAuth/绑定、脱敏消息、deeplink、通讯录、人事助手、打卡只读主链路和真实消息回流。WAPC1 只固化审批配置准备清单；WAPC2 只读模板详情和低风险 `sp_no` 审批详情；WAPC2FLIVE 只生成 OA-POC 低风险测试样件并自动复跑只读 POC；WCBK1 只证明真实审批状态回调可验签、可解密、可脱敏留证；WACP3R 只证明补偿拉取和详情读取可用，并发现回调证据文件未持久化；WEGOV1 只修正混合主办、自建留存和测试治理口径；WREAD1 只证明请假/补卡当前样例可读，不代表自建留存或镜像实现完成。自建留存模型和最小历史留存未明确前，不得直接开发企微审批镜像或恢复回写。
- WAPI/WRRA/WOUA-FIX/WAPC1/WAPC2/WPROC1/WEGOV1 后，审批相关运行时迁移必须先读 [企微优先开发路线图](./企微优先开发路线图.md) 和 [企微 API 能力目录](./企微API能力目录.md)，按 `wecom_hr_master_sync_v1` -> `runtime_first_wecom_enablement` -> `WOUA-FIX / WECOM-RUNTIME-READY-V1` -> `WAPC1 审批配置准备` -> `WAPC2 请假/补卡只读 POC` -> `WAPC2F 自动生成 POC 样件` -> `WAPC2FLIVE live 创建与 WAPC2 自动复跑` -> `WCBK1 回调只读 POC` -> `WEGOV1 企微主办治理与自建留存路线修正` -> `WACP3/WACP3R 补偿拉取 POC` -> `WREAD1 审批可读性与误审批防护门禁` -> `WADM1 自建留存/镜像数据模型设计` -> `WARCH1 最小自建历史留存实现` -> `wecom_attendance_approval_mirror_v1` -> `oa_hr_emergency_mode_v1` -> `wecom_recovery_writeback_v1` 的顺序拆单功能 Issue CSV；WOUA-FIX 只收口了用户一致性测试账号差异和处理决策，WRV1/WRA1/WMSG1 只验证入口、OAuth/绑定、脱敏消息、deeplink、通讯录、人事助手、打卡只读主链路和真实消息回流。WAPC1 只固化审批配置准备清单；WAPC2 只读模板详情和低风险 `sp_no` 审批详情；WAPC2FLIVE 只生成 OA-POC 低风险测试样件并自动复跑只读 POC；WCBK1 只证明真实审批状态回调可验签、可解密、可脱敏留证；WACP3R 只证明补偿拉取和详情读取可用，并发现回调证据文件未持久化；WEGOV1 只修正混合主办、自建留存和测试治理口径；WREAD1 只证明请假/补卡当前样例可读；WADM1 只完成模型设计，不代表历史留存或镜像实现完成。WARCH1 最小历史留存未实现前，不得直接开发企微审批镜像或恢复回写。
- WRV1/WRA1 runner `npm run check:wecom-runtime-ready` 中的审批模板、测试 `sp_no` 和真实回调检查只允许输出 `NEEDS_CONFIG`；这类缺口不阻断运行优先主链路的 `PASS_WITH_CONFIG_GAPS`，但必须阻断 `wecom_attendance_approval_mirror_v1`、应急恢复回写和 RuleOps。`WECOM_CHECKIN_SYNC_ENABLED` 只控制正式考勤同步批次，不阻断 QA-only 打卡只读能力探测。
- WMSG1 已证明企业微信应用消息可达和 Deeplink 可进入 OA 通知页；该证据只清除通知链路，不清除审批模板、测试 `sp_no` 或真实回调前置。WAPC1 固化配置准备清单后，WAPC2 先提供请假/补卡模板详情和低风险审批详情只读 POC；WPROC1 后优先用 WAPC2F 自动生成 POC 样件，不默认要求人工手动创建模板或测试单。人工介入限于写入批准、密钥/回调配置、企微后台无法 API 化配置、真机确认和风险拍板。
- 后续企微审批同步的 POC 必须输出 `CAN_REUSE_NOW`、`NEEDS_CONFIG`、`NEEDS_API_POC`、`KEEP_OA_PRIMARY`、`NOT_SUPPORTED_BY_API`，缺模板、回调、Secret 或权限时记录 `SKIP/BLOCKED_BY_EXTERNAL_CONFIG`。
@@ -418,9 +418,48 @@ WAPC2F 是 WAPC2 后的自动化优先补缺阶段，目标是尽量用 QA-only
- `WEGOV1 企微主办治理与自建留存路线修正`：固定企微主办域、OA 主办域、OA 留存域和 OA 应急域；明确企业微信没有完整 sandbox 假设，默认使用受控测试域和自动化 runner。
- `WACP3 补偿拉取 POC`：已新增 `check:wecom-approval-compensation-poc` 和 `getapprovalinfo` 只读封装；WACP3R 公网复跑为 `PASS_WITH_FINDINGS`，已按 `SMOKE002` creator 自动发现请假/补卡 OA-POC 模板并拉取审批详情。finding 为回调证据文件未持久化，需在 WADM1/WARCH1 的自建留存模型中解决。
- `WREAD1 审批可读性与误审批防护门禁`：已新增 `check:wecom-approval-readability-gate` 只读 runner，并在 WREAD1F 新样例后完成真机确认。公网人工结果报告 `/app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T133628Z/summary.json` 为 `PASS_READABLE`：请假和补卡消息卡片、审批列表、详情页足够看清；驳回有二次确认，同意单击即通过。后续不要求回退 OA 主办，但需在 WADM1/WARCH1 中处理单击同意的审计和操作提示风险。
- `WADM1 自建留存/镜像数据模型设计`：先设计字段、状态机、幂等键、索引、隐私保留、审计和迁移回滚方案。
- `WADM1 自建留存/镜像数据模型设计`：已完成字段、状态机、幂等键、索引、隐私保留、审计和迁移回滚方案设计；本阶段不改 schema、不写业务代码。
- `WARCH1 最小自建历史留存实现`：先只读保存企微审批、打卡和人事关键快照，保证企微不可用时可查看历史，再进入完整镜像增强。
### 9.4.1 WADM1 自建审批留存模型
WADM1 只做模型设计，不修改 Prisma schema。后续 WARCH1 才能在单独合同中创建迁移和写入路径。
企微主办审批进入 OA 自建留存时，建议按以下模型拆分：
| 设计模型 | 职责 | 必要字段 |
| --- | --- | --- |
| `WecomApprovalArchive` | 审批单主表，表示一条企微审批在 OA 的历史事实 | `sp_no`、`template_id`、`template_type`、规范化状态、企微原状态码、申请人 OA 员工、申请人企微 userid、申请/完成/更新时间、最后来源、风险标记 |
| `WecomApprovalParticipant` | 申请人、审批人、抄送人、节点参与人快照 | `sp_no`、角色、节点序号、企微 userid、OA 员工映射、是否当前节点、是否映射失败 |
| `WecomApprovalAction` | 通过、驳回、撤回、转交、系统状态变化等动作历史 | `sp_no`、动作类型、操作者、动作时间、节点序号、意见摘要、来源和幂等键 |
| `WecomApprovalFieldSummary` | 表单字段规范化摘要 | 字段 key、字段名、字段类型、规范化值、敏感级别、是否可展示 |
| `WecomApprovalAttachmentSummary` | 低风险附件摘要和外部引用 | 附件数量、类型、外部引用摘要、是否下载、敏感级别 |
| `WecomApprovalCallbackEvent` | 企微回调事件持久证据 | `approval_archive_id`、完整 `sp_no`、完整 `template_id`、事件类型、规范化状态、接收时间、企微事件时间、处理结果、幂等键、摘要 digest；日志和报告只输出脱敏前缀 |
| `WecomApprovalCompensationRun` / `WecomApprovalCompensationItem` | 补偿拉取运行和逐单详情证据 | 时间窗口、模板过滤、游标、计数、错误分类、`sp_no` 关联、详情拉取状态 |
| `WecomApprovalReconcileFinding` | 回调与补偿对账差异 | 漏回调、重复回调、状态不一致、样例缺失、权限阻断和解释状态 |
状态机统一为 `pending`、`approved`、`rejected`、`revoked`、`terminated`、`changed`、`unknown`、`sync_failed`。同一 `sp_no` 采用幂等 upsert，动作历史只追加不删除；若回调和补偿拉取状态冲突，主表不静默覆盖为成功，而是写入 `WecomApprovalReconcileFinding`。
回调与补偿合并规则：
- DB 业务表必须保存完整 `sp_no`、`template_id`、企微 userid 和 `approval_archive_id`，用于稳定关联和补偿恢复；脱敏只发生在日志、报告、Issue、文档、默认导出和普通 UI 摘要。
- `getapprovaldetail` 的详情快照是业务状态的最终校准来源；回调是低延迟事件来源。补偿拉取成功拉到详情后，可以修正主表状态，但必须保留原回调事件和动作历史。
- 主表维护 `status_observed_at`、`last_source`、`last_detail_digest`。新事件只有在 `observed_at` 晚于当前状态时间，或详情 digest 变化时才能推进主状态；旧的非终态事件不得覆盖较新的终态。
- 终态 `approved`、`rejected`、`revoked`、`terminated` 不被较旧的 `pending` 或 `unknown` 覆盖；若企微详情返回不同终态，记录 `status_mismatch` finding，并以最新详情快照作为待确认状态。
- 回调重试使用同一事件幂等键 upsert 并递增重试计数，不重复写动作历史。补偿拉取同一 `run_id + sp_no` 只能有一条 item，详情 digest 相同则只更新时间和来源，不重复生成动作。
- source 优先级用于解释，不用于盲目覆盖：`getapprovaldetail` 详情快照 > 回调事件 > 手工导入/测试样例。任何跨来源不一致必须留 finding。
请假/补卡 WARCH1 V1 至少应保存：申请类型、申请人、审批人、时间范围或补卡时间、时长、原因摘要、状态、审批历史、来源、外部关联键和同步证据。外出/加班仍需后续样例或处理决策；不可把请假/补卡可读性结论扩展为外出/加班已通过。
同意单击即通过的风险处理不要求回退 OA 主办，但 WARCH1 之后的 OA 历史页和操作规程必须突出：审批动作来源、操作者、时间、状态变化、是否由企微单击同意触发，以及后续补偿拉取是否与回调一致。
隐私边界：
- OA DB 可保存完整 `sp_no`、`template_id` 和企微 userid，用于补偿、恢复和审计；日志、报告、Issue 和文档只输出脱敏前缀。
- 不保存原始 XML、密文、Token、EncodingAESKey、access token、Secret 或无治理原始 payload。
- 表单字段只保存业务必要的规范化字段；如后续确需保存原始 payload，必须另设加密存储、保留期限和访问审计。
- 普通员工只能看本人历史；审批人看自己处理链路；HR/管理员按范围查看；导出默认脱敏。
### 9.5 WF8 邮件通道决策
WF8 当前正式验收通道为站内通知和企业微信个人应用消息。邮件通道先记录为冻结项，不作为当前 WF8 硬门禁；三渠道验收在本阶段按“两渠道验收 + 邮件冻结说明”处理。