312 lines
14 KiB
Markdown
312 lines
14 KiB
Markdown
# 渠道 SDK 集成设计 (T8)
|
||
|
||
日期: 2026-06-12
|
||
作者: coder (kanban t_884fbeee)
|
||
关联任务: T8.1 闲鱼Webhook集成 / T8.2 微信SDK集成 / T8.3 企业微信集成 / T8.4 失败兜底
|
||
交付状态: T8.1/T8.2/T8.3 已实现并完成本地验证；远程推送不在本文档范围
|
||
|
||
---
|
||
|
||
## 0. 范围
|
||
|
||
本文档定义 v2.1 渠道 SDK 集成层（Channel Sync）的设计方案，以及 T8.1 闲鱼 Webhook、T8.2 微信最小 client、T8.3 企业微信最小 client 的当前实现边界。
|
||
|
||
目标: 在不引入重 SDK 依赖（不集成闲鱼/微信官方 SDK）的前提下,实现:
|
||
|
||
- **主路径**: Webhook 推送 + HMAC 签名校验 + 订单去重入库
|
||
- **兜底路径**: 定时轮询未确认订单 + 手动录入后台（人工兜底）
|
||
- **消息能力**: 基于标准库的微信/企业微信最小发送 client（payload 组装、token 缓存、错误包装）
|
||
- **不推荐**: 爬虫/逆向（合规风险,合规审计明确否决）
|
||
|
||
适用范围:
|
||
|
||
- 闲鱼(主)
|
||
- 微信（最小标准库 client 已实现；生产联调/企业认证不在本期）
|
||
- 企业微信（最小标准库 client 已实现；生产联调/企业配置开通不在本期）
|
||
|
||
---
|
||
|
||
## 1. 设计目标与不做清单
|
||
|
||
### 1.1 设计目标
|
||
|
||
1. **合规优先**: 仅使用平台公开的 Webhook / 开放 API,绝不爬虫/逆向
|
||
2. **订单自动同步**: 闲鱼下单/付款/退款事件在 5 分钟内进入 `orders` 表
|
||
3. **幂等性**: 同一外部订单号重复推送不产生重复记录（依赖既有 `uniq_orders_external` 唯一索引）
|
||
4. **签名校验**: HMAC-SHA256 校验 Webhook 头,失败立即拒绝
|
||
5. **可观测**: 所有 Webhook 接收/拒绝/解析失败均落审计表
|
||
6. **可降级**: Webhook 不可用时,轮询任务可独立运行并补偿
|
||
|
||
### 1.2 不做清单
|
||
|
||
- ❌ 不接入闲鱼/微信官方 SDK（避免依赖膨胀 + 合规边界）
|
||
- ❌ 不做用户身份 OAuth 登录（人工服务场景,客户名/手机号由人工补录）
|
||
- ❌ 不做 IM 消息实时收发（本期只做订单事件,消息推送属 T8.2）
|
||
- ❌ 不做自动发卡/自动发货（人工交付,避免合规风险）
|
||
- ❌ 不在宿主数据库内建表（v2.1 独立 SQLite,本期不写 sub2api）
|
||
|
||
---
|
||
|
||
## 2. 架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ 外部渠道 (闲鱼开放平台) │
|
||
└────────────────────┬────────────────────┘
|
||
│ HTTPS POST
|
||
│ X-Signature: hmac-sha256=...
|
||
│ X-Timestamp: 1700000000
|
||
▼
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ Channel Webhook Receiver (Python stdlib http.server)│
|
||
│ ① 验签 → ② 去重 → ③ 解析 → ④ 写库 → ⑤ ACK │
|
||
└──────────────────────┬──────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────┐
|
||
│ data/orders DAO (T4.2) │
|
||
│ - upsert_by_external_id() │
|
||
│ - insert_status_history() │
|
||
└──────────────┬──────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────┐
|
||
│ data/channel_sync/ │
|
||
│ - signature.py (HMAC) │
|
||
│ - xianyu_adapter.py │
|
||
│ - poller.py (兜底轮询) │
|
||
│ - audit.py (审计日志) │
|
||
└─────────────────────────────┘
|
||
```
|
||
|
||
### 2.1 模块清单
|
||
|
||
| 文件 | 职责 | 行数预估 |
|
||
| ------------------------------------- | ----------------------------------------------- | -------- |
|
||
| `data/channel_sync/__init__.py` | 模块入口,导出公共 API | 30 |
|
||
| `data/channel_sync/signature.py` | HMAC-SHA256 签名/校验,时间戳防重放 | 80 |
|
||
| `data/channel_sync/audit.py` | Webhook 接收/拒绝/解析失败审计表 | 120 |
|
||
| `data/channel_sync/xianyu_adapter.py` | 闲鱼事件→Order 模型映射 | 150 |
|
||
| `data/channel_sync/poller.py` | 兜底轮询(从外部 API 拉未确认订单) | 200 |
|
||
| `data/channel_sync/webhook_server.py` | 标准库 http.server 实现的最小 Webhook 接收端 | 180 |
|
||
| `data/channel_sync/dao_extension.py` | 在 T4.2 DAO 之上添加 upsert_by_external_id 扩展 | 100 |
|
||
| `tests/test_xianyu_channel.py` | 单测:签名/解析/去重/兜底轮询 | 250+ |
|
||
|
||
合计 ≈ 1100 行(含测试)。
|
||
|
||
---
|
||
|
||
## 3. 关键流程
|
||
|
||
### 3.1 Webhook 接收流程
|
||
|
||
```
|
||
1. 接收 POST /webhook/xianyu
|
||
2. 读取 Header:
|
||
- X-Signature: hmac-sha256=<hex>
|
||
- X-Timestamp: <unix-seconds>
|
||
- X-Nonce: <random>
|
||
3. 时间戳校验: |now - ts| <= 300s (防重放窗口 5 分钟)
|
||
4. 签名校验: HMAC-SHA256(secret, f"{ts}.{nonce}.{body}") == X-Signature
|
||
5. 解析 body (JSON) → XianyuEvent
|
||
6. 调 XianyuAdapter.to_order(event) → Order
|
||
7. DAO.upsert_by_external_id(source='xianyu', external_id=event.order_id, order=order)
|
||
- 已存在: 更新 status / status_updated_at / 写历史
|
||
- 不存在: insert
|
||
8. 写 audit_log(decision='accepted', event_id=..., order_id=...)
|
||
9. 返回 200 OK
|
||
```
|
||
|
||
### 3.2 兜底轮询流程
|
||
|
||
```
|
||
1. 定时任务(每 5 分钟):
|
||
- 从 poller_state 读 cursor(上次拉取时间)
|
||
- 调 XianyuOpenAPI.list_orders(since=cursor)
|
||
- 对每个返回的订单:
|
||
a. 若 orders 表已存在: 比对状态,有变化则更新
|
||
b. 若不存在: insert + 写历史
|
||
- 更新 cursor = max(updated_at)
|
||
- 写 poller_run 审计行
|
||
2. 失败重试: 指数退避(5/15/45 分钟),3 次失败告警
|
||
3. 与 Webhook 关系: Webhook 为主路径,poller 补漏;同一订单在两端都到时,以外部订单号幂等
|
||
```
|
||
|
||
### 3.3 手动兜底
|
||
|
||
- 管理后台 (T6) 提供"新建订单"表单,source 字段可选 'xianyu'/'wechat'/'web'/'school'
|
||
- 提交时: external_id 留空可空(允许未带外部订单号的人工补录)
|
||
- 状态: 默认 pending,可手动推到 paid/serving/...
|
||
|
||
---
|
||
|
||
## 4. 数据契约
|
||
|
||
### 4.1 XianyuEvent(Webhook body 解析后)
|
||
|
||
```python
|
||
@dataclass
|
||
class XianyuEvent:
|
||
event_id: str # 闲鱼侧事件唯一 ID(用于去重审计)
|
||
event_type: str # 'order.created' | 'order.paid' | 'order.refunded'
|
||
order_id: str # 闲鱼订单号 → external_id
|
||
service_version: str # 'audit' | 'basic' | 'standard' | 'premium'
|
||
amount_cents: int # 单位:分
|
||
customer_name: str
|
||
customer_phone: str
|
||
customer_wechat: Optional[str]
|
||
candidate_name: Optional[str]
|
||
candidate_province: Optional[str]
|
||
created_at: str # ISO8601
|
||
paid_at: Optional[str]
|
||
refunded_at: Optional[str]
|
||
```
|
||
|
||
### 4.2 状态映射
|
||
|
||
| 闲鱼 event_type | Order.status | 备注 |
|
||
| --------------- | ------------ | ------------------ |
|
||
| order.created | pending | 拍下未付 |
|
||
| order.paid | paid | 担保交易付款成功 |
|
||
| order.delivered | serving | (可选,闲鱼发货) |
|
||
| order.completed | completed | 交易完成 |
|
||
| order.refunded | refunded | 退款(任意阶段可入) |
|
||
|
||
转换合法性由 `data/orders/state_machine.py` 的 `ALLOWED_TRANSITIONS` 强制约束。
|
||
|
||
### 4.3 审计表 (新增)
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS webhook_audit (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
received_at TEXT NOT NULL,
|
||
channel TEXT NOT NULL, -- 'xianyu'
|
||
event_id TEXT,
|
||
decision TEXT NOT NULL, -- 'accepted' | 'rejected' | 'parse_error' | 'duplicate'
|
||
reject_reason TEXT,
|
||
order_id TEXT, -- 已映射到的内部订单号
|
||
raw_body_hash TEXT, -- SHA-256(body),避免大字段落库
|
||
remote_addr TEXT
|
||
);
|
||
|
||
CREATE INDEX IF NOT EXISTS idx_webhook_audit_event
|
||
ON webhook_audit(channel, event_id);
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 安全与合规
|
||
|
||
### 5.1 签名密钥管理
|
||
|
||
- 来源: 环境变量 `GAOKAO_XIANYU_WEBHOOK_SECRET`
|
||
- 不入库,不入 git,不在日志中打印完整 secret
|
||
- 测试用固定值 `test-secret-for-unit-tests` 通过环境变量注入
|
||
|
||
### 5.2 防重放
|
||
|
||
- 时间戳窗口 300s(可配置 `XIANYU_WEBHOOK_TS_TOLERANCE`)
|
||
- 已用 nonce 缓存 10 分钟(内存 + 审计表任选其一;v1 用内存 LRU)
|
||
|
||
### 5.3 限流
|
||
|
||
- 单 IP 60 req/min(标准库实现,避免引入 redis)
|
||
- 超出返回 429 + Retry-After
|
||
- 来源 IP 默认取 socket `client_address`；仅在显式设置 `GAOKAO_TRUST_X_FORWARDED_FOR=true` 时才读取 `X-Forwarded-For`
|
||
|
||
### 5.4 数据脱敏
|
||
|
||
- 接收时即按既有 `data/orders/crypto.py` 加密手机/身份证
|
||
- 审计表只存 raw_body_hash,不存原始 body(避免敏感信息二次落地)
|
||
|
||
### 5.5 合规边界
|
||
|
||
- 仅接收业务事件,不主动调用闲鱼 API 抓取用户/聊天/地址等敏感信息
|
||
- 退款事件只更新订单状态,不主动调退款 API(避免代操作风险)
|
||
- 客户身份证号不在 Webhook 中接收(如闲鱼返回则丢弃,落审计 `reject_reason='pii_dropped'`)
|
||
|
||
---
|
||
|
||
## 6. 部署与运行
|
||
|
||
### 6.1 启动 Webhook 服务
|
||
|
||
```bash
|
||
# 监听 0.0.0.0:8080,挂载 /webhook/xianyu 路由
|
||
GAOKAO_XIANYU_WEBHOOK_SECRET=<...> \
|
||
GAOKAO_ORDERS_FERNET_KEY=<...> \
|
||
python -m data.channel_sync.webhook_server --port 8080
|
||
```
|
||
|
||
### 6.2 定期巡检 + 人工兜底
|
||
|
||
```bash
|
||
# 值班巡检（建议每 5~15 分钟一次，非 0 exit code 接告警）
|
||
python3 scripts/gaokao-channel-fallback --db data/orders.db check --source xianyu --human
|
||
|
||
# 打印人工兜底模板
|
||
python3 scripts/gaokao-channel-fallback --db data/orders.db manual-template --source xianyu --human
|
||
|
||
# 渠道不可用时先人工补录，后续再 pay / deliver
|
||
python3 scripts/gaokao-order-manager --db data/orders.db create \
|
||
--source xianyu --service-version basic --amount-cents 0 \
|
||
--customer-name 张三 --customer-phone 13800001234
|
||
```
|
||
|
||
详见 `docs/T8-4-fallback-sop.md`。注意：当前巡检健康度判定仅对已落 `webhook_audit` / `poller_*` 事实源的 `xianyu` 链路成立；其他 source 暂时只复用人工补录模板。
|
||
|
||
### 6.3 关闭 Webhook 时的兜底
|
||
|
||
- Webhook 不可用(闲鱼平台维护)时,poller 仍运行
|
||
- 平台恢复后,poller 与 Webhook 数据自动按 external_id 幂等合并
|
||
- 若 poller 也不可用,按 `docs/T8-4-fallback-sop.md` 走人工补录 CLI
|
||
|
||
---
|
||
|
||
## 7. T8 任务依赖与拆分
|
||
|
||
| ID | 任务 | 依赖 | 落地文件 | 状态 |
|
||
| ---- | --------------- | ---- | ---------------------------------------------------------------------------- | ---------------- |
|
||
| T8.1 | 闲鱼Webhook集成 | T4.1 | 本设计 + channel_sync/\* + tests/test_xianyu_channel.py | 已实现并本地验证 |
|
||
| T8.2 | 微信SDK集成 | T8.1 | channel_sync/wechat_adapter.py + tests/test_wechat_adapter.py | 已实现并本地验证 |
|
||
| T8.3 | 企业微信集成 | T8.2 | channel_sync/wecom_adapter.py + tests/test_wecom_adapter.py | 已实现并本地验证 |
|
||
| T8.4 | 失败兜底(手动) | T6 | `scripts/gaokao-channel-fallback` 巡检 + `gaokao-order-manager` 人工补录 SOP | 已落地 |
|
||
|
||
T8.1 不阻塞 T6/T7;但 T6 必须有"手动新建"入口作为兜底。
|
||
|
||
---
|
||
|
||
## 8. 验收标准 (T8.1 DoD)
|
||
|
||
- [ ] 接收 `POST /webhook/xianyu` 能解析 body 并入库(单测 + 集成测试覆盖)
|
||
- [ ] 签名错误 / 时间戳过期 → 401/408 拒绝,审计记录 `decision='rejected'`
|
||
- [ ] 重复 event_id → 不重复入库,审计记录 `decision='duplicate'`
|
||
- [ ] Webhook 主路径与 poller 兜底路径在并发下幂等(单测覆盖)
|
||
- [ ] webhook_audit 表 schema 与索引存在
|
||
- [ ] `pytest data/orders/tests data/channel_sync/tests -q` 全绿
|
||
- [ ] 核心代码覆盖率 ≥ 80%
|
||
- [ ] gofmt/ruff 等价: ruff check data/channel_sync 0 warning
|
||
- [ ] 文档落地:本文件 + CHANGELOG + IMPLEMENTATION_PLAN 更新
|
||
- [ ] 已提交到本地 git,推送 3 仓(GitHub/tksea/gitea-local)
|
||
|
||
---
|
||
|
||
## 9. 风险与缓解
|
||
|
||
| 风险 | 可能性 | 影响 | 缓解 |
|
||
| ----------------------------- | ------ | ---- | --------------------------------------------------- |
|
||
| 闲鱼未公开 Webhook 协议 | 高 | 高 | 本设计采用通用 HMAC 模式,可在签约开放平台时按需调整 |
|
||
| 平台限流 / IP 黑名单 | 中 | 中 | poller 兜底 + 退避重试 |
|
||
| 客户身份证号出现在 Webhook 中 | 中 | 高 | 接收时丢弃 PII 字段,审计记录 reject_reason |
|
||
| 订单状态与闲鱼侧不一致 | 中 | 中 | 状态机强制约束 + 历史审计,异常告警 |
|
||
| 测试覆盖率不达 80% | 低 | 中 | TDD 强制,先写单测再实现 |
|
||
|
||
---
|
||
|
||
## 10. 不在本期范围
|
||
|
||
- 微信 SDK 生产联调与企业认证申请（本任务仅落地标准库 client + payload/错误处理封装）
|
||
- 闲鱼 IM 消息自动回复(属客服机器人,独立产品)
|
||
- 闲鱼退款自动审批(人工审核更安全)
|
||
- 多渠道统一网关(等 T8.1/T8.2/T8.3 都稳定后做抽象层)
|