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
+61 -4
查看文件
@@ -2,10 +2,10 @@
**文档状态**：当前开发路线图事实源。
**分类**：开发治理 / 路线图。
**适用时间**：WDRG / WCP1 / WHMSLIVE / WOUA / WAPI / WRRA / WOUA-FIX / WRV1 / WRA1 / WMSG1 / WAPC1 / WAPC2 / WPROC1 / WPROC2 / WAPC2F / WAPC2FLIVE / WCBK1 / WEGOV1 / WACP3 / WACP3R / WREAD1 / WREAD1F 真机确认之后。
**关联 Issue**：`WDRG,WCP1,WHMS,WHMSLIVE,WOUA,WAPI,WRRA,WOUAFIX,WRV1,WRA1,WMSG1,WAPC1,WAPC2,WPROC1,WPROC2,WAPC2F,WAPC2FLIVE,WCBK1,WEGOV1,WACP3,WACP3R,WREAD1,WREAD1F`。
**适用时间**：WDRG / WCP1 / WHMSLIVE / WOUA / WAPI / WRRA / WOUA-FIX / WRV1 / WRA1 / WMSG1 / WAPC1 / WAPC2 / WPROC1 / WPROC2 / WAPC2F / WAPC2FLIVE / WCBK1 / WEGOV1 / WACP3 / WACP3R / WREAD1 / WREAD1F / WADM1 之后。
**关联 Issue**：`WDRG,WCP1,WHMS,WHMSLIVE,WOUA,WAPI,WRRA,WOUAFIX,WRV1,WRA1,WMSG1,WAPC1,WAPC2,WPROC1,WPROC2,WAPC2F,WAPC2FLIVE,WCBK1,WEGOV1,WACP3,WACP3R,WREAD1,WREAD1F,WADM1`。
**最近审计**：2026-05-19。
**不得误读**：本文只控制后续开发节奏、阶段顺序和门禁。WHMSLIVE 后只代表企微 HR 主数据镜像已部署并受控验证；WAPI 后进一步固定企微 API/Secret 口径并转为运行优先；WRRA 后明确 `PASS_WITH_FINDINGS` 只代表只读对账成功且存在差异，不代表企微考勤/审批镜像、OA 应急接管、恢复回写或 RuleOps 已完成运行时实现。WMSG1 只证明企业微信应用消息可达和 Deeplink 可回到 OA；WAPC1 只固化审批配置准备清单；WAPC2 只新增请假/补卡模板详情和低风险 `sp_no` 审批详情只读 POC，不代表真实回调或镜像能力已完成。WPROC1 后，WAPC2 不直接放行深度镜像，必须先完成自动样件、回调、补偿拉取和镜像数据模型设计门禁。WPROC2 只新增可执行 process gate。WAPC2FLIVE 已创建 OA-POC 请假/补卡测试模板和低风险测试审批单，并自动复跑 WAPC2 得到 `PASS_APPROVAL_POC`。WCBK1 已完成真实回调 URL 验证和一条现有 OA-POC 测试审批单事件确认，公网报告为 `PASS_CALLBACK_EVENT_CONFIRMED`；WEGOV1 后路线明确为“企微成熟功能优先上线，OA 做自建留存、审计、入口、消息和应急兜底”。WACP3R 已将补偿拉取复跑修正为自动按 `SMOKE002` creator 发现 OA-POC 请假/补卡模板，公网报告 `/app/artifacts/qa-flow/wecom-approval-compensation-poc-20260519T115944Z/summary.json` 为 `PASS_WITH_FINDINGS`。WREAD1F 新样例后，审批人真机确认请假和补卡消息卡片、列表、详情页均可看清；远端人工结果报告 `/app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T133628Z/summary.json` 为 `PASS_READABLE`。但同意按钮单击即通过仍是操作风险，需在 WADM1/WARCH1 的留存、审计、提示或操作规程中继续处理；该结论不代表自建留存模型、最小历史留存或 `wecom_attendance_approval_mirror_v1` 已完成。
**不得误读**：本文只控制后续开发节奏、阶段顺序和门禁。WHMSLIVE 后只代表企微 HR 主数据镜像已部署并受控验证；WAPI 后进一步固定企微 API/Secret 口径并转为运行优先；WRRA 后明确 `PASS_WITH_FINDINGS` 只代表只读对账成功且存在差异，不代表企微考勤/审批镜像、OA 应急接管、恢复回写或 RuleOps 已完成运行时实现。WMSG1 只证明企业微信应用消息可达和 Deeplink 可回到 OA；WAPC1 只固化审批配置准备清单；WAPC2 只新增请假/补卡模板详情和低风险 `sp_no` 审批详情只读 POC，不代表真实回调或镜像能力已完成。WPROC1 后，WAPC2 不直接放行深度镜像，必须先完成自动样件、回调、补偿拉取和镜像数据模型设计门禁。WPROC2 只新增可执行 process gate。WAPC2FLIVE 已创建 OA-POC 请假/补卡测试模板和低风险测试审批单，并自动复跑 WAPC2 得到 `PASS_APPROVAL_POC`。WCBK1 已完成真实回调 URL 验证和一条现有 OA-POC 测试审批单事件确认，公网报告为 `PASS_CALLBACK_EVENT_CONFIRMED`；WEGOV1 后路线明确为“企微成熟功能优先上线，OA 做自建留存、审计、入口、消息和应急兜底”。WACP3R 已将补偿拉取复跑修正为自动按 `SMOKE002` creator 发现 OA-POC 请假/补卡模板，公网报告 `/app/artifacts/qa-flow/wecom-approval-compensation-poc-20260519T115944Z/summary.json` 为 `PASS_WITH_FINDINGS`。WREAD1F 新样例后，审批人真机确认请假和补卡消息卡片、列表、详情页均可看清；远端人工结果报告 `/app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T133628Z/summary.json` 为 `PASS_READABLE`。但同意按钮单击即通过仍是操作风险，需在 WADM1/WARCH1 的留存、审计、提示或操作规程中继续处理。WADM1 只完成自建留存/镜像数据模型设计，不创建 Prisma migration、不写业务代码、不部署；它不代表最小历史留存、完整镜像、应急接管、恢复回写或 RuleOps 已完成。
## 1. 路线图原则
@@ -46,6 +46,7 @@
| `WEGOV1` | 路线和治理已调整 | 明确混合架构：企微成熟功能优先上线，OA 做自建数据留存、审计、入口、消息和应急兜底；固化受控测试域、自动化优先和人工边界；后续顺序调整为 WACP3、WREAD1、WADM1、WARCH1 后再评估深度镜像。 |
| `WACP3/WACP3R` | 已实现并公网只读复跑，有 findings | 新增 QA-only `npm run check:wecom-approval-compensation-poc` 和 `POST /cgi-bin/oa/getapprovalinfo` 只读封装，固定 `WECOM_AGENT_SECRET`。WACP3R 改为按 `SMOKE002` creator 自动发现 OA-POC 请假/补卡模板 ID，再按模板过滤拉审批单号并用 `getapprovaldetail` 拉详情；公网报告 `/app/artifacts/qa-flow/wecom-approval-compensation-poc-20260519T115944Z/summary.json` 为 `PASS_WITH_FINDINGS`：请假/补卡各拉到 1 条详情，发现回调证据文件未持久化导致当前无法跨部署比对历史回调。未写 OA/企微数据，未保存完整模板 ID。 |
| `WREAD1/WREAD1F` | 请假/补卡真机确认已通过 | 新增 QA-only `npm run check:wecom-approval-readability-gate`，只读汇总 OA-POC 请假/补卡证据并输出人工确认清单。WREAD1F 重新生成新样例后，审批人真机确认请假和补卡均可看清；远端报告 `/app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T133628Z/summary.json` 为 `PASS_READABLE`。风险记录：驳回有二次确认，但同意单击即通过，后续 WADM1/WARCH1 需纳入提示、审计或操作规程。 |
| `WADM1` | 自建留存/镜像模型设计已固化 | docs-only 固定 OA 留存域数据模型：企微审批主表、参与人/节点/动作、字段摘要、附件摘要、回调事件、补偿拉取 run/item、对账 finding、打卡/人事快照边界、隐私保留、权限和 WARCH1 最小实现切片。WADM1 解决 WACP3R “回调证据文件未持久化”的模型设计缺口，但不创建迁移、不写入业务数据、不放行完整镜像。 |
## 3. 阶段路线
@@ -61,7 +62,7 @@
| 8 | `WEGOV1 企微主办治理与自建留存路线修正` | 固化混合主办边界、OA 自建留存策略、受控测试域和后续顺序。 | WCBK1 已确认真实回调事件；用户选择优先利用企微成熟功能并要求 OA 保存关键历史。 | docs-only 收口；文档明确企微主办域、OA 主办域、OA 留存域、OA 应急域、自动化与人工边界。 |
| 9 | `WACP3 补偿拉取 POC` | 证明按时间窗口批量获取审批单号并可拉取审批详情，作为回调丢失补偿。 | WEGOV1 完成；WAPC2/WAPC2FLIVE/WCBK1 已提供低风险样例、详情读取和真实事件证据；官方 API 和权限明确。 | WACP3R 已自动发现 OA-POC 请假/补卡模板并复跑到 `PASS_WITH_FINDINGS`：补偿拉取和详情读取可用；findings 为当前回调证据文件未持久化，需在 WADM1/WARCH1 设计留存模型时解决。 |
| 10 | `WREAD1 企微审批可读性与误审批防护门禁` | 真机确认请假、补卡、外出、加班在企微里是否看得清再批，评估快捷同意/驳回误操作风险。 | WACP3 完成或并行准备低风险样例；审批模板可在企微手机端由代表审批人查看。 | 请假/补卡已由 WREAD1F 真机确认 `PASS_READABLE`；驳回有二次确认，同意单击即通过，后续作为操作风险进入 WADM1/WARCH1 设计。外出/加班仍需后续样例或处理决策；不可读模板不得进入正式镜像。 |
| 11 | `WADM1 自建留存/镜像数据模型设计` | 先设计 OA 留存字段、状态机、幂等键、索引、隐私保留、审计和迁移回滚方案。 | WACP3 证明补偿拉取可用；WREAD1 明确模板可读性或回退策略。 | 模型覆盖审批、打卡、人事关键快照、回调事件和补偿拉取记录；设计经 Issue CSV 固化后才允许 schema 或业务代码实现。 |
| 11 | `WADM1 自建留存/镜像数据模型设计` | 先设计 OA 留存字段、状态机、幂等键、索引、隐私保留、审计和迁移回滚方案。 | WACP3 证明补偿拉取可用；WREAD1 明确模板可读性或回退策略。 | 已完成 docs-only 设计：模型覆盖审批、打卡、人事关键快照、回调事件和补偿拉取记录；只允许在单独 WARCH1 合同批准后进入 schema 或业务代码实现。 |
| 12 | `WARCH1 最小自建历史留存实现` | 只读保存企微审批、打卡、人事关键快照，先满足企微不可用时可查看历史。 | WADM1 完成并批准 schema/接口实现。 | OA 可查看已保存历史摘要和完整外部关联键；报告和日志只输出脱敏前缀；不保存 Secret、token、EncodingAESKey、原始密文或无治理原始 payload。 |
| 13 | `wecom_attendance_approval_mirror_v1` | 企微打卡、请假、补卡、外出、加班、假期余额和审批历史镜像到 OA。 | WARCH1 稳定；外出/加班模板和打卡细项明确；运行优先门禁和用户一致性仍满足。 | OA 可查询企微 HR/考勤镜像、附件摘要、审批历史、考勤解释和审计；不把 OA 主办高敏审批迁到企微。 |
| 14 | `oa_hr_emergency_mode_v1` | 企业微信不可用时，由管理员人工开启 OA HR/考勤应急接管。 | 自建历史留存和镜像数据可支撑对账；OA 应急入口、权限和审计方案明确。 | 管理员可填写原因、范围、预计结束时间和责任人后开启/关闭；应急单据带 `EMERGENCY` 标记。 |
@@ -237,3 +238,59 @@ WAPC2 通过后，下一步不是直接进入 `wecom_attendance_approval_mirror_
8. `WARCH1 最小自建历史留存实现`：先只读保存企微审批、打卡和人事关键快照，保证企微不可用时可查看历史。
上述门禁完成前，不拆 `wecom_attendance_approval_mirror_v1`。
## 13. WADM1 自建留存/镜像数据模型设计
WADM1 是 `WARCH1` 前的设计门禁，只定义数据模型、状态机、幂等键、隐私和迁移回滚策略，不创建 Prisma migration、不改业务代码、不部署。
模型按四域边界拆分：
| 模型域 | 设计对象 | WARCH1 V1 取舍 |
| --- | --- | --- |
| 企微审批留存 | `WecomApprovalArchive` 主表、`WecomApprovalParticipant` 参与人/节点快照、`WecomApprovalAction` 审批动作、`WecomApprovalFieldSummary` 字段摘要、`WecomApprovalAttachmentSummary` 附件摘要 | 先覆盖请假和补卡；保存完整 `sp_no`、`template_id`、申请/审批人外部键到受权限保护的 OA DB；报告和日志只输出脱敏前缀。 |
| 回调与补偿证据 | `WecomApprovalCallbackEvent`、`WecomApprovalCompensationRun`、`WecomApprovalCompensationItem`、`WecomApprovalReconcileFinding` | 解决 WACP3R finding：回调证据不能再只落到易丢失文件；DB 内保存完整 `sp_no`/`template_id`/`approval_archive_id` 用于稳定关联，日志和报告只输出脱敏前缀；未来回调和补偿拉取均入库后再比对漏回调、重复回调和状态不一致。 |
| 打卡与人事快照 | 复用 `WecomCheckinSyncRun`、`WecomCheckinRecord`、`WecomHrMasterSyncRun`、`WecomHrMasterSyncItem`、`WecomIdentityBinding`，后续按缺口补规则快照、假期余额摘要或花名册快照 | WARCH1 不重造企微打卡风控；先保存已可读摘要和必要快照，排班、日报、月报、假期余额细项按后续 POC 再扩展。 |
| OA 应急衔接 | 应急单据与企微镜像单据通过外部键、状态和恢复队列关联 | WADM1 只预留字段和状态，不开启 `oa_hr_emergency_mode_v1`，不做恢复回写。 |
审批留存主表建议字段：
- 业务键：`sp_no` 唯一、`template_id`、`template_type`（`leave`、`missed_punch`、后续 `outing`、`overtime`）、`corp_id_hash` 或租户标识、企微状态码和 OA 规范化状态。
- 人员键：申请人 OA `employee_id`、申请人企微 userid、审批人/抄送人企微 userid、通过 `WecomIdentityBinding` 映射到 OA 员工；映射失败时保留外部键并标记 `unmatched_user`。
- 时间键：申请时间、提交时间、最后状态时间、完成时间、最近回调时间、最近补偿拉取时间。
- 来源键：`last_source` 为 `callback`、`compensation_pull`、`manual_import` 或 `synthetic_fixture`；`source_priority` 规则为回调和补偿互补，不以文件报告替代数据库事实。
- 风险键：`readability_status`、`single_tap_approve_risk`、`template_adjustment_required`、`external_config_status`。
审批状态机建议规范化为：`pending`、`approved`、`rejected`、`revoked`、`terminated`、`changed`、`unknown`、`sync_failed`。企微原始状态码只作为枚举/字符串字段保存，不保存原始 payload；状态推进采用“同一 `sp_no` 幂等 upsert + 最新状态时间优先 + 保留全部动作历史”的规则。回调和补偿状态冲突时不覆盖为成功，而是生成 `WecomApprovalReconcileFinding`，等待后续 runner 或人工解释。
回调和补偿合并语义：
- `getapprovaldetail` 详情快照作为业务状态最终校准来源；回调作为低延迟事件来源。两者都必须持久化，不能以 runner 文件报告替代数据库事实。
- 主表保存 `status_observed_at`、`last_source` 和 `last_detail_digest`；只有更晚的事件时间或变化的详情 digest 才能推进主状态。
- 较旧的 `pending`、`unknown` 或失败事件不得覆盖较新的终态；不同终态冲突写入 `WecomApprovalReconcileFinding(status_mismatch)`，不静默改成成功。
- 回调重试以事件幂等键 upsert 并累加重试计数；补偿拉取以 `run_id + sp_no` 唯一，详情 digest 未变化时不重复写动作。
- DB 业务表保存完整外部键，默认 UI、导出、日志、报告、文档和 Issue 只显示脱敏前缀。
幂等键建议：
- 审批主表：`sp_no` 唯一。
- 回调事件：`sha256(corp + event_type + sp_no + template_id + normalized_status + node_user + event_time + normalized_digest)`；保存 digest，不保存原始 XML、密文或原始 payload。
- 补偿拉取 run：`source + start_time + end_time + template_filter + cursor`。
- 补偿 item：`run_id + sp_no` 唯一，并记录详情拉取状态和错误分类。
- 审批动作：`sp_no + action_type + operator_userid + action_time + node_index`。
隐私和保留策略：
- OA DB 可保存完整外部关联键和业务必要字段，用于补偿、历史查看、恢复和审计；日志、报告、Issue CSV 和文档只保存脱敏前缀。
- 表单字段默认只保存规范化业务字段和摘要。请假/补卡至少保存申请类型、时间范围、时长或补卡时间、原因摘要、审批状态和审批历史；不保存无治理的整包 payload。
- 附件 V1 只保存数量、类型和外部引用摘要；不下载采购、合同、报销、发票、银行回单或高敏附件。
- 原始 XML、密文、Token、EncodingAESKey、access token、Secret 和完整回调密文永不入库。若后续确需原始 payload，必须另开加密存储、字段级访问审计和保留期限合同。
- 普通员工只能查看本人历史；审批人查看自己处理链路；HR/管理员按部门或系统权限查看；导出默认脱敏。
WARCH1 最小实现切片：
1. 新增只写不读的审批留存、回调事件、补偿拉取和对账 finding 表，migration 可回滚。
2. 修改 WCBK1 回调路径和 WACP3 补偿 runner，把请假/补卡的规范化详情幂等写入 OA DB。
3. 增加 QA-only backfill/verify runner：断开企微 API 时仍能从 OA DB 读取已保存的请假/补卡历史摘要。
4. 再做只读查询 API 或管理页入口；不在 WARCH1 内开启完整镜像增强、外出/加班正式样例、应急接管、恢复回写或 RuleOps。
WARCH1 实施前必须另建 Issue CSV，并在方案中列出 Prisma 表、索引、迁移回滚、权限、脱敏输出和 replay 策略。