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

## 目标与边界

本清单用于把退款人工 `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。问题应通过前向修复处理。