# 支付网关容灾与对账体系设计 v3（主动查账 · 事件驱动 · 三级兜底 · 人工异常池）

> 版本：v3.0（2026-08-09）
> 设计约束：
> - 临时隧道是防攻击特性，不引入固定域名；回调丢失是常态，主动查账是核心保障。
> - 兜底分**三级**：① 自动查单补账（ConfirmScheduler）→ ② 退避重试（查单/通知）→ ③ **人工异常处理池**（自动化兜不住时的最终兜底）。
> - 所有资金写入（含人工处理）只走幂等入口（SettlePayment / CloseOrder），不绕过状态机、不手改账本。
> - 高性能：事件驱动 + timer heap，不轮询；不出错：幂等 + 关单前查单 + 冲突进差错。

---

## 一、设计哲学

1. **回调是优化，查单是保障** —— 快路径（回调入账）与慢路径（查单补账）殊途同归，都进幂等 `SettlePayment`。
2. **数据经过网关，就有信息返回** —— 每个环节可自我验证，异常即触发兜底。
3. **三级兜底**：自动补偿 → 退避重试 → **人工异常池**。自动化兜不住才进人工，人工操作也走同一幂等入口。

---

## 二、每环节"正常路径 vs 兜底"

| 环节 | 正常 | 异常→兜底触发 |
|------|------|----------------|
| ① 上游→网关（下单） | 验签→建单→返回凭据 | 验签/参数失败→拒绝并记录（无资金影响） |
| ② 用户→支付宝（支付） | 回调→入账（快路径） | **回调丢失→ConfirmScheduler 到期→查单补账（慢路径）** |
| ③ 网关→上游（通知） | 通知 200→标记 | 失败→outbox 重试 31h→dead→人工重发 |
| ④ 日终对账 | 一致 | 不一致→差错单→人工 |
| ⑤ **任何环节异常不明** | — | **进人工异常池**（兜底链终点） |

---

## 三、核心模块：ConfirmScheduler（订单确认调度器）

内存 min-heap（按 nextCheckAt 排序），事件驱动，**非轮询**。

```
OnOrderCreated → push(now + T1 60s)
OnCallbackReceived → remove + SettlePayment（幂等）
到期 Confirm(tradeNo)：
  ├─ 已 SUCCESS → remove
  ├─ 仍 WAIT 未到关单时间 → QueryOrder 查单
  │     ├─ TRADE_SUCCESS → SettlePayment 补账 → 通知 → remove
  │     ├─ 未支付 → push(+30s~5m 自适应)
  │     └─ 查单失败 → push(+退避)，连续失败 N 次 → 进异常池（query_failed）
  └─ 到关单时间 → 最后查一次：已支付补账；未支付 CloseOrder；查单失败 → 推迟关单 + 进异常池
```

冲突（查单金额≠订单金额、状态矛盾）→ **不自动入账** → 进异常池（amount_mismatch / state_conflict）。

---

## 四、人工异常处理池（Manual Exception Pool）★新增核心

### 4.1 定位
**自动化兜底失败后的最终兜底**：任何"不按正常流程"的订单（回调全丢且查单不明、金额矛盾、关单存疑、通知 dead 无法重发）自动进入本池。人工核对证据 → 按流程填写必要信息 → 提交后经幂等入口恢复为正常订单，**订单永久标记"人工处理"**，全程审计。

### 4.2 数据模型（新表 + orders 标记）

```sql
-- 异常订单池（只增不改，resolved 后可 reopen，不可删除）
CREATE TABLE exception_orders (
    id              INTEGER PRIMARY KEY AUTOINCREMENT,
    out_trade_no    TEXT NOT NULL UNIQUE,      -- 关联订单
    pid             TEXT, upstream_name TEXT, channel TEXT,
    amount_minor    INTEGER,                   -- 网关记录金额（分）
    order_status    TEXT,                      -- 当前订单状态
    channel_status  TEXT,                      -- 最近查单结果（TRADE_SUCCESS/CLOSED/QUERY_FAILED/UNKNOWN）
    channel_tx_id   TEXT,                      -- 查单拿到的通道交易号
    paid_amount     INTEGER,                   -- 人工确认的实际支付金额（默认=amount_minor）
    payer           TEXT,                      -- 人工确认的付款方
    reason          TEXT,                      -- query_failed / amount_mismatch / state_conflict / close_uncertain / notify_dead / manual
    phase           TEXT DEFAULT 'pending',    -- pending / processing / resolved
    resolved_action TEXT,                      -- settle / close / noop / refund
    evidence        TEXT,                      -- 证据时间线 JSON（自动收集，不可手改）
    suggestion      TEXT,                      -- 系统建议动作（依据最近查单结果）
    handler         TEXT, handler_note TEXT,
    resolved_at     TEXT, updated_at TEXT,
    created_at      TEXT
);

-- orders 表新增人工处理标记（列表/详情可见，审计可追溯）
ALTER TABLE orders ADD COLUMN exception_id  INTEGER DEFAULT 0;    -- 关联异常池
ALTER TABLE orders ADD COLUMN handled_by    TEXT DEFAULT '';      -- 处理人
ALTER TABLE orders ADD COLUMN handled_action TEXT DEFAULT '';     -- manual_settle / manual_close / noop
ALTER TABLE orders ADD COLUMN handled_at    TEXT DEFAULT '';
ALTER TABLE orders ADD COLUMN handled_note  TEXT DEFAULT '';

-- 操作审计（谁在何时对哪个异常单做了什么）
CREATE TABLE exception_logs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    exception_id INTEGER, action TEXT, operator TEXT, detail TEXT, created_at TEXT
);
```

### 4.3 自动进池触发点（ConfirmScheduler / notify 集成）

| 触发 | reason | 进入时自动收集的证据 |
|------|--------|----------------------|
| 查单连续失败 ≥ `query_fail_alert`（5 次） | query_failed | 下单/回调/通知记录 + 每次查单结果时间线 |
| 查单金额 ≠ 订单金额 | amount_mismatch | 查单快照（金额、交易号、时间） |
| 回调与查单状态矛盾 | state_conflict | 两方原始数据 |
| 关单时查单失败（存疑） | close_uncertain | 查单错误信息 |
| 通知 dead 且重发仍失败 | notify_dead | 通知任务重试历史 |
| 管理后台手动加入 | manual | 人工填写的说明 |

进池时同时**暂停 ConfirmScheduler 对该订单的自动动作**（避免人工处理与自动查单打架），订单转入"待人工"。

### 4.4 人工处理流程（管理后台「异常订单」页）

```
① 列表（筛选 phase/reason/上游/日期）→ 打开详情
② 详情：基本信息 + 证据时间线（自动收集，只读）+ 系统建议动作
   （可点「再次查单」刷新证据：调用通道查单，把最新结果并入时间线）
③ 填写处理表单：
     动作：settle（确认入账）/ close（确认未支付，关单）/ noop（无需处理）
     实际支付金额（默认=订单金额，可改）
     通道交易号（可从支付宝账单人工核对后填入）
     付款方（可选）
     备注
④ 提交 → 后端校验（金额>0、订单未处理过、动作合法、表单与证据不冲突）
      → 执行：
        settle → Service.SettlePayment(幂等，参数含人工金额/交易号/付款方/来源=manual)
                  → 成功自动创建通知任务 → 通知上游到账
        close  → Service.CloseOrder(幂等，单笔)
        noop   → 仅记录
      → 成功：orders 写 handled_* 标记 + exception_orders 置 resolved + exception_logs 记审计
⑤ 该订单在列表/详情永久显示「⚠️ 人工处理」徽标（含处理人/时间/备注/动作）
```

### 4.5 防呆与安全

| 项 | 设计 |
|----|------|
| 并发防重 | 处理时 `phase=pending→processing` 行锁，同一订单不可并发处理；resolved 后不可再处理（可管理员 reopen） |
| 幂等入口 | settle/close 一律走 Service 幂等方法，**绝不直接 UPDATE 订单状态/金额** |
| 金额校验 | 人工金额必须 >0 且为整数分；与查单金额不一致时强制二次确认（输入框要求重复输入） |
| 证据只读 | evidence 自动收集，人工不可编辑（防掩盖）；人工信息只写在 paid_amount/payer/handler_note |
| 权限 | 异常池操作走管理后台认证；敏感动作（settle）可加二次确认口令（可配置） |
| 审计 | exception_logs 全程留痕：谁、何时、看了什么、填了什么、做了什么 |
| 账本 | settle 走 SettlePayment 自动过账本 hash 链；人工无法绕账本 |

### 4.6 与上游通知不到的联动
人工 settle 成功后自动创建通知任务 → 若上游仍不可达 → outbox 重试 31h → dead → 此时订单已 SUCCESS，**dead 通知单独成清单**（"上游未确认"），可在异常池关联查看/重发；上游也可主动调 `/api.php` 查单（网关数据正确，拉取是上游的事）。

---

## 五、分阶段落地

| 阶段 | 内容 | 说明 |
|------|------|------|
| **P0-1** | 通知重试增强（31h 窗口）+ dead 管理 API | 修复"付钱未到账" |
| **P0-2** | ConfirmScheduler 最小版（timer heap + 查单补账 + 关单前查单） | 回调丢失自动兜底 |
| **P0-3** | systemd 守护（gateway+new-api）+ 每日 sqlite 备份 | 进程/数据安全 |
| **P1-1** | **人工异常处理池**（表 + 进池触发 + 处理流程 + 管理后台页） | 最终兜底 + 人工台 |
| **P1-2** | 启动配置自检（沙箱/正式、密钥、回调地址） | is_prod 错配早暴露 |
| **P1-3** | 告警（Bark/Webhook：查单连续失败、验签失败率、dead、账本失败、**进池事件**） | 可观测 |
| **P2-1** | 日终对账报告（网关 vs 通道 vs 上游） | 资金最终核对 |

> **存量订单 116**：P0-2 落地后由 ConfirmScheduler 自然发现；若查单亦失败（极端），P1-1 人工池接管——人工从支付宝账单核对后 settle 恢复，标记人工处理。

---

## 六、模块与现有代码对应

| 新组件 | 复用 | 新增 |
|--------|------|------|
| `reconciler.ConfirmScheduler` | `Channel.QueryOrder`、`Service.SettlePayment`、`CloseExpiredOrders` | timer heap、事件接口 |
| `reconciler.ExceptionPool` | admin 框架、审计日志模式、SettlePayment/CloseOrder | exception 表、进池触发、处理流程 API |
| notify 增强 | `notify.Worker`、`notify_tasks` | 重试参数、dead 管理 API |
| admin 页面 | admin 框架 | 异常订单池 Vue 页（证据时间线 + 处理表单） |
| systemd + 备份 | gateway_autostart.sh | service 单元、备份脚本 |

**核心承诺**：所有资金写入（自动或人工）只走 `SettlePayment` / `CloseOrder` 等幂等方法；人工处理同样过账本 hash 链、同样触发通知、同样留审计；订单永久可追溯"是否人工处理过、谁处理的、依据什么"。