# T8.4 渠道失败兜底 SOP

状态：已落地（巡检 CLI + 人工补录指令）
适用范围：当前巡检事实源以 `xianyu` 的 `webhook_audit` / `poller_state` / `poller_run` 为准；其他渠道目前仅复用“人工补录模板”，不应误解为已接入同等自动健康判定。

## 1. 目标

当 Webhook 主路径异常、poller 兜底异常或渠道侧临时不可用时，运营/值班同学可以：

1. 先做事实巡检，确认是不是链路退化；
2. 再走人工补录，确保订单不因为渠道故障而丢单；
3. 最后继续用已有 order-manager CLI 推进 `paid/serving/delivered` 状态。

## 2. 定期检查

建议每 5~15 分钟执行一次：

```bash
python3 scripts/gaokao-channel-fallback --db data/orders.db check --source xianyu --human
```

返回语义：

- `status: ok`：最近未发现明显异常
- `status: warn`：链路可能未启动 / 最近运行过旧 / 存在失败信号，需要人工关注
- `status: critical`：poller 连续报错或最近一次 poller_run 失败，应立即切人工兜底

退出码：

- `0` = ok
- `1` = warn
- `2` = critical

适合 cron / systemd timer / 外部监控直接接入。

## 3. 人工兜底入口

### 3.1 打印模板

```bash
python3 scripts/gaokao-channel-fallback --db data/orders.db manual-template --source xianyu --human
```

### 3.2 新建订单

注意：当前 CLI 通过命令行参数接收姓名/手机号，存在 shell history / `ps` 暴露风险。仅建议在可信单用户主机上临时执行；执行后应清理历史记录，且不要把真实 PII 粘贴到工单/IM。

```bash
python3 scripts/gaokao-order-manager --db data/orders.db create \
  --source xianyu \
  --service-version basic \
  --amount-cents 0 \
  --customer-name 张三 \
  --customer-phone 13800001234 \
  --candidate-name 李同学 \
  --candidate-province 湖南
```

说明：

- `external_id` 可留空，允许渠道故障期先人工建单；
- `amount_cents` 在未确认实付时可先填 `0`，后续再 `update`；
- 订单创建后会自动生成 `GKO-*` 内部单号，后续推进都用该单号。

### 3.3 补齐字段 / 推进状态

```bash
python3 scripts/gaokao-order-manager --db data/orders.db update <ORDER_ID> \
  --assigned-consultant consultant-a \
  --note 渠道故障期人工补录

python3 scripts/gaokao-order-manager --db data/orders.db pay <ORDER_ID> --reason manual_pay
python3 scripts/gaokao-order-manager --db data/orders.db deliver <ORDER_ID> --reason manual_delivery
```

## 4. 值班判断规则

优先看以下事实：

1. `webhook_audit` 最近是否还有 `accepted`
2. `poller_state.last_run_at` 是否超过阈值
3. `poller_state.last_error` / `poller_run.error_message` 是否持续存在
4. 最近 60 分钟 `rejected + parse_error` 是否明显升高

建议阈值（CLI 默认值）：

- poller stale：15 分钟
- webhook stale：30 分钟
- recent window：60 分钟
- reject warn threshold：5 次
- poller error warn threshold：3 次

## 5. 推荐调度

最小 cron 方案：

```cron
*/10 * * * * cd /home/long/project/gaokao-volunteer-system && python3 scripts/gaokao-channel-fallback --db data/orders.db check --source xianyu
```

说明：

- 非 0 退出码表示要进入监控/告警；
- 真正是否有业务影响，还要结合最近是否有渠道订单流量；
- 若当前阶段尚未启用 poller，可接受 `warn`，但应明确值班同学走人工补录。

## 6. 当前边界

本次 T8.4 只补齐“巡检 + 人工兜底”闭环，不做：

- 自动调用真实闲鱼开放平台 API；
- 自动把外部失败订单直接转成人工建单；
- 自动通知企业微信/短信。
- 为 `wechat` / `school` 等非 xianyu 渠道建立独立 webhook/poller 健康事实源。

这些属于后续增强项，不影响当前人工值班闭环。