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

企业微信审批存量切换清单

目标与边界

本清单用于把退款人工 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。

-- 仍需通过旧人工入口完成的存量待审批退款
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。问题应通过前向修复处理。