七月迭代短暂完结,还有很多后端的关键东西没有弄,这是一版赶时间做的东西

docs/wecom-application-connection/存量审批切换清单.md

@@ -0,0 +1,62 @@
+# 企业微信审批存量切换清单
+
+## 目标与边界
+
+本清单用于把退款人工 `approve/reject` 和线下充值人工 `offline-pay` 从存量兼容模式切换为企业微信只读审批状态模式。切换只关闭旧 HTTP 入口，不删除路由、历史退款、充值、审批实例、钱包流水、Outbox 或 Integration Log，也不为存量记录伪造企业微信审批实例。
+
+## 发布开关
+
+两个开关默认均为 `true`，部署新版本后继续允许 `approval_instance_id IS NULL` 的存量旧 provider 完成处理：
+
+| 环境变量 | 默认值 | 关闭后的入口 |
+|---|---|---|
+| `JUNHONG_APPROVAL_LEGACY_REFUND_MANUAL_ENABLED` | `true` | 退款 `approve/reject` 返回“入口已停用” |
+| `JUNHONG_APPROVAL_LEGACY_OFFLINE_RECHARGE_PAY_ENABLED` | `true` | 线下充值 `offline-pay` 返回“入口已停用” |
+
+配置变更后必须重启 API 实例。Worker 的企业微信标准终态消费者不读取这两个开关，不受切换影响。
+
+## 切换前只读核对
+
+以下 SQL 仅用于发布人员核对，不在本 Change 中执行。待审批状态值按当前模型均为 `1`。
+
+```sql
+-- 仍需通过旧人工入口完成的存量待审批退款
+SELECT id, refund_no, order_id, shop_id, creator, status, created_at
+FROM tb_refund_request
+WHERE deleted_at IS NULL
+  AND status = 1
+  AND approval_instance_id IS NULL
+ORDER BY id;
+
+-- 仍需通过旧人工入口完成的存量待确认线下充值
+SELECT id, recharge_no, shop_id, user_id, amount, status, created_at
+FROM tb_agent_recharge_record
+WHERE deleted_at IS NULL
+  AND payment_method = 'offline'
+  AND status = 1
+  AND approval_instance_id IS NULL
+ORDER BY id;
+```
+
+核对和处理规则：
+
+- `approval_instance_id IS NULL` 表示存量旧 provider，必须在关闭开关前通过原入口处理完成；不得补写或伪造企微实例。
+- `approval_instance_id IS NOT NULL` 表示新企微审批记录，只能由企微回调或轮询产生的标准终态处理；旧人工入口已在代码中逐单阻断。
+- 存量清单应保存退款/充值业务 ID、业务单号、当前状态、责任人和处理结果，不复制 Secret、access_token、media_id 或附件正文。
+
+## 关闭门禁
+
+只有同时满足以下条件才关闭旧入口：
+
+1. 退款和员工线下代充值已在真实企微环境完成发起、审批、回调或轮询补偿、标准终态以及资金副作用联调。
+2. 上述两份存量清单已清零，或剩余记录已有明确的前向处理方案和责任人。
+3. 前端已隐藏退款 `approve/reject` 与线下充值 `offline-pay` 操作，只读展示 `approval_instance_id`、`approval_provider`、`approval_status` 和 `approval_status_name`。
+4. API 发布配置把对应开关设为 `false`，并完成全部 API 实例滚动重启。
+
+关闭后应抽查：新企微记录的列表和详情审批字段一致；旧入口返回明确停用错误；Worker 仍能消费 `approved/rejected/cancelled/deleted` 标准终态。
+
+## 回滚
+
+如关闭后发现前端或存量处理遗漏，将对应开关重新设为 `true` 并重启 API 实例。回滚只恢复旧入口可用性，不改变企微审批记录的逐单防绕过规则。
+
+不得删除、清空或回退已经产生的审批实例、退款、充值、钱包流水、Outbox、Integration Log 或企微外部审批；不得把新企微记录改为旧 provider。问题应通过前向修复处理。