live-hub-py/docs/自动化与资料收集规划.md

自动化与资料收集规划

更新时间：2026-10-02 状态：P1a（CK 巡检）+ P1b（CK 自动重登）已上线；P0 适配层已完成并真机验证（无接口/页面、开关仍关、生产未跑迁移）；下一步 P2。产品决策已确认（见 §4），施工单见附录 C。

🔜 续作入口（下一个会话先看这里）

1. 当前该做 P2（资料收集链接 + OSS 上传），施工顺序见 §C.5，下一个迁移编号 20261003_0042；
2. P0 的适配层已就绪（services/external_order_source.py，lookup_order() 直接可用）， P2 做「用户填订单号后回显商品」时直接调它，不要重写跨库 SQL；
3. P0 遗留三件事（要真正启用时才做）：生产跑迁移 0039 建表、.env 开 ORDER_SITE_LOOKUP_ENABLED、补查询接口/页面（见 §C.4-bis）；
4. 上手前必读 §C.2 通用约定（方言、时区、环境变量三处同步、迁移编号取号规则、 「动手前先核实外部库真实表结构」）与 §C.3 已核实的环境事实。

---

1. 背景

当前后台的日常动作基本都要人工点：判断 CK 是否失效、失效后重登、和用户来回沟通收集资料、手工记录兑换过的皮肤。人工环节一多就会出现三个问题：

1. CK 维护不及时 —— 账号放着不管，等到客服要跑任务时才发现 CK 失效；临时重登又可能赶上邮箱验证码配额被打满；
2. 信息靠人转述 —— 用户在聊天里发订单号、游戏名、主页截图，客服再抄进系统，容易抄错、抄漏、无法追溯；
3. 兑换历史无台账 —— 谁在什么时候兑过什么皮肤只看聊天记录，无法执行「一年内同一件皮肤只兑一次」的规则。

目标是把这几块沉淀成系统能力，最终拼成一条半自动流水线：客服只做「发链接」和「点执行」两件事。

现状是全人工，因此本规划的基本原则是「逐步减少人工」，不是一步到位全自动（见 §5.1 第 5 条）。

2. 术语表

术语	含义
订单号 / order_no	用户在快手（或拼多多）下单后拿到的平台订单号，如 2627501841217849
订单快照	从 order_site 读到的订单信息（platform / sku_code / sku_name / order_status）在本地留档，防止外部数据变动导致无法追溯
route	订单去向判定（只看 order_site 的客观事实）：unhandled（既无履约任务也无接单平台工单，没人管 → 本系统候选）/ auto_fulfilled（有履约任务，发货平台已处理）/ worker_platform（有接单平台工单，打手已处理）
皮肤 / skin	游戏内可兑换的外观类商品（套装 / 头盔 / 背包 / 枪皮等），是本系统实际要兑换的东西
skin_key	皮肤标准名，365 天规则的唯一判定键（由 C 桶皮肤类的 923 个原始商品名归一而来，具体收敛数待分析）
别名	同一件商品的各种写法：快手 relSkuId / relItemId / skuNick、斗鱼商品名
skuNick	快手 SKU 规格名 —— 买家真正买的那件东西（比店铺标题 itemTitle 精确，§3.6）
relItemId / relSkuId	快手商品 ID / SKU ID，(itemId, skuId) 是单个订单的精确定位键
工单 / exchange_order	一笔兑换任务的载体：订单快照 + 用户资料 + 执行账号 + 状态 + 结果
资料模板	配置「要用户补哪些字段」，本系统固定为 游戏编号 / 游戏昵称 / 主页截图
兑换规则	配置「什么订单 → 对应哪个皮肤 → 用哪个斗鱼商品兑换」
台账	account_exchange_records：账号 × 皮肤 × 时间的兑换历史
CK	斗鱼账号的登录 Cookie；本系统用「CK 有效/失效」描述账号状态
attempt	一次登录/重登尝试，落在 login_tasks.attempt_* 字段上，与账号持有的 CK 分离

3. 现状盘点

3.1 可直接复用的能力

能力	现状	位置
CK 有效性判定	check_douyu_cookie() 双接口（鱼丸 + 等级）同时通过才算有效	web/backend/services/cookie_check_service.py
检测结果持久化	login_tasks.ck_check_status / ck_check_result / ck_checked_at	已落库
批量检测	POST /api/cookies/check、/api/cookies/operations/check	web/backend/routers/cookies.py
批量重登无效 CK	POST /api/cookies/operations/relogin-invalid	同上
重登执行器	LoginBatchRunner(mode="relogin")：成功才替换 CK、attempt_* 状态机、可停止、重启会收敛	web/backend/services/login_service.py
邮箱配额信号	EmailQuotaError（斗鱼返回「发送次数已达上限」时抛出，只影响该账号）	core/douyu/login.py
商品/皮肤快照	douyu_goods_snapshot（名称、积分、库存、raw）—— 实测只有 78 个可兑换商品（皮肤类 60），这就是我们能兑的全部（§3.5）	已落库
斗鱼侧兑换记录	client.exchange_records(manual_id) + query_exchange_records 任务	core/douyu/activity_client.py:950
任务编排	douyu_tasks（批次/账号/类型/结果/时间）+ DouyuBatchRunner	已成型
权限与审计	PERMISSIONS / ROLE_PERMISSIONS + audit_logs	已成型
部署形态	单容器（应用 + worker）；Caddy 反代 live.khhao.com → douyu-login:8800；./data、./logs 持久化	docker-compose.yml

3.2 缺口

1. 没有任何定时/调度机制 —— 全项目只有 HTTP 触发 + 进程内线程，没有 scheduler；
2. 没有文件上传与存储 —— UploadFile 全项目未使用，也没有对象存储依赖（oss2 未安装），还没有公开（无鉴权）页面；
3. 没有兑换台账 —— 兑换历史散落在 douyu_tasks.result 里，无法按「账号 × 皮肤 × 时间」查询；
4. 没有订单概念 —— 用户手里的「订单号 → 商品/皮肤」不在本系统，需与 order_site 整合（见 §3.3）；
5. POST /api/login/batch 没有审计记录 —— 自动化要可追溯，需补上。

3.3 外部依赖：order_site（快手自动发货系统）

项目：/Users/yml/codes/order_site、仓库 gitea.hao858.com/yml/order_site.git，与本系统同一台服务器部署（order_site-web-1 / order_site-backend-1 / order_site-postgres-1，Caddy 反代 worker.khhao.com）。

它已经持有「订单号 → 商品/皮肤」这层数据（2026-10-02 线上 PostgreSQL 实测）：

事实	数据
订单量	271,032 单（快手 268,436 / 拼多多 2,596）
订单与商品明细	1 单 = 1 件商品（271,024 单为 1:1）
关键字段	orders.platform_order_id（订单号）+ order_items.sku_code / sku_name
实例	2627501841217849 → suit_shadow_gothic / 套装-暗影哥特
商品名种类	distinct sku_name 1,514 个；distinct sku_code 4,241 个
语义化皮肤码	非纯数字 code 共 173 个（suit_* / helmet_* / bag_* / 中文名）

两条关键结论（直接决定本规划的数据模型）

1. 统计归类要看名称，单订单定位要看 SKU：同一个商品名（如「指挥官密钥5个」）会对应 30~45 个不同数字 sku_code（不同店铺/不同时期的 item 各挂一个），所以按名称做归类统计；但单个订单的 (relItemId, relSkuId) 精确指向一件具体商品（详见 §3.6）；
2. 同一件皮肤有多种写法：实测「套装-浪漫天命」至少三种形态—— sku_code=套装-浪漫天命 / sku_name=套装-浪漫天命、sku_code=suit_romantic_destiny / sku_name=套装-浪漫天命、sku_code=套装-浪漫天命 / sku_name=浪漫天命。 按名称当 key，365 天规则会失效（同一件被当成三件）—— 所以判定键最终落在斗鱼商品上（§3.5）。

它已有的、与本规划同形但语义不同的能力

order_site 能力	说明	与本规划的关系
/api/collect/lookup · submit · upload	凭订单号查待完善单 → 动态字段 → 上传截图 → 提交	面向打手工单（work_orders），字段由 fulfillment_profile_requirements 决定，语义不同；实现模式与资料模板结构可直接借鉴
file_assets + /api/v1/files/object	阿里云 OSS（私有桶 order-site-assets），sharp 生成 thumb(480)/medium(1280) 变体；DB 只存 object_key，图片通过自己的后端代理读取（带 ETag/304）	P2 的图片存储照这个模式做（§8.3）
claim_tokens + /api/claims/:token	用户领取页令牌（有效期 / 次数）	P2 的 token 设计可对齐
POST /api/open91/orders/query	面向 91 卡券的签名鉴权订单查询	证明跨系统调用可行，但返回的是发货状态，不含 sku
限流中间件 createRateLimitMiddleware	公开接口按字段/参数限流	P2 可参考阈值设计
接单平台的规则/模板/状态机	见 §10.0	P4 的整体设计蓝本

当前没有：面向内部系统的通用 API Key 鉴权、按订单号返回商品明细的内部接口。（/api/admin/orders 需要后台管理员 session。）

3.4 order_site 的订单路由：决定「哪些订单需要来这边」

实测（2026-10-02）：order_site 把订单二选一路由，fulfillment_tasks 与 work_orders 完全不重叠（both = 0，共 271,134 单）：

桶	判据	规模	典型商品	来 live-hub-py？
A 已自动发货	有 fulfillment_tasks	85,338	套装-浪漫天命 / 套装-暗影哥特 / 国宝胖达头盔 / 萌熊伴侣背包	❌ 不要（发货平台已处理）
B 接单平台	有 work_orders（打手众包）	96,755	指挥官密钥 / 荣耀专属礼盒 / 苏尔南钻石 / 暮色之下礼盒	❌ 不要（打手已处理）
C 无人处理	两张表都没有	89,542	兔兔白日梦 / 狂战萌兔 / 青涩年华 / 黑色ROCK长袖 / 幸运币2个	✅ 要（本系统的目标）

为什么 A 桶不要（fulfillment_tasks.delivery_status 实测）：

通道	delivered	cancelled	closed	pending
affiliate_dash	29,713	1,044	433	569
kuaishou_ct_assisted	39,697	3,154	2,452	1,591
kuaishou_feifei	6,216	507	113	171
合计	75,626（88.3%）	4,705	2,998	2,331

判据方向：A、B 都是「已经有人管」的订单（发货平台 / 打手），只有 C 是「没人管」——才轮到我们。 （这一版推翻了本规划早期把 A 当成目标的判断：A 桶 88.3% 已 delivered，是发货平台的活。）

C 桶内部分类（1,227 个商品名 / 89,542 件，按商品名关键词粗分）：

子类	件数	名字数	典型商品	处理
① 服装类	17,704	19	黑色ROCK长袖+10幸运币 / 蓝色运动服上衣-黑色ROCK(2选1）	⏸ 后面单独处理（负责人已定）
② 卡券/道具类	17,948	202	幸运币2个 / 9月改名卡 / 指挥官密钥 / 礼盒	❓ 待确认（疑似走电子凭证自动发码）
③ 纯数字商品名	4,491	83	100089 / 99999 / 100033	❓ 待确认（需人工识别是什么）
④ 皮肤/套装类	49,400	923	兔兔白日梦 / 狂战萌兔 / 青涩年华 / 风蚀行者 / 猫布灵 / 雪山精英 / AUG-魔性柴柴 / 浪漫波比 / 暮夜私语	✅ 现在做

④ 里混着大量 SEO 堆词的商品名（如「和平精英皮肤小店入口浪漫天命黑色上衣暗影哥特雪国小丑木乃伊」「和平精英熔岩游骑兵胖达团团圆圆萌熊伴侣背包雪山精英兔兔白日梦」），923 个原始名归一后应明显收敛，具体收敛到多少要先跑一遍归一分析（见 §9.2）。

准入判据（两层，缺一不可）

层	判据	回答的问题
第一层：外部事实	fulfillment_tasks 与 work_orders 都不存在（route = unhandled）	这单是不是没人管？
第二层：我们的配置	商品能匹配到「皮肤兑换规则」（§10.1）	这单的皮肤我们做不做？

两层串起来正好把「P0 的 route 判定」和「P4 的规则匹配」接上：route 决定候选范围，规则匹配决定最终放行。

分阶段落地：P2（收集链接）上线时 P4 的规则匹配还没有，此时只能做第一层（route=unhandled 放行 + 客服受理时人工把关）；P3/P4 上线后再加第二层收窄。

3.5 我们实际能兑什么：斗鱼商品目录才是真正的边界

douyu_goods_snapshot 实测（2026-10-02）：只有 78 个可兑换商品，全部来自手册 20260120QYOOB（精英宝典）—— 皮肤类 60 个、非皮肤 18 个（体验卡 / 改名卡 / 幸运币礼包 / 精英火箭等）。

把 C 桶皮肤类那 923 个快手商品名往这 60 个皮肤类商品上映射：

类别	快手名	件数	占比	处理方式
✅ 唯一命中斗鱼商品	62	13,678	27.7%	订单可自动确定皮肤 → 直接建单
⚠️ 命中多个	14	6,122	12.4%	必须让用户在链接里选一件
❌ 斗鱼兑不了	847	29,612	59.9%	拒绝（斗鱼没有对应商品）

结论：斗鱼现有商品只能覆盖 40.1% 的 C 桶皮肤订单。 剩下近 6 成（青涩年华、风蚀行者、雪山精英、AUG-魔性柴柴、浪漫波比、暮夜私语、顽皮橙 …）斗鱼根本没有对应商品，做不了。

锚点必须是斗鱼商品，不是快手商品名。 快手那 923 个名字最终都要落到这几十个商品上：映射得上 = 能做，映射不上 = 做不了。 完整商品清单、可映射的 76 个快手名、兑不了的 Top 40 见 皮肤准入映射分析。

3.6 SKU 才是精确定位键（匹配层按这个来）

order_items.spec_json 已经带了定位所需的全部字段，不需要解析商品名文本：

{
  "skuId":     "192758405127439",     // 快手 SKU ID
  "skuNick":   "（3选1）甜心娇蕊-清雅山茶-紫梦罗兰",  // SKU 规格名（比 itemTitle 精确）
  "sellerId":  "4661340439",
  "relItemId": "25228845231439",      // 快手商品 ID
  "relSkuId":  "",
  "itemTitle": "和平精英皮肤小店入口浪漫天命黑色上衣暗影哥特雪国小丑木乃伊",  // 店铺商品标题（SEO 堆词，不可靠）
  "source":    "kuaishou_send_code",
  "paymentFen": 10300
}

一个 item（皮肤小店）挂多个 SKU，每个 SKU 就是一件具体商品 —— 实测同一 relItemId=25228845231439 下：

skuId	skuNick
187748927889439	兔兔白日梦
187748927890439	狂战萌兔
192651207500439	黑色ROCK长袖+10幸运币
193618786956439	冥河战士大礼包
177839563418439	青涩年华
191455593788439	风蚀行者

所以：itemTitle 是店铺标题（堆词，没用），skuNick / skuId 才是买家真正买的那件东西。 实测 4,092 个数字 skuId 中 89% 只对应一个 skuNick；另外 11% 是跨 item 复用，用 (relItemId, relSkuId) 组合即可区分。

接单平台就是按 SKU 定位的（work_product_rule_mappings 实测）：

mapping_type	定位字段	真实例子
sku_exact	rel_sku_id（单个或多个快手 SKU ID）	191555220780642 → 小金人+金AUG+金M338；191555220783642 → 红雪隼AA12
sku_exact	rel_item_id（多个 item ID）+ sku_nick	rule 237：11 个 item ID + 指挥官密钥
sku_series	sku_nick 前缀	指挥官 / 碎梦浮光珍宝礼盒 / 突击兵
product_default	rel_item_id 或 item_title	兜底

本系统的映射层照抄这个结构（§10.1）：精确 SKU 映射覆盖高频商品，文本归一只做兜底。 顺带修正本规划早期的一个错误结论：不是「数字 skuId 不能用」，而是「跨 item 会重复，所以要用 (itemId, skuId)」。

4. 产品决策（已确认）

#	决策
1	邮箱验证码配额打满只针对单个账号：跳过该账号、按天退避，不暂停整个批次
2	CK 巡检频率默认 6 小时，可在后台配置
3	收集链接不做复杂进度回执；兑换成功后用户通过同一个链接能看到结果
4	同一皮肤判定用滚动 365 天；判定键是斗鱼商品（skin_catalog.commodity_id），不是快手商品名 —— 因为一个斗鱼商品对应多个快手写法（§3.5）
5	用户填的订单号只做基础处理：非空 + 唯一 + 去除空白字符
6	命中 365 天规则时允许强制兑换，但仅超管且必填原因（写审计）
7	收集提交的可见范围：归属客服 + 运营/超管
8	资料模板字段固定为 游戏编号 + 游戏昵称 + 主页截图；皮肤优先由订单号自动对应；仅当订单命中多个斗鱼商品时（「3选1」「小店自选」类，占 12.4%），才让用户在链接里选一件
9	兑换不涉及「加好友后赠送」，状态机不需要"等待可赠送"等待态
10	订单准入分两层：① 订单在 order_site 里既无履约任务、也无接单平台工单（route=unhandled，即「没人管」）才进入候选；② 候选订单的商品必须命中皮肤兑换规则才放行。其余一律提示「该订单暂不支持，请联系客服」，客服可在后台人工放行（留审计）
11a	重登失败按原因分型（relogin_failure_kind），不是笼统「失败」：极验/凭证问题转人工，取码/中断/网络自动重试，配额满退避到次日（详见 §7.4.3）
11	准入白名单以斗鱼商品目录为准：能映射到 douyu_goods_snapshot 的才放行；映射不到（占 C 桶皮肤订单 59.9%）直接拒绝 —— 因为斗鱼兑不出来。不匹配就不建单，后续按实际数据逐步放宽
12	匹配优先按 SKU 精确定位（relSkuId / skuNick），商品名文本只作兜底（§3.6）—— 接单平台已是这个做法

5. 总体架构决策

5.1 五条原则

1. 调度器放进程内，状态全部落库 新增一个 60s tick 的 daemon 线程；作业定义、开关、间隔、上次/下次运行时间、每轮结果都写库（automation_jobs / automation_runs）。进程重启不丢状态，也不会因为重启而重复跑一轮。

2. 自动化只做「决策 + 排队」，执行仍走现有批次 复用 LoginBatchRunner / DouyuBatchRunner，不另写执行器。这样人工和自动共用同一条安全链路（attempt_* 状态机、停止信号、启动清理、CK 只在成功时替换）。

3. 公开入口单独一条链路 收集链接是全新的无鉴权入口，按「最小暴露 + 强限流 + 图片二次编码」设计，不与内部接口共用鉴权中间件。

4. 单容器前提 不做分布式锁；用「数据库里的在途状态 + 进程内作业锁」避免重入即可。将来若多副本部署，再引入 DB 级 advisory lock。

5. 渐进上线：每一步都保留人工入口，自动化只是"少点几下" 现状是全人工，目标是逐步减少人工，所以每条自动化都必须：

   • 有独立开关，默认关闭，观察一段时间再打开；
   • 人工入口原样保留（人工检测 / 重登 / 建单 / 执行都还能走）；
   • 出问题能回退到人工，不做不可回退的自动执行（尤其涉及花钱的支付环节，永远人工扫码确认）；
   • 先做「只读 / 只提示」，确认数据无误后再做「自动动作」。

5.2 与 order_site 的整合方式

结论：只整合「订单号 → 商品/皮肤」这一段；收集链接在 live-hub-py 自建。

理由：P4 的工单、P3 的台账、兑换执行全在 live-hub-py，让用户提交的数据与工单同库，链路最短；order_site 的 collect 是打手侧语义，硬套会把两套业务搅在一起。

原则：order_site 一行代码都不改，也不改它的部署，把「读订单」的能力放在 live-hub-py 一侧。

方案对比（核心诉求：改需求时只改一处）

方案	要改 order_site？	契约	契约稳定性（实测）	运行时依赖	改需求时改几处
A. 在 order_site 加内部 HTTP 接口	要（写接口 + 鉴权 + 发版）	我们设计的 HTTP 字段	中：接口由我们定，但每次调整都要对方配合发版	强	2 处 ❌ 已否决
B. live-hub-py 只读直连 PG ✅ 采用	不要（仅一次性建只读账号）	orders / order_items / fulfillment_tasks / work_orders 的少数几列（只判存在性 + 取 sku）	极高：88 个迁移里 orders/order_items 从未 ALTER	强（有缓存与降级开关）	1 处
C. 定时同步进本地表	不要（读法同 B）	同 B + 同步器	高	弱（本地有副本）	1 处（多一个同步作业，可复用 P1 调度器）
D. 完全不整合，用户从斗鱼商品下拉选皮肤	不要	无	—	无	1 处 ❌ 已否决（决策 8：皮肤由订单决定）

A 之所以「改两处」，不是因为要读数据，而是因为把读接口的实现放进了对方系统。 B/C 把读的能力收回自己这边，order_site 就彻底静止了。

实测支撑（2026-10-02）

• 网络已通，不需要动 order_site 的部署：live-hub-py-douyu-login-1 同时挂在 live-hub-py_default 与 order_site_default 两个网络上，实测可直连 order_site-postgres-1:5432（172.19.0.2）。这是 Caddy 反代时加的，属于既有事实；
• 表结构极稳：order_site 共 88 个迁移，orders / order_items 自 001 基线以来从未被 ALTER；我们只需要 platform_order_id、sku_code、sku_name、order_status（外加 platform），全部是外部平台透传字段；
• 查询走索引：idx_orders_platform_order_id btree (platform_order_id) 存在，单按订单号查也能命中（另有 (provider, platform, platform_order_id) 复合索引；线上 provider/platform 只有 91kaquan/kuaishou 与 pdd/pdd）。

具体实现见 §6 P0。

6. P0 · 订单读取适配层

6.1 目标

让本系统能「凭订单号知道这是什么订单、要不要我们处理、对应哪件皮肤」，同时对 order_site 零代码改动、零部署改动，且出问题时能一键降级。

6.2 数据模型（迁移 1 个）

external_order_cache（订单快照）：platform_order_id + source_order_id（联合唯一；对应 order_site orders.platform_order_id 与 orders.id）/ platform / provider / shop_id / order_status / sku_code / sku_name / seller_id / rel_item_id / rel_sku_id / sku_nick / item_title / quantity / route / payload(JSON) / fetched_at

⚠️ 2026-10-02 修订：order_site 没有 order_no 列，主键改为 platform_order_id + source_order_id。 后者不可省 —— 同一个 platform_order_id 有 541 组重复（详见 §6.5.1），按单列存会互相覆盖。

用途：用户提交订单号时立即回显商品；工单与台账留档；order_site 不可用时降级。 缓存有效期建议 24 小时（订单状态可能变化，过期后重查）。

6.3 适配层接口

所有跨库 SQL 只允许出现在一个文件里：web/backend/services/external_order_source.py。将来表结构或数据源变化，只改这一个文件。

对外只暴露一个语义化方法：

lookup_order(order_no) -> {
    order_no, platform, provider, order_status,
    sku_code, sku_name, route,          # route ∈ {unhandled, auto_fulfilled, worker_platform}
    seller_id, rel_item_id, rel_sku_id, # SKU 定位键（取自 spec_json，§3.6）
    sku_nick, item_title,               # SKU 规格名 / 店铺标题
    cached: bool, error: str | None,
}

• route 由 §3.4 的互斥判据得出：有 fulfillment_tasks → auto_fulfilled；有 work_orders → worker_platform；都没有 → unhandled。业务代码只认 route，不认 SQL 细节；

  ⚠️ 按 §6.5.1 的决策 2，判定要在「订单号维度」聚合：按 platform_order_id 取到全部行， 任一行有 fulfillment_tasks 即 auto_fulfilled（540 个已发货的重复组靠这条拦住）。

• 查询顺序：先查 external_order_cache（未过期）→ 未命中再查 PG → 回写缓存。
• 入参 order_no 实际就是 platform_order_id（对外仍叫 order_no，保持接口语义稳定）。

6.4 准入规则（用户填订单号时）

route	第一层处理	第二层（命中皮肤兑换规则？）
unhandled（两张表都无）	✅ 候选，继续第二层	命中 → 放行建单；未命中 → 拒绝或人工归类
auto_fulfilled（有 fulfillment_tasks）	❌ 拒绝：「该订单已由发货平台处理，无需在此提交」	——
worker_platform（有 work_orders）	❌ 拒绝：「该订单由接单平台处理，无需在此提交」	——
查不到订单	❌ 拒绝：「订单号不存在，请核对」	——
order_site 不可用	⚠️ 允许提交但快照为空、标记 order_unverified，交客服人工确认	——

第二层依赖 P4 的规则匹配；P2 阶段先只做第一层，客服受理时人工把关（见 §3.4 分阶段落地）。

6.5 只读保护（对对方生产库）

✅ 已在生产落地（2026-10-02）：

项	实际值
角色	livehub_ro（CONNECTION LIMIT 5）
授权	SELECT on orders / order_items / fulfillment_tasks / work_orders（仅这 4 张）
超时	statement_timeout = 3s、idle_in_transaction_session_timeout = 15s
写保护	default_transaction_read_only = on —— 物理上写不了（实测 CREATE TABLE 被拒）
越权	实测查 admin_users → permission denied ✅
连接串	ORDER_SITE_DATABASE_URL 已写入 /root/live-hub-py/.env（ORDER_SITE_LOOKUP_ENABLED=false，默认关）

应用侧仍需遵守：只走单行索引查询、禁止全表扫描与聚合；独立连接池且极小（2 条），不影响本系统主库连接池。

⚠️ 实现前提：应用容器里没有任何 PostgreSQL 驱动（psycopg / psycopg2 / asyncpg / pg8000 全未安装，只有 SQLAlchemy 本体）。 P0 必须往 pyproject.toml 加一个驱动，三选一：

• ✅ psycopg[binary]（已定），SQLAlchemy 2.0 原生支持，URL 用 postgresql+psycopg://
• （备选：psycopg2-binary / pg8000 纯 Python）

适配层要把 .env 里的 postgresql:// 归一成带驱动的 URL（如 postgresql+psycopg://）后再交给 SQLAlchemy。

6.5.1 ⚠️ 实测偏差：没有 order_no，且同一订单号跨桶重复（2026-10-02 上机核实）

在生产机（order+douyu_huya）用只读账号 livehub_ro 实测，§6.2/§6.4 的两处假设与真实库不符。P0 必须按本节实现：

项	规划原文	实测
订单号列	order_no(PK)	❌ 不存在。只有 id（内部 bigint PK）与 platform_order_id（用户手上的快手单号）
platform_order_id 唯一性	隐含唯一	❌ 非唯一：276,371 行 / 275,830 个号 → 541 个号重复
重复的形态	——	541 组全部是 n=2, shops=2：shop_id='91kaquan' 行 + 一个真实店铺行
重复组的分桶	——	540 组跨 A/C 桶：91kaquan 行有 fulfillment_tasks（delivery_status = delivered/closed）→ A；真实店铺行无 A/B → C
影响面	C 桶 89,542	C 桶实测 91,029 行 / 91,028 个号，其中 540 个号的同一单已被 91kaquan 发货

决策（已确认）

1. 查询入口 = platform_order_id（用户/客服填的快手订单号），走 idx_orders_platform_order_id 索引；orders.id 只作内部关联，不当对外入口；
2. route 判定改为「订单号维度聚合」：按 platform_order_id 取全部行， 任一行命中 fulfillment_tasks → auto_fulfilled；否则任一行命中 work_orders → worker_platform；都没有 → unhandled。

   不这么做，这 540 个已发货订单会被误判为「没人管」而放行重复履约 —— 与 §3.4「A 桶不要」直接矛盾。

3. 回显的 SKU 取真实店铺行（shop_id != '91kaquan'，带 sku_code / sku_name / spec_json）； 91kaquan 是发货方内部行（provider=91kaquan、automation_mode=manual、sku_code 形如 suit_shadow_gothic），不用于展示。

缓存表主键相应改为订单号 + 店铺行（见 §6.2 的 order_no → platform_order_id，并带 source_order_id），避免多行互相覆盖。

6.6 降级开关

ORDER_SITE_LOOKUP_ENABLED=false 时完全不查外部，退化成「客服手工填订单信息 + 人工确认」，主流程照常可用。

若将来想要「零运行时依赖」，把「按需查」升级为「定时增量同步」（§5.2 方案 C），同步作业直接挂到 P1 的调度器上，不引入新机制。

6.7 验收标准

1. 输入一个 A 桶订单号（有履约任务）→ route=auto_fulfilled，被正确拒绝；
2. 输入一个 B 桶订单号（有接单平台工单）→ route=worker_platform，被正确拒绝；
3. 输入一个 C 桶订单号（如「兔兔白日梦」的订单）→ route=unhandled，进入候选并带出 sku_name；
4. 输入不存在的订单号 → 明确提示「订单号不存在」；
5. 关掉 ORDER_SITE_LOOKUP_ENABLED → 系统仍可正常走手工流程；
6. 查一次订单对 order_site 的负载可忽略（单行索引查询，实测 < 50ms）；
7. 输入一个「重复订单号」（91kaquan 行已发货 + 店铺行无人管，共 540 个）→ route=auto_fulfilled，不被放行（§6.5.1）。

7. P1 · CK 自动管理

7.1 目标（分两步，不要一次上）

• P1a（先做）：把「哪些账号 CK 失效了」自动找出来并展示 —— 只检测、只标记、只提示，不改动任何 CK；重登仍然人工点。
• P1b（观察后再开）：把「失效账号自动重登」也自动化 —— 有退避、有熔断、有开关，默认关闭。

P1a 已落地（2026-10-02），实际落点： services/automation/scheduler.py（调度线程 + 到点判定 + 运行记录）、 services/automation/jobs/ck_health.py（巡检作业）、 routers/automation.py（4 个接口）、permissions.py（automation:view / automation:manage）、 migrations/versions/20261002_0037_automation_jobs.py、 前端 pages/AutomationPage.tsx（菜单「自动巡检」）、 tests/test_automation_ck_health.py（22 条）。 端到端已用 3 个真实账号验证：巡检结果与直接检测逐条一致，且 cookie / status / message / attempt_status 全程未变。

生产上线记录（2026-10-02）

按三段走完，全部通过：

段	动作	结果
①	AUTOMATION_ENABLED=true + 重启	容器内变量生效，日志「自动化调度器已启动，tick=300s」
②	手动跑一轮（每轮 50 条，作业开关仍关）	success，50 条 / 7 秒，斗鱼无风控反应（无验证码、无频控、无超时）
③	每轮 200 条 + 打开作业开关	调度器自动接管：12:27:26 → 12:27:48 跑完 200 条（22 秒），next_run_at 按 tick 推进到 +5 分钟

上线过程中抓到（并已修）两个只有生产才会暴露的问题，都已在 §C.2 记档：

1. NULLS FIRST 在 SQLite 合法、MySQL 报 1064 → 改用 col IS NULL DESC，并加了一条按 MySQL 方言 compile() 的回归测试；
2. compose 的 environment: 是显式列表，只写 .env 不会传进容器 → AUTOMATION_ENABLED 起初根本没生效（顺带发现早先写入的 ORDER_SITE_* / OSS_* 也全都没传进去）。

首轮数据结论（供客服侧预期管理）：前几轮 100% invalid 属正常且正是价值所在 —— 选行是「从没检测过的优先」，而积压的 1,897 条未检测记录里大部分是 2026-08-04 一次性批量导入、attempt_status 为空（从未尝试登录）、CK 已放两个月的陈旧账号。错误信息统一是斗鱼侧的「用户未登录」，不是风控。按 200 条/5 分钟，约 5.4 小时扫完全库积压后进入稳态。

注意：巡检会把这些陈旧账号的 ck_check_status 从空翻成 invalid，客服在「CK 检测与重登」页会突然看到大批失效账号 —— 这是预期行为，不是故障。

7.2 数据模型（迁移 1 个，P1a/P1b 共用）

新表 automation_jobs

字段	说明
key (PK)	作业标识：ck_health / ck_relogin
title	展示名
enabled	开关（默认 false）
interval_seconds	单账号重检间隔（CK 巡检默认 6h）—— 注意不是作业运行周期，作业每个 tick 都跑（见 §7.3）
batch_size	单轮处理上限（ck_health 默认 200，按「5 分钟一轮 × 200 条 = 40 条/分钟 ≥ 需要的 36 条/分钟」反推，见 §7.3；ck_relogin 默认 20）
concurrency	单轮并发
config (JSON)	作业私有配置（退避表、每日上限、失败率阈值等）
last_run_at / next_run_at	调度用
last_status / last_message	最近结果
updated_at

新表 automation_runs：id / job_key(索引) / started_at / finished_at / status / scanned / valid / invalid / relogin_started / relogin_success / skipped / message / detail(JSON)

login_tasks 增字段：relogin_attempts(int, 默认 0) / relogin_next_at(datetime, 可空) / relogin_last_error(string)

accounts 增字段：auto_managed(bool, 默认 true) —— 给特殊账号留「不自动动」的后门

7.3 P1a · 作业一：ck_health（巡检，只检测）

• 选取范围：从持有 CK 的 login_tasks 行里挑（即现有 cookie_holding_filter() 的口径：cookie is not null and cookie != ''）—— CK 是挂在登录记录上的，不是挂在 accounts 上；

• 调度：每 5 分钟跑一轮（TICK_SECONDS = 300）；每轮挑「距上次检测超过 interval_seconds（默认 6h）」的行，最多 batch_size（默认 200）个。 这样全库是滚动覆盖的，负载平稳，不会出现「整点扫 1.2 万个账号」的尖峰；

• ⚠️ 两个「间隔」不能混：TICK_SECONDS 是作业多久跑一轮；job.interval_seconds 是同一行数据多久重新检测一次（只用于选行 cutoff）。 如果误把作业周期设成 interval_seconds，就变成「200 条/6 小时 = 800 条/天」，全库 12,881 条要 16 天才能过一轮 —— 等于没巡检（P1a 实现时踩过一次，已修）；

• 排除：auto_managed = false；attempt_status in (pending, running)（正在被批次处理）；最近 10 分钟内刚检测过（防重入）；

• 动作：调用现有 check_douyu_cookie()（两个只读接口，直连），写回 ck_check_status / ck_check_result / ck_checked_at；

• ⚠️ 三类判定（关键防护）：检测失败不等于 CK 失效，结果必须分三类处理，否则斗鱼接口抖动一小时就能把上千个好账号标成失效、让客服误判成「CK 大面积挂掉」：

  判定	依据	处理
  valid	两个接口都通过	写 ck_check_status='valid'
  invalid	斗鱼明确回「未登录 / 登陆异常 / 请重新登陆」	写 ck_check_status='invalid'
  error	其余失败（请求失败: 超时、响应异常、未知结构、走异常兜底）	不覆盖该行原结论，只更新 ck_check_result（带 verdict）与 ck_checked_at，计入 skipped

• 自动暂停：一轮里 error 占比 > 30% 且条数 ≥ 20 时，作业把自己 enabled 置 false 并在 message 写明原因（detail.paused=true）—— 大面积「查不到」通常是接口抖动或被风控，继续跑只会污染更多账号；

  注意：真实死号占比高不触发暂停。首轮 100% invalid 是合法且预期的情况（选行是「从没检测过的优先」，积压的多是两个月前批量导入、从未登录的陈旧账号）。

• 并发：默认 5，沿用现有 ThreadPoolExecutor 模式；

• 不做：不改 CK、不建重登批次、不动 login_tasks.status。

容量测算（真实数据，2026-10-02 实测）

指标	数值
持有 CK 的 login_tasks 行	12,881（12,880 个账号；总账号 13,529）
当前状态分布	valid 10,079 / invalid 905 / 从未检测 1,897
历史检测时间	最早 2026-08-07，最新 2026-10-02（人工零星跑的）

按「单账号 6 小时内重检一次」折算：

需要吞吐 = 12,881 ÷ 6h ≈ 36 行/分钟
一个 tick = 5 分钟 → 每轮需要 ≈ 180 行
单行耗时 ≈ 0.13s（实测 3 个账号 0.4s，并发 3）→ 180 行并发 5 约 5 秒/轮  ← 很轻松

batch_size 默认 200（比需要的 180 留一点余量）：

• 冷启动：全库积压 12,881 条，按 200 条/5 分钟 ≈ 5.4 小时跑完第一遍，随后进入稳态；
• 稳态：每分钟约 36 条到期，每轮扫到一百多条，负载很轻；
• 取行按 ck_checked_at ASC（最久没查的优先，NULLS FIRST），自然错峰，不会同一时刻全量到期。

7.4 P1b · 作业二：ck_relogin（自愈，默认关闭）

这一节 2026-10-02 按线上实测数据重写过。 原来的设计只有「退避 + 熔断 + 开关」， 数据表明那样不够：失败必须分型，否则 64% 本可自动解决的失败会被当成人工活。

7.4.1 为什么必须和 P1a 联动（数据）

巡检只产出「谁失效了」的清单，不兑现修复，1,000+ 个账号还是要人工逐个选集→点重登→过滑块。 线上实测（2026-10-02）：

项	数值	依据
当前失效	1,356（还在涨，巡检在排空积压）	ck_check_status='invalid'
其中「还没在 attempt_* 时代重试过」	941	纯新机会
其中「最近一次重登失败过」	415	已有失败记录
历史重登真实成功率	≈78%	成功 1,767 ÷ (1,767 + 真实失败 508)，已排除「中断/停止」这类非真失败
预计可自动救回	≈1,050	1,356 × 78%
预计需人工	≈300	主要是极验滑块

关键结论：失效是「会话级」而不是「凭证级」。 斗鱼对这批账号回的是「用户未登录」， 不是「密码错误」；而这些行本来都是登录成功的产物（见下）。

「持有 CK 的行 = 真实登录成功过」的依据：LoginTask 全项目只在一处创建 —— services/login_service.py（登录成功写回 CK 处）；导入账号不建 LoginTask、 不写 cookie（已 grep 核实）。因此 cookie 非空且 status='success' 的行， 只可能是某次真实登录成功留下的。那批 attempt_status='' 不是「从未登录」， 而是「登录成功发生在 attempt_* 字段存在之前」（字段是迁移 20261001_0035 才加的）。

7.4.2 候选筛选

• 每 5 分钟 tick，取满足以下条件的行，最多 batch_size（默认 20）个： ck_check_status = 'invalid' 且 relogin_next_at <= now（或为空） 且 relogin_attempts < max_attempts_per_day（默认 2） 且 auto_managed = true 且 attempt_status 不在途；
• 不再按「有没有成功过」筛：持 CK 的行按定义都成功过，这个条件没有区分度； 真正有区分度的是「上一次为什么失败」（下一步的分型）。

7.4.3 失败分型（本次新增的核心）

重登失败不能笼统地「再试一次」或「丢给人工」。按原因落 login_tasks.relogin_failure_kind （枚举字段，新增迁移；不要靠 attempt_message 做字符串匹配 —— 文案一改就失效， 且页面要按类型筛选），不同分型走不同后续：

kind	触发（线上实测条数）	后续动作
captcha	极验滑块失败（144 / 35%）	转人工队列，不再自动重试（反复撞只会加重风控）
email_code	验证码错误 / 等待超时（144 / 35%）	自动重试（走退避表）；这批多半正是 20261001 修掉的取码 bug 造成的
interrupted	服务重启 / 人工停止（121 / 29%）	不是真失败 → 自动重试
email_quota	「发送次数已达上限」	退避到次日零点 + 随机抖动 ±30 分钟（决策 1：只影响该账号，批次继续）
credential	密码错误 / 账号异常	转人工队列（需核对密码或邮箱）
network	请求失败 / 超时 / 连接异常	自动重试（退避）

64% 的线上「失败」（email_code + interrupted）其实是可自动解决的；不分型就会把它们 一起推给人工，白费 265 个可救名额。

7.4.4 退避与熔断

• 退避：relogin_attempts 1→1h、2→3h、3→12h、4+→24h（写 relogin_next_at）；
• 极验即停：同一账号连续 2 次 captcha → 直接转人工，不再自动重试；
• 系统性故障刹车（与决策 1 不冲突）：代理 API 不可用 / 单轮失败率超阈值（默认 80%） / 单轮异常数超阈值 → 自动暂停作业并告警。这些不是单账号问题，继续跑只会浪费资源。

7.4.5 速率与风控

约束	实测/建议
邮箱配额	13,618 个账号对应 13,618 个独立邮箱（1:1，实测） → 单账号配额满不影响他人，决策 1 成立；也不存在「打爆共享邮箱」的问题
IP 才是瓶颈	1,356 次登录 + 1,356 封验证码，短时间集中做会触发风控 → 走现有代理池 + 限速每小时 30~60 个（约 1~2 天跑完，后台慢慢来完全可以接受）
单轮上限	batch_size 默认 20（5 分钟一轮 = 上限 240/小时，实际由退避与每日上限压住）

7.4.6 页面呈现（对应「失败单独标记提示」）

/automation 页在作业卡片之外增加两块：

• 自动重登中：有退避倒计时、下次重试时间、当前 relogin_attempts；
• 待人工处理：按 relogin_failure_kind 分组 ——
  • 极验失败（要人工过滑块）
  • 凭证问题（要核对密码/邮箱）
  • 多次失败（要人工查账号可用性）

7.4.7 上线方式（三段，同 P1a 的谨慎程度）

1. 小规模实测 ✅ 已完成（2026-10-02），结果远好于预期：

   项	结果
   样本	20 个 invalid，两组各 10：A「还没重试过」/ B「取码 bug 时代失败过」
   成功率	20 / 20 = 100%（历史推断只有 78%）
   耗时	2 分 13 秒（≈ 9 个/分钟）
   极验滑块	0 次
   邮箱取码	全部正常 → 20261001 的取码修复在生产验证通过（B 组全过，证实那 144 个「验证码失败」就是旧 bug 造成的）
   CK 替换	20 个全部换成新 CK；ck_check_status 由登录流程自动改回 valid（login_service.py 成功分支）

   结论：会话确实只是过期，重登几乎必定成功；可救量从估的 1,050 上调到 ≈1,350（1,356 × 近 100%）。失败分型仍然要做，但属少数路径（极验/配额/凭证）。 实测 9 个/分钟且零极验，说明斗鱼当前风控容忍度比预想高，不过全量仍建议限速 （先按每小时 100~200 个开，观察极验率再决定是否加速）；

2. 限量开作业：按实测成功率定 batch_size 与日上限，先只跑一个分组；

3. 全量：观察若干轮，确认分型与退避符合预期后再放开。

7.5 并发与互斥

• 同一账号不允许人工与自动同时操作：依据 attempt_status 在途 + 现有 cookie_relogin_registry；
• 作业级：进程内 threading.Lock 保证同一作业不会重叠执行；
• 批次级：ck_relogin 一轮只起一个 LoginBatchRunner，与人工批次并存但目标账号互不重叠。

7.6 接口与权限

方法	路径	说明
GET	/api/automation/jobs	列出作业与配置、最近一次结果
PATCH	/api/automation/jobs/{key}	改开关 / 间隔 / 批量大小 / 并发
POST	/api/automation/jobs/{key}/run	立即跑一轮（手动触发）
GET	/api/automation/runs	运行历史（分页、按作业过滤）

权限点：automation:view（运营/超管）、automation:manage（仅超管，见 §11.1）。

7.7 前端

新页 /automation：作业卡片（开关 / 间隔 / 上次与下次运行 / 最近结果统计）、运行历史表格、手动「立即跑一次」。 Dashboard 增加一张「自动化」卡片（今日巡检数、无效数、自愈成功数、待重登数）。

7.8 验收标准

P1a

1. 人为让一批账号 CK 失效 → 一个巡检周期内被检出并标记 ck_check_status='invalid'；
2. 巡检过程中没有任何 CK 被改动（可对比巡检前后的 login_tasks 行）；
3. 关闭作业开关后立即停止调度；
4. /automation 能看到每一轮的明细（扫描数 / 有效 / 无效 / 跳过）。

P1b

5. 开启自愈后，失效账号按退避表排队重登，不会每轮都撞同一个账号；
6. 命中邮箱配额上限时，只有该账号被跳过并退避到次日，其余账号正常完成；
7. 连续失败率超阈值时作业自动暂停并留下 automation_runs 记录。

7.9 顺带修

给 POST /api/login/batch 补审计记录（对齐 cookie:relogin 等已有动作），否则自动化与人工的登录来源无法追溯。

8. P2 · 资料收集链接

8.1 目标

客服把一条链接发给用户，用户填订单号 + 游戏编号 + 游戏昵称 + 主页截图，信息直接进系统；皮肤由订单号自动对应（决策 8）。

8.2 数据模型（迁移 1 个）

collect_links：id / token(唯一，32 字节随机 base64url) / account_id(可空) / created_by / title / expires_at / max_submissions(默认 1) / submissions_count / status(open/closed/expired) / created_at / closed_at

collect_submissions：id / link_id / account_id / order_no(归一化后) / order_snapshot(JSON，来自 §6) / fields(JSON：游戏编号 / 游戏昵称) / screenshots(JSON：主页截图路径数组) / remark / status(pending/processing/done/rejected) / handled_by / handled_at / ip / user_agent / created_at

用户只填这三样。唯一命中的订单皮肤由订单号自动带出，提交记录只存订单快照。 用户"选一件"的结果不放在这里，而是放在工单的 exchange_orders.chosen_commodity_id 上（见 §10.3/§10.4）—— 提交记录是用户视角的原始凭证，不该被后续业务流程改写。

截图存储：阿里云 OSS（不落本地磁盘），DB 只存 object_key；读取走后端鉴权代理。详见 §8.3。

8.3 图片存储：OSS（不落本地磁盘）

服务器磁盘有限，用户上传的图片一律进 OSS，本地只做内存处理（Pillow 从 bytes 读，不写临时文件）。

参考 order_site 的成熟做法（实测）：

环节	order_site 的做法	我们照做
桶	阿里云 OSS order-site-assets（私有，region oss-cn-hangzhou）	live-hub-assets —— ✅ 已建好（私有 ACL + 版本控制已开，内网端点，实测 put/get/list/delete 全通）
端点	上传走内网 oss-cn-hangzhou-internal.aliyuncs.com	同（实测容器可达：100.118.28.52，无公网流量费）
存什么	DB 只存 object_key，不存 URL	同（换域名/换桶不用改数据）
怎么读	自己的后端代理 /api/v1/files/object?key=...，带 ETag / Last-Modified / 304	GET /api/collect/submissions/{id}/screenshots/{idx}，鉴权 + 流式返回 + 304
变体	sharp 生成 thumb(480) / medium(1280)	Pillow 生成缩略图（列表页用），原图保留

落地要点

1. 桶权限：私有（不开公共读）—— ✅ 已实测：公共 URL 直取返回 403。既然读走后端代理，就不需要公网端点、公开 ACL 或签名 URL，攻击面最小；
   • 凭据已就位：独立 RAM 子账号 live-hub-oss + 策略 live-hub-assets-rw，实测跨桶访问被拒（最小授权）；
   • 实现注意：object_storage.py 只用 PutObject / GetObject / DeleteObject / ListObjectsV2，不要用 HeadBucket（该策略下返回 403），健康检查改用 ListObjects 或 Put/Get 往返；
2. object key 规范：collect/<yyyyMM>/<uuid>.<ext>，缩略图 collect/<yyyyMM>/<uuid>_thumb.<ext>；
3. 上传前处理：校验 magic bytes → 限制 ≤5MB / ≤3 张 → Pillow 重新编码（剥 EXIF、防伪装）→ 生成缩略图 → 两张都传 OSS；
4. 鉴权读取：读图接口挂登录依赖 + 数据范围过滤（决策 7：归属客服 + 运营/超管），不允许无鉴权直读；
5. 凭据：建议新建 RAM 子账号，只授权这一个桶的 PutObject / GetObject / DeleteObject，不复用 order_site 的 AK；
6. 不落地：UploadFile 读进内存即可，不写 ./data，容器磁盘只用于日志；
7. 清理：给桶配生命周期规则（如转低频/过期删除）由运维侧决定；本轮不做应用层删除。

Python 侧用官方 oss2（需新增依赖，当前环境未安装）；不用 boto3，省掉 S3 兼容层的坑。

8.4 订单号处理（决策 5 + P0 整合）

1. 归一化：去掉首尾空白 + 去掉所有空白字符（含全角空格 \u3000）→ 非空校验；
2. 查单：走 P0 适配层拿 sku_code / sku_name / order_status / route，写入 external_order_cache 与提交记录的快照（准入规则见 §6.4）；
3. 唯一性：order_no 全库唯一（重复直接拒绝并提示「该订单号已提交过」）。不做格式校验。

假设：不同平台订单号不会撞号。若将来会撞，改为 (order_no + platform) 组合唯一。

8.5 接口

公开（无鉴权，独立前缀 /api/public/collect）

方法	路径	说明
GET	/api/public/collect/{token}	链接状态、资料模板字段、已提交时的处理状态
POST	/api/public/collect/{token}	multipart 提交（订单号 + 游戏编号 + 游戏昵称 + 主页截图）

为什么单独开 /api/public/ 前缀：① 若公开接口用 /api/collect/{token}，会把同级的 /api/collect/links 当成 token="links" 吞掉（FastAPI 按声明顺序匹配参数化路由）；② 无鉴权边界写在 URL 上，一眼能审出哪些路由不该挂登录依赖。

内部（需登录，前缀 /api/collect）

POST /api/collect/links（生成）、GET /api/collect/links、POST /api/collect/links/{id}/close、GET /api/collect/submissions（按范围过滤）、GET /api/collect/submissions/{id}/screenshots/{idx}（鉴权读图，见 §8.3）、POST /api/collect/submissions/{id}/accept|reject

现有代码没有全局鉴权中间件，鉴权是逐路由 Depends(get_current_user) —— 所以公开路由只要不挂依赖即可；新路由记得在 web/backend/main.py 里 include_router。

8.6 防护（公开入口必须做）

• token 32 字节随机、有效期默认 7 天、提交次数上限；
• 每 IP 限流（内存令牌桶，默认 10 次/分钟）；
• 文件：仅 png/jpg/webp、单张 ≤ 5MB、最多 3 张、校验 magic bytes，并用 Pillow 重新编码（剥离 EXIF、防伪装文件），随后直传 OSS（§8.3，不落本地盘）；
• 公开接口只回显最少信息（不暴露账号密码、CK、内部备注）；截图读取一律走后端鉴权接口，不给 OSS 公共读。

8.7 前端

• 公开页 /collect/:token：
  • P2 阶段：订单号 → 显示订单商品名（来自订单快照，仅作核对，不做皮肤匹配——那时还没有别名表）→ 游戏编号 → 游戏昵称 → 主页截图 → 提交。
  • P4 阶段：在 P2 基础上增加皮肤匹配显示 —— 唯一命中时展示「你买的是：套装-暗影哥特」让用户确认；skin_choice（多选）时展示候选列表让用户选一件（§10.4）。 已提交过则显示状态（决策 3：不做复杂回执，但兑换成功后用户打开同一链接能看到「已兑换 XX 皮肤 + 时间」）。 链接在 status=open 期间可反复打开（查看状态不算一次提交，不消耗 max_submissions）—— 用户没保存链接时，客服转发原链接即可；这是"用户能回来看到结果"的实现前提； 该路由必须放在 App.tsx 登录判断之外，SPA fallback 已支持；
• 内部页：/collect-links（链接管理：生成 / 复制 / 关闭）、/collect-submissions（待处理队列 + 大图查看 + 受理 / 驳回）。

权限点：collect:link、collect:handle；可见范围按决策 7。

8.8 验收标准

1. 手机打开链接能完成填写与上传，提交后客服端队列立即出现；
2. 同一订单号二次提交被拒绝；
3. 超过有效期 / 超过提交次数 / 非图片文件 / 超大文件都被正确拒绝；
4. 上传的图片只存在于 OSS，容器与宿主机磁盘上找不到任何副本（可 find 验证）；
5. 未登录访问读图接口返回 401/403；客服只能看到自己范围内账号的截图；
6. OSS 不可用时提交给出明确失败提示，不产生"半条记录"；
7. 兑换成功后，用户用原链接能看到结果。

9. P3 · 账号皮肤台账

9.1 目标

知道「哪个账号、什么时间、兑换了什么皮肤」，并在兑换前拦住「365 天内重复兑换同一件皮肤」。

9.2 数据模型（迁移 1 个）

别名归一（本阶段的核心）：以斗鱼商品为锚点

表	字段	说明
skin_catalog	commodity_id(PK，斗鱼商品 ID) / manual_id / name / points / category(suit/helmet/bag/weapon/pack/other/non_skin) / active / updated_at	斗鱼商品目录是主表。365 天规则的判定键就是它
skin_aliases	(source, raw_key) 联合 PK / commodity_id(索引) / confidence / updated_at；source ∈ {kuaishou_rel_sku_id, kuaishou_rel_item_id, kuaishou_sku_nick, manual}	快手 SKU / item / 规格名 → 斗鱼商品（优先 SKU 精确，名称只兜底，见 §3.6）
skin_keywords	keyword(PK) / commodity_id(索引) / updated_at	归一层用的核心词（当前 30 个），用于在「小店自选 / 3选1 / 堆词标题」里识别候选商品

依据 §3.3 实测：sku_code（数字型，易变）、sku_name（中文，有 套装- 前后缀变体）、语义化 code（suit_*）都只是别名，必须归一到 skin_key 才能正确判「同一件」。 规模（已跑完分析，见 皮肤准入映射分析）：不是梳理 923 或 615 个快手标准名，而是维护 60 个斗鱼商品 ← 76 个快手商品名的映射 —— 工作量从「数百条」降到「几十条」，人工过一遍即可。 其中 62 个快手名唯一命中（订单可自动定皮肤）、14 个命中多个（需用户选）。

与 douyu_goods_snapshot 的关系（同步策略）

项	约定
同步方向	douyu_goods_snapshot → skin_catalog（单向；snapshot 是抓取结果，catalog 是我们的可用目录）
存多少	全部 78 行都进 catalog（非皮肤 18 个标 category=non_skin、active=false）；准入只看 active=true 的
何时同步	新增同步作业挂到 P1 的调度器上（sku_catalog_sync，默认每天一次），不引入新机制；也可在 /skins 页手动触发
冲突处理	commodity_id 已存在 → 只更新 name/points；不覆盖人工维护的 category/active；snapshot 里消失的商品 → 标 active=false，不物理删除（历史台账要能查到）

account_exchange_records（台账）：id / account_id(索引) / skin_key(索引) / goods_name / exchange_time / source(our_task / douyu_api / manual / order) / order_no(订单号, 可空) / sku_code / sku_name(订单快照) / task_id(可空) / role_name / remark / raw(JSON) / created_at 唯一键：(account_id, order_no)（有订单号时）防重复导入。

9.3 四路数据源

1. 我方兑换任务成功时自动落账（最准，带账号/时间/商品/任务/角色）；斗鱼商品先经 skin_douyu_items 映射到 skin_key；
2. 斗鱼侧 exchange_records 回填（复用 query_exchange_records，解析 goods_name / buy_time / serial 后 upsert）；
3. 订单驱动落账（P4 工单执行成功时，直接用订单快照里的 sku_code/sku_name 归一后落账）；
4. 人工补录（带截图，用于查不到的历史）。

9.4 规则引擎

can_exchange(account_id, skin_key, within_days=365)：

• 取该账号该 skin_key 最近一条 exchange_time；
• 若 now - exchange_time < 365 天 → 阻止，并给出「上次兑换 2026-03-01，2027-03-01 后可再兑」；
• 超管可用 force_reason 强制通过（决策 6），写审计。

归一流程（订单号进来的皮肤）： sku_code / sku_name → 查 skin_aliases → 命中则用 skin_key；未命中则挂起待人工归类（工单进 rule_unmatched，见 §10.4；不静默放行，避免 365 天规则被绕过）。

接入点：

• 兑换前：工作台里选中账号 + 商品时校验并提示（前端禁止 + 后端接口二次校验）；
• 兑换后：任务成功即写台账；
• 工单受理时：用订单快照里的 skin_key 再校验一次。

9.5 前端

新页 /skins：

• 皮肤视角：某皮肤被哪些账号兑换过、最近一笔时间、还剩多久可再兑；
• 账号视角：某账号的兑换时间线（含截图）；
• 检索与导出；skin:manage 可维护别名映射。

权限点：skin:view、skin:manage。

10. P4 · 皮肤兑换工单（模板 + 匹配 + 状态机）

设计思路整体对齐 order_site 接单平台：同样是「订单进来 → 按规则模板匹配 → 命中才建单 → 用户补资料 → 执行 → 归档」，只是把「打手抢单」换成「客服执行」。

10.0 参考对象：接单平台的六层机制

层	组件	关键设计
① 规则/模板	work_categories、work_product_rules、work_product_rule_mappings	规则带 enabled / auto_create / 来源约束 / requirement_json.fields（资料模板） / 报酬 / 超时策略 / 验收模式；映射分 product_default / sku_exact / sku_series 三种粒度
② 匹配	resolveMatchingProductRuleDecision()	打分 → 排序 → 只有唯一最高分才算命中；并列判 ambiguous 绝不猜；匹配上下文取自订单快照；结果与候选写 work_product_match_logs
③ 建单	syncWorkerOrdersForSourceOrder()	未命中 → 只写日志不建单；命中但 auto_create=false → 跳过；校验订单号跨订单唯一（防撞号）；初始状态由模板决定：有必填 → pending_material，无必填 → unassigned；material_json 存来源订单快照；requirement_json 存模板快照
④ 状态机	WORK_ORDER_STATUS	pending_material → unassigned/open → in_progress → pending_acceptance → accepted；旁路 problem/cancelled；配 deadline_at + timeout_policy；acceptance_mode 分 standard/friend_gift
⑤ 补资料	/api/collect/lookup · submit · upload	凭订单号找 pending_material 工单；提交写 material_json.collect = {fields, screenshots, submittedAt, complete}；状态回落：complete ? 下一态 : pending_material
⑥ 事件与实时	work_order_events + realtime + 通知	每次状态变更写 from_status → to_status + payload；实时推送；建单时给管理端发通知

模板的两种编辑方式（直接抄）：

// 结构化
"requirement_json": { "fields": [
  { "key": "gameId", "label": "游戏编号", "required": true, "type": "text",   "options": [] },
  { "key": "system", "label": "系统",     "required": true, "type": "select", "options": ["安卓","苹果"] }
]}

# 文本（一行一个字段：key：label#选项1,选项2）
gameId：游戏编号
system：系统#安卓,苹果

我们的模板固定三个字段（决策 8）：

game_id：游戏编号
game_nickname：游戏昵称
homepage：主页截图#image

比接单平台多一个 image 字段类型 —— 他们的类型只有 text/select，截图是单独一个 screenshots 数组；我们把图片也做成模板字段，这样「必填校验」统一走一套逻辑，不用给截图开特例。

10.1 规则/模板层（新增 2 张表）

exchange_skin_rules（业务配置，一个斗鱼商品一条规则）

字段	说明
id / rule_key(唯一)
commodity_id(唯一, 索引)	指向 skin_catalog.commodity_id —— 规则直接挂在斗鱼商品上
enabled / auto_create	是否参与准入 / 命中后是否自动建单
required_points	预计消耗积分（用于前置校验）
cooldown_days	冷却天数，默认 365
requirement_json	资料模板（默认 游戏编号 / 游戏昵称 / 主页截图，三项均必填）
sort_order / remark / created_at / updated_at

没有单独的映射表 —— 原先打算照抄接单平台的 exchange_skin_rule_mappings，但它与 §9.2 的 skin_aliases 职责重叠（两条链路都能把订单映射到同一个斗鱼商品），实现时会反复纠结「这条映射该写哪张表」。 接单平台要 rule + mapping 两层，是因为它要在多个店铺/多个接单模板之间路由；我们只有一个数据源（快手），不需要。

最终分工：商品身份识别统一交给 skin_aliases / skin_keywords（§9.2），规则表只挂业务配置 —— 一张表一件事。 连带好处：rule_ambiguous 状态也不需要了（skin_aliases 主键 (source, raw_key) 天然一对一，不会出现多条规则并列），候选复数只剩「小店自选」一类，走 skin_choice。

exchange_match_logs（匹配诊断）：order_no / rel_sku_id / sku_nick / item_title / match_status(matched / multi_match / unmatched) / commodity_id / candidates(JSON) / created_at

10.2 匹配层

resolve_skin(order_snapshot) -> { commodity_ids: list[str], reason: matched|multi_match|unmatched, source: alias|keyword, rule | None }

• 输入：订单快照的 (sellerId, relItemId, relSkuId, skuNick, itemTitle)（直接来自 spec_json，§3.6）；
• 第一步：解析候选商品（skin_aliases / skin_keywords）—— 匹配顺序从精确到宽泛：rel_sku_id 精确 → sku_nick 精确 → sku_nick 系列前缀 → rel_item_id → item_title 包含；
• 第二步：取业务配置（按命中的 commodity_id 取 exchange_skin_rules：模板、积分、冷却、启用状态）—— 分工见 §10.1；
• 候选 1 个且规则 enabled → matched（皮肤由订单自动确定）；
• 候选多个 → multi_match（「3选1 / 小店自选」类）：工单进 skin_choice，让用户在链接里选一件（决策 8 例外，占 12.4%）；
• 候选 0 个，或规则 enabled=false → unmatched（斗鱼兑不了 / 我们不接，占 59.9%）→ 拒绝、不建单；
• 没有 ambiguous：skin_aliases 主键 (source, raw_key) 天然一对一，不存在多条并列（§10.1）；
• 匹配结果每次都要落日志（命中 / 多选 / 未命中都写），这是排障的唯一依据。

10.3 工单模型（新增 2 张表）

exchange_orders（工单）

字段	说明
order_no(唯一) / order_snapshot(JSON)	来源订单 + 快照
chosen_commodity_id(可空)	最终选定的斗鱼商品 —— 多选类由用户在链接里选、或客服代选（决策 8 例外的落点）
submission_id(可空, 索引)	来源的 collect_submissions.id —— P2 与 P4 的衔接点（见 §10.5）
sku_code / sku_name / skin_key	皮肤标识（skin_key 可空，未归类时为空）
rule_id / requirement_json	命中的规则（按 commodity_id 取）+ 模板快照（模板后续改动不影响历史工单）
account_id / assignee_id	执行账号（客服选）+ 归属客服
status	见 §10.4
material_json	用户提交内容 + 截图路径 + 提交时间（对齐接单平台 material_json.collect）
eligibility_check(JSON)	前置校验结果：CK 状态 / 365 天规则 / 角色绑定 / 积分
task_batch_id / result(JSON)	关联的斗鱼任务批次与执行结果
force_reason	超管强制兑换原因
deadline_at / finished_at / created_at / updated_at

exchange_order_events（事件流水）：order_id / actor_type(collect / support / system) / actor_id / event_type / from_status / to_status / payload(JSON) / created_at

10.4 状态机

工单的创建时机：① 用户通过链接提交后自动建单（主路径）；② 客服手动建单（不走链接的特殊情况）。 「客服生成链接」本身不建工单 —— 链接是 collect_links，用户没提交时没有工单行，所以状态机里没有 draft。

pending_material（待用户补资料）        ← 模板有必填字段时的默认入口
  → pending_match（订单已提交，待匹配皮肤）
      ├─ rule_unmatched（皮肤映射不到斗鱼商品）→ 人工归类或拒绝 → 回 pending_match
      ├─ rule_unmatched（映射不到斗鱼商品 / 规则未启用）→ 人工归类或拒绝 → 回 pending_match
      └─ skin_choice（命中多个斗鱼商品，等选一件）→ 选定 chosen_commodity_id → 回 pending_match
  → ck_repairing（账号 CK 无效 → 等重登；**P1b 已启用则自动重登，未启用则等人工点重登**）
  → ineligible（前置校验不过：365 天规则命中 / 积分不足 / 角色未绑定）
        └─ 超管 force_reason 强制 → 回 ready；否则取消
  → ready（前置校验全过，可执行）
  → running（兑换执行中，关联斗鱼任务批次）
  → done（已完成，已写台账）
  旁路：problem（执行异常待处置）/ cancelled（取消）

ineligible 与 ck_repairing 的区别：ck_repairing 是能自动修复的（等 CK 重登好），ineligible 是需要人决策的（365 天命中就摆在那儿，只能超管强制或放弃）。两者都不能直接进 running。

补充规则（对齐接单平台）：

• 初始状态由模板决定：模板有必填 → pending_material；全可选 → 直接进 pending_match；
• 状态回落：用户补资料不完整（缺必填）时状态退回 pending_material，并写事件；
• 超时：deadline_at + timeout_policy，我们只需要 reopen（回 ready）和 cancel 两种；
• 不做接单平台的 open（抢单）/ unassigned（派单池）/ pending_acceptance 复杂分支 —— 我们是一对一客服，「执行完成即 done」，异常统一进 problem；
• skin_choice 怎么选（决策 8 例外的落地方式）：工单进 skin_choice 后，客服把（同一个）链接再发给用户 —— 链接在 status=open 期间可反复打开，此时公开页展示候选列表让用户选一件；用户不方便时客服可在工单页代选。两种情况都写 chosen_commodity_id 并写事件。

10.5 补资料流程（对齐 /api/public/collect/*）

步骤	行为
用户打开链接	已有 order_no 时直接查；没有则输入订单号
查订单	P0 适配层 lookup_order() → route 判定；route ≠ unhandled 直接拒绝（§6.4）
匹配规则	resolve_skin_rule() → 命中则带出皮肤与资料模板；未命中 / 歧义 → 进对应待处理状态
渲染表单	按 requirement_json.fields 动态渲染：text→输入框、image→上传（预览 + 删除，单张 ≤5MB，Pillow 重编码）
提交	校验必填（image 字段看路径数组非空）→ 写 material_json.collect = {fields, screenshots, submitted_at, complete} → 状态流转 + 写事件；不完整则退回 pending_material
存图	直传 OSS（collect/<yyyyMM>/<uuid>.<ext>，§8.3），DB 只存 object_key；不落本地磁盘
多件商品	我们 1 单 = 1 件商品（实测 271,024 单 1:1），不需要接单平台「多件要求指定 workOrderId」的分支

10.6 前端页面（对齐接单平台三处界面）

页面	参考实现	内容
/exchange-rules	ProductRulesPanel.tsx	规则列表 + 模板编辑（支持文本一行一字段）+ 启用 / 自动建单开关 + 斗鱼商品绑定
/exchange-orders	WorkOrdersPanel.tsx	状态筛选、资料查看（含大图）、一键执行、备注、强制兑换（超管 + 原因）
/collect/:token	CollectPage.tsx	动态字段表单 + 截图上传 + 提交后状态展示（与 §8.7 同一页面）

权限点：exchange:view（查看）、exchange:manage（改规则 / 执行工单 / 强制兑换，见 §11.1）。

10.7 与接单平台的差异（不照搬的部分）

接单平台有	我们	原因
抢单大厅 / 分享 / 多打手 / 派单池	❌	一对一客服执行
报酬、保证金、钱包、提现、等级、VIP	❌	不涉及众包结算
验收草稿、申诉、售后、超时扣款	❌（简化）	只保留 problem + 客服处置
friend_gift 好友赠送冷却（默认 72h）	❌ 不涉及（决策 9）	我们的兑换不需要加好友等待
资料是给打手看的	✅ 换成	资料是给客服操作游戏账号用（游戏编号 / 游戏昵称 / 主页截图）
——	➕ CK 健康检查（P1）	接单平台没有账号池概念
——	➕ 365 天规则（P3）	接单平台没有跨订单冷却
——	➕ 斗鱼商品映射与积分校验	接单平台直接对接发货平台 API

10.8 端到端流程

客服选账号 → 生成收集链接 → 发给用户
      ↓
用户填订单号 → P0 适配层查 order_site（route 判定：是否「没人管」）→ 匹配规则（皮肤做不做）
      ↓
按规则模板渲染表单 → 用户补游戏编号 / 游戏昵称 / 主页截图 → 提交（写 material_json）
      ↓
系统自动前置校验（后台作业）：
  ① skin_key 归一（归不到 → rule_unmatched，人工处理，不静默放行）
  ② CK 是否有效 → 无效则挂 P1 自动重登，工单停在 ck_repairing
  ③ 皮肤 365 天规则（P3）→ 命中则标记「不可兑换」并提示上次兑换时间
  ④ 角色绑定 / 积分是否足够（复用现有 query 任务）
  汇总写 eligibility_check
      ↓
工单变 ready → 客服一键「执行」→ 现有任务链（绑定 → 开通 → 兑换）
      ↓
二维码 / 结果回填工单 → 成功自动写台账（P3）→ 用户用原链接看到结果

10.9 验收标准

1. 从「发链接」到「兑换完成」全程无需手工录数据；
2. 用户填的订单号能自动带出商品/皮肤并留快照；
3. 映射不到斗鱼商品（unmatched）时不建单；候选多个（multi_match）时必须先选定 chosen_commodity_id 才能继续；匹配日志能看出命中了哪些候选；
4. 用户资料不完整时状态退回 pending_material，补齐后继续；
5. CK 失效时工单自动进入 ck_repairing，修复后自动转 ready；
6. 命中 365 天规则的工单不能直接执行，超管可强制并留原因；
7. 每个状态变更都有 exchange_order_events 记录；
8. 完成后台账、用户链接、工单三处状态一致。

11. 横切关注点

11.1 权限点与默认角色

新增权限点，并给出建议的角色默认分配（沿用 web/backend/permissions.py 的 ROLE_PERMISSIONS 机制）：

权限点	说明	super_admin	operation	support
automation:view	查看自动化作业与运行历史	✅	✅	❌
automation:manage	改配置 / 手动触发作业	✅	❌	❌
collect:link	生成收集链接	✅	✅	✅
collect:handle	受理 / 驳回提交	✅	✅	✅（仅自己账号，见下）
skin:view	查看台账	✅	✅	✅（仅自己账号）
skin:manage	维护皮肤别名与目录	✅	✅	❌
exchange:view	查看兑换规则与工单	✅	✅	✅（仅自己账号相关）
exchange:manage	维护兑换规则、执行工单、强制兑换	✅	✅	❌

数据范围靠过滤而不是权限点：客服只能看到「分配给自己的账号」相关的提交与台账，实现方式与现有 account:view_assigned / cookie:operate 一致（查询时按 accounts.assigned_to 过滤）。

11.2 审计

动作	落点
自动化每轮执行	automation_runs
自动重登单个账号	audit_logs（action=cookie:auto_relogin）
人工发起登录批次	audit_logs（P1 顺带补，action=login:batch）
生成收集链接 / 用户提交 / 客服受理	audit_logs + collect_submissions 状态
365 天规则强制兑换	audit_logs（含 force_reason、操作人）
C 桶订单人工放行	audit_logs（决策 10 要求的留痕）

11.3 配置项清单

配置	阶段	默认	说明
ORDER_SITE_DATABASE_URL	P0	—	✅ 已写入生产 .env（角色 livehub_ro），不入仓库
ORDER_SITE_LOOKUP_ENABLED	P0	false	总开关；关掉即退回手工流程（✅ 已写入生产 .env，当前为 false）
ORDER_SITE_LOOKUP_TIMEOUT_SECONDS	P0	3	只读查询 statement_timeout（✅ 已写入；DB 侧角色也已设 3s，双保险）
AUTOMATION_ENABLED	P1	false	调度器总开关
COLLECT_LINK_TTL_DAYS	P2	7	收集链接有效期
COLLECT_UPLOAD_MAX_MB	P2	5	单张截图上限
COLLECT_UPLOAD_MAX_FILES	P2	3	单次提交截图张数
COLLECT_RATE_LIMIT_PER_MIN	P2	10	公开接口每 IP 限流
OSS_ENDPOINT	P2	内网端点	https://oss-cn-hangzhou-internal.aliyuncs.com（上传走内网，无流量费）
OSS_BUCKET	P2	—	✅ live-hub-assets（已建：私有 + 版本控制），已写入生产 .env
OSS_ACCESS_KEY_ID / OSS_ACCESS_KEY_SECRET	P2	—	✅ RAM 子账号 live-hub-oss，只授权该桶；已写入生产 .env
OSS_PREFIX	P2	collect	object key 前缀

作业级参数（interval_seconds / batch_size / concurrency / 退避表 / 失败率阈值）走 automation_jobs.config，在 /automation 页面改，不写死在环境变量里。

11.4 数据保留与清理

数据	建议策略
automation_runs	保留 90 天，超期清理（待确认）
exchange_match_logs	保留 180 天
external_order_cache	每条 24 小时后视为过期（过期重查，不主动删）
collect_links 过期记录	保留 90 天
用户上传截图（OSS）	不自动删（属业务凭证）；生命周期与版本控制由 OSS 侧规则管理

11.5 备份

目前只备份数据库。截图改为 OSS 后（§8.3），不再需要本地备份 —— 图片的持久性与版本控制由 OSS 承担：

• 建议给 live-hub-assets 开启版本控制并用生命周期规则管理（转低频/过期清理由运维定）；
• DB 依旧只备份数据库，但要注意 DB 里的 object_key 与 OSS 对象是配套的，误删 OSS 对象会导致台账"有记录、没图"。

11.6 用户可见文案（统一）

场景	文案
订单号为空	请填写订单号
订单号重复提交	该订单号已提交过，请勿重复提交
订单不存在	订单号不存在，请核对后重试
已由发货平台处理（auto_fulfilled）	该订单已由发货平台处理，无需在此提交
走接单平台（worker_platform）	该订单由接单平台处理，无需在此提交
无人管但皮肤未命中（unhandled + 规则未命中）	该订单暂不支持，请联系客服
皮肤待归类（内部）	该商品未归类，请先在「兑换规则」里补充映射
365 天规则命中	该账号已于 2026-03-01 兑换过该皮肤，2027-03-01 后可再兑
资料不完整	还有必填项未填写，请补全后提交

11.7 测试计划

• 每个阶段补 pytest，沿用现有基线（当前 235 条通过）；
• 只读与纯函数优先：匹配打分、别名归一、365 天判定、订单号归一、模板必填校验都做成纯函数，重点覆盖；
• 写操作不纳入自动回归：兑换、重登、支付类不跑真实请求，用 mock 客户端做契约测试（沿用 tests/test_douyu_write_path_contracts.py 的写法）；
• 迁移脚本要走现有 tests/test_migrations.py 的链完整性 + SQLite 整链执行；
• 前端沿用 tsc -b + npm run build 门禁。

11.8 安全

• 公开接口最小回显 + 限流 + 图片重编码（见 §8.6 防护）；
• 内部接口沿用现有鉴权与数据范围；新增接口一律挂 Depends(get_current_user) 或具体权限；
• order_site 只读账号权限最小化，只授 4 张表的 SELECT；
• 截图存私有 OSS 桶，只通过鉴权接口读取（不放进 dist，不给公共读、不发签名 URL）；
• OSS 凭据走 .env，建议独立的 RAM 子账号 + 最小授权；不在日志里打印 AK/SK。

12. 里程碑与依赖

阶段	内容	依赖	粗估
P1a	CK 巡检自动化（调度器骨架 + ck_health 只检测/只标记 + /automation 页 + 登录批次审计）不改动任何 CK	无	2 人日
P0	订单读取适配层（只读 PG 账号 + external_order_source.py + external_order_cache）	运维建只读账号	1~1.5 人日
P2	资料收集链接（公开页 + OSS 图片直传 + 后端代理读图 + 队列 + 订单回显）	P0（订单回显）+ 运维建 OSS 桶；P0 未完成时先留手工填订单号	5~6 人日
P3	皮肤台账（skin_catalog 以斗鱼商品为锚 + skin_aliases 映射 + 四路来源 + 365 天规则 + /skins 页）	P0（订单皮肤）；映射分析已完成（见分析文档），人工只需过 60 个商品 / 76 条别名	4~5 人日
P4	皮肤兑换工单（规则/模板 + 匹配层 + 工单/事件表 + 状态机 + 三处界面 + 前置校验作业）	P1a + P2 + P3（不依赖 P1b：CK 失效时先标记等人工重登，P1b 上线后自动接管）	6~8 人日
P1b	CK 自愈（ck_relogin 自动重登：失败分型 + 退避 + 熔断 + 开关，默认关闭）	P1a（检测已验证，不必再等观察期）	2.5~3 人日

建议顺序：P1a → P1b → P0 → P2 → P3 → P4。

• P1a 已上线（2026-10-02），只做「帮你把失效 CK 找出来」，零风险；
• P1b 已上线（2026-10-02）：20 个失效账号实测 20/20 重登成功、零极验；当前 30 条/轮、约 97% 成功率，待重登积压约 3.6k 正在消化；
• P0 已过半（2026-10-02）：适配层 + 迁移 0039 已完成并真机验证（三桶判定全对、3.3ms、540 个重复订单号正确拦下）。 psycopg 与迁移 0039 已随 2026-10-03 的部署上线（external_order_cache 表已在生产建好）。 仍缺接口与页面，且 ORDER_SITE_LOOKUP_ENABLED=false —— 运营还查不了订单； 接口/页面按 §6.4 的调用点（用户填订单号时）随 P2 一起上；
• P1b 提到 P1a 之后：原计划等一到两周观察期，但线上数据已把三个前提验证完了 —— 检测结果与人工/直连逐条一致、误判路径已封（三类判定 + 自动暂停）、失效性质查清（会话过期而非凭证问题）。不联动的话，巡检每天翻出失效清单却没人兑现修复，1,356 个账号只会越积越多；
• P0 随时可做：只动本系统，order_site 侧代码改动量为 0；
• P1b 开关仍默认关闭，按 §7.4.7 三段上线：小规模实测 → 限量开 → 全量；
• P1a 上线按三段走： ① 打开 AUTOMATION_ENABLED=true 并重启（此时作业开关仍关着，调度线程空转，不会有任何检测）； ② 在 /automation 页点「立即跑一次」并先把「每轮条数」设 50 —— 手动触发不受开关限制，正好用来观察斗鱼风控与失败率； ③ 确认无异常后把「每轮条数」调 200 并打开「启用」，调度器接管（5 分钟一轮，约 5.4 小时覆盖全库一遍），观察一到两周确认检测结果与人工判断一致。

依赖关系：

P1a ──> P1b                      （观察一到两周后再开，开关默认关闭）
  │
  └──────────────┐
                 ├──> P4          （只依赖 P1a 的「检测出失效」；P1b 上线后自动接管重登）
P0 ──┬──> P2 ────┤
     └──> P3 ────┘

13. 风险与回退

风险	影响	缓解	回退方式
只读查 order_site 打慢对方生产库	影响自动发货	statement_timeout=3s、单行索引查询、2 条连接、本地缓存	关 ORDER_SITE_LOOKUP_ENABLED
order_site 改表结构	适配层报错	只读 4 列且 88 个迁移零变更；SQL 集中在一个文件	同上（降级为手工）
巡检把「查不到」当成「失效」	接口抖动/被风控时批量误标失效，客服误判	已做三类判定：只有斗鱼明确回「未登录」才写 invalid，其余只记 error、保留原结论；error 占比 > 30% 自动暂停作业	恢复接口后重新打开作业开关
巡检本身触发斗鱼风控	检测接口被限流/封禁，误判大面积 invalid	巡检走只读接口且不并发过高；失败率超阈值自动暂停；必要时给请求加随机抖动、降 concurrency	关 ck_health 作业（回到人工检测）
冷启动一次性全量扫	短时高并发被风控	首轮小批量（50）观察后再放量	调小 batch_size
自动重登烧掉邮箱配额	该账号当天无法登录	单账号退避到次日 + 每日上限 + 失败率熔断	关 ck_relogin 作业
自动重登与人工操作撞车	状态互相覆盖	attempt_status 在途判断 + 作业锁	关作业
公开收集页被刷	垃圾数据 / 磁盘占用	token + 有效期 + 次数上限 + IP 限流 + 图片重编码 + 大小限制	关闭链接 / 全局停用公开接口
皮肤别名归类错误	365 天规则误判	未命中一律挂起待人工，不静默放行；强制兑换留审计	/skins 页面修正别名
OSS 桶/对象被误删	台账有记录、图片丢失	桶开版本控制 + 生命周期；DB 只存 object_key 便于核对	从 OSS 版本历史恢复
OSS 不可用	用户传不了图	提交失败给明确提示，不产生半条记录；重试	临时降级：先收文字资料，客服后补图
规则配置错误导致误拒绝	用户无法提交	匹配日志 + 人工放行通道	修正规则 / 人工放行

14. 明确不做（避免范围膨胀）

• 不做用户注册 / 登录体系：收集链接就是一次性的、带 token 的表单；
• 不做用户端的复杂进度回执与消息推送（决策 3）；
• 不做订单号格式校验（决策 5），但会校验订单是否真实存在（依赖 P0）；
• 不改 order_site 的代码、鉴权与部署（见 §5.2）；
• 不在 order_site 里重建一套兑换流程：只借用它的订单/商品数据；
• 不回写 order_site 的订单状态（本轮只读）；
• 不做接单平台的众包能力（抢单 / 报酬 / 保证金 / 钱包 / 验收申诉）；
• 不做分布式调度 / 多副本部署适配（当前单容器）；
• 不做自动付款：所有涉及花钱的环节仍需人工扫码确认。

15. 待定事项

15.1 需要运维配合（非代码改动，P0/P2 前置）

#	事项	状态
1	order_site PostgreSQL 建只读账号并授权 4 张表	✅ 已完成（livehub_ro，SELECT-only，详见 §6.5）
2	连接串写入 live-hub-py 的 .env 并确认可达	✅ 已完成（/root/live-hub-py/.env，容器实测可达 172.19.0.2:5432）
3	只读保护参数	✅ ���完成（statement_timeout=3s、CONNECTION LIMIT 5、default_transaction_read_only=on）
4	新建 OSS 桶 live-hub-assets（私有 + 版本控制）	✅ 已完成（private ACL、版本控制开启、put/get/list/delete 实测通过）
5	新建 RAM 子账号（只授权该桶 Put/Get/Delete）并写入 AK/SK	✅ 已完成（live-hub-oss + 自定义策略 live-hub-assets-rw，实测最小授权生效）

第 5 项的做法（已完成，留档）

子账号 live-hub-oss 只挂了自定义策略 live-hub-assets-rw（仅 live-hub-assets 桶的 Put/Get/Delete/List），实测：

验证	结果
本桶 Put / Get / Delete / List	✅ 全通（含真实 PNG 上传 → 后端读回，字节与 ContentType 完全一致）
跨桶越权（读 order-site-assets）	✅ AccessDenied —— 最小授权生效
公共 URL 直取	✅ 403 —— 证实桶是私有的，必须走后端代理
HeadBucket	❌ 403（OSS 对 HEAD Bucket 要的权限不在这套策略里）→ object_storage.py 不要用 HeadBucket 做健康检查，用 ListObjectsV2 或 Put/Get 往返

原控制台步骤（供以后给新环境建号时参考）：

1. 阿里云控制台 → RAM 访问控制 → 身份管理 → 用户 → 创建用户
   • 登录名称：live-hub-oss
   • 访问方式：只勾「OpenAPI 调用访问」（不要开控制台登录）
2. 创建后立即保存 AccessKey ID / Secret（只显示这一次）
3. 权限管理 → 新增授权 → 自定义策略 → 新建策略（脚本编辑），粘贴：

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["oss:PutObject", "oss:GetObject", "oss:DeleteObject", "oss:AbortMultipartUpload", "oss:ListParts"],
      "Resource": ["acs:oss:*:*:live-hub-assets/*"]
    },
    {
      "Effect": "Allow",
      "Action": ["oss:ListObjects", "oss:GetBucketInfo", "oss:GetBucketAcl"],
      "Resource": ["acs:oss:*:*:live-hub-assets"]
    }
  ]
}

4. 把 AK/SK 写入 /root/live-hub-py/.env：

OSS_ENDPOINT=https://oss-cn-hangzhou-internal.aliyuncs.com
OSS_BUCKET=live-hub-assets
OSS_ACCESS_KEY_ID=<第 2 步的 ID>
OSS_ACCESS_KEY_SECRET=<第 2 步的 Secret>
OSS_PREFIX=collect

若嫌麻烦，也可先用现有 AK 跑通 P2，之后再收窄权限 —— 但最小授权更稳（.env 泄漏时影响面只有一个桶）。

15.2 自有待确认

1. automation_runs 保留 90 天是否合适（§11.4）；
2. 收集链接默认有效期 7 天是否合适；
3. skin_catalog / skin_aliases 初版由谁确认（分析已完成，只需过一遍 60 个斗鱼商品 + 76 条快手别名）；
4. C 桶的②卡券/道具类（17,948 件）与③纯数字商品名（4,491 件）是否纳入？初步判断：不纳入（疑似走电子凭证自动发码 / 需人工识别）；
5. 是否需要在兑换成功后主动通知用户（目前靠用户自己打开链接看）。

15.3 已定事项（留档）

事项	结论
准入范围	只接 C 桶（没人管）；A（已自动发货）、B（接单平台）都不要（§3.4）
C 桶内①服装类（黑色ROCK/运动服，17,704 件）	后面单独处理，本轮不做
归一的锚点	斗鱼商品目录（78 个），不是快手商品名（§3.5）
皮肤由谁定	唯一命中 → 订单自动定；命中多个 → 用户在链接里选一件（决策 8 + 例外）
斗鱼兑不了的 59.9%	直接拒绝、不建单（负责人已定），后续慢慢优化
匹配键	优先 SKU（relSkuId/skuNick），文本兜底（决策 12）
规则与映射的分工	取消映射层：识别归 skin_aliases/skin_keywords，配置归 exchange_skin_rules（§10.1）；rule_ambiguous 一并去掉
皮肤是否由用户选	不用，由订单号自动对应（决策 8）
是否涉及加好友赠送	不涉及（决策 9）
整合方案	选 B：只读直连 PG，order_site 零改动（§5.2）

---

附录 A · 迁移清单（均为加表/加字段，不动存量数据；编号按落地顺序取）

阶段	迁移内容
P0	external_order_cache
P1a	automation_jobs、automation_runs；login_tasks + relogin_attempts/relogin_next_at/relogin_last_error；accounts + auto_managed（revision 20261002_0037）
P1b	login_tasks + relogin_failure_kind（枚举；按落地顺序取号）
P2	collect_links、collect_submissions（截图只存 object_key，不存 URL/本地路径）
P3	skin_catalog、skin_aliases、skin_douyu_items、account_exchange_records
P4	exchange_skin_rules、exchange_match_logs、exchange_orders、exchange_order_events（4 张，映射层已取消）

附录 B · 文件清单（预估）

后端

文件	阶段	说明
web/backend/models.py	全部	新增表与字段
web/backend/permissions.py	全部	新增权限点与角色默认
web/backend/migrations/versions/*.py	全部	5 个迁移
web/backend/services/automation/scheduler.py	P1	进程内调度线程
web/backend/services/automation/jobs/ck_health.py	P1a	巡检作业
web/backend/services/automation/jobs/ck_relogin.py	P1b	自愈作业
web/backend/services/external_order_source.py	P0	唯一允许写跨库 SQL 的文件
web/backend/services/collect_service.py	P2	token / 限流 / 图片校验与重编码
web/backend/services/object_storage.py	P2	OSS 封装（oss2）：上传/读取/删除，唯一允许出现 OSS SDK 的文件
pyproject.toml	P0/P2	新增依赖：PG 驱动（psycopg[binary] 等，P0）+ oss2（P2）
web/backend/services/skin_service.py	P3	别名归一 + 365 天规则 + 落账
web/backend/services/exchange_order_service.py	P4	匹配 + 状态机 + 事件
web/backend/routers/automation.py	P1	作业管理接口
web/backend/routers/collect.py	P2	公开 + 内部接口
web/backend/routers/skins.py	P3	台账与别名维护
web/backend/routers/exchange_orders.py	P4	工单接口
web/backend/main.py	P1	注册路由 + 启停调度器
.env.example	P0/P1/P2	新增配置项说明

前端

文件	阶段	说明
web/frontend/src/pages/AutomationPage.tsx	P1	作业与运行历史
web/frontend/src/pages/CollectPage.tsx	P2	公开收集页（放在登录判断之外）
web/frontend/src/pages/CollectLinksPage.tsx	P2	链接管理
web/frontend/src/pages/CollectSubmissionsPage.tsx	P2	待处理队列
web/frontend/src/pages/SkinsPage.tsx	P3	台账与别名维护
web/frontend/src/pages/ExchangeRulesPage.tsx	P4	规则与资料模板
web/frontend/src/pages/ExchangeOrdersPage.tsx	P4	工单管理
web/frontend/src/App.tsx	P2	新增路由（公开页需放在 isLoggedIn 分支之外）
web/frontend/src/layouts/MainLayout.tsx	P1~P4	菜单项
web/frontend/src/api/{automation,collect,skins,exchangeOrders}.ts + types.ts	全部	接口封装与类型

文档

文件	说明
docs/自动化与资料收集规划.md	本文档
docs/README.md	索引

附录 C · 施工单（实现顺序与验证）

战略与数据模型在正文已定；这里只写按什么顺序动手、每步怎么验证。

C.1 迁移编号（按落地顺序取，不预留）

现状 head = 20261003_0041（账号事件，在 dev；main 上是 20261003_0040）。谁先落地谁取下一个号，不要按阶段预分配。

阶段	revision	说明
P1a（已落地）	20261002_0037	automation_jobs / automation_runs / login_tasks +3 / accounts.auto_managed
P1b（已落地）	20261002_0038	login_tasks + relogin_failure_kind
P0（已落地）	20261002_0039	external_order_cache
生产热修（已落地）	20261003_0040	douyu_tasks.account_assigned_to + 复合索引（消除任务列表 filesort）
账号事件（已落地，在 dev）	20261003_0041	account_events + audit_logs.account_id（设计）
P2 / P3 / P4	各自落地时依次取号（下一个是 20261003_0042）	见附录 A 的表清单

为什么不能预留编号：Alembic 的 down_revision 必须形成单链。若先给 P1 占 0038、 把 0037 留给 P0，等 P0 真落地时它的 down_revision 只能指向 0038（否则与 0038 平级， 出现两个 head，tests/test_migrations.py 的单头断言会直接失败），编号比父提交还小。 所以按落地顺序递增，才是唯一不别扭的做法。

约定：每个迁移的 down_revision 指向前一个；写成幂等的（照 20261001_0036 的写法，先 sa.inspect 查存在再改）；每加一个迁移，tests/test_migrations.py 的 HEAD_REVISION 要同步改。

⚠️ 迁移编号一旦被任何库应用过就不能再改名。P1a 犯过一次：迁移先叫 20261002_0038，本地 dev 库跑过一次，随后为了链条连续改名成 0037，dev 库里的 alembic_version 还记着 0038，再启动就报 CommandError: Can't locate revision identified by '20261002_0038'。 改名要在还没被任何库应用之前做；已经应用过又必须改名时，除了改文件，还要把每个应用过的库 手动对齐：UPDATE alembic_version SET version_num='<新编号>';（前提是迁移内容没变， 否则要按实际差异补脚本）。

C.2 通用约定

• 测试文件按功能命名：tests/test_<域>_<主题>.py（现有 38 个文件、235 条）；
• 纯函数优先：匹配打分、别名归一、365 天判定、订单号归一、模板必填校验都做成纯函数重点覆盖；
• 写操作不进自动回归：兑换/重登/支付用 mock 客户端做契约测试（沿用 tests/test_douyu_write_path_contracts.py）；
• 提交门禁：pre-commit 跑 ruff format --check（仅暂存文件）+ tsc -b；pre-push 跑全量 pytest；
• 新增环境变量必须同步改 docker-compose.yml：本项目的 compose 用的是 environment: 显式列表（不是 env_file），只写进 .env 不会传进容器。 P1a 踩过一次：.env 加了 AUTOMATION_ENABLED=true，容器里查不到，调度器照旧不启动； 早先 §15.1 写入的 ORDER_SITE_* 与 OSS_* 同样没生效。新增变量时三处都要动： .env（服务器实值）+ docker-compose.yml（透传）+ .env.example（留档）；
• 测试现已跑在真实 MySQL 上（2026-10-02 改造完成，不再用 SQLite）：SQLite 与 MySQL 的方言差异 曾让 NULLS FIRST 这类写法本地全绿、生产 1064，而 P1b 又踩到 SQLite 测不出的 REPEATABLE READ 快照问题（见下条）。现在 tests/conftest.py 指向独立的 douyu_login_test、 每用例前后清表，库名与开发库相同时直接拒绝运行（防误清）；./dev.sh test 需要 MySQL 已启动。 代价：跑测试前要先 ./dev.sh 起库，耗时从约 3.6 秒增至约 13 秒；
• 注意方言差异：生产是 MySQL 8。SQLite 能吃下的写法 MySQL 未必认，行为测试也发现不了。 P1a 踩过一次：ORDER BY ck_checked_at ASC NULLS FIRST 在 SQLite 正常，MySQL 直接报 1064 ... near 'NULLS FIRST'。跨方言的排序用可移植写法（如 col IS NULL DESC, col ASC）， 并在测试里按 MySQL 方言 compile() 一次做回归。P0 更要注意：它连的是 order_site 的 PostgreSQL， 三套方言（MySQL / SQLite / PG）都出现过，写 SQL 前先想清楚方言；
• DB 读出来的时间是 naive UTC：datetime 列取回后不带时区，直接和 datetime.now(UTC) 比较会 TypeError: can't compare offset-naive and offset-aware（P1a 踩过一次）。比较前一律用 _as_utc()（services/yyb_service.py 与 services/automation/scheduler.py 各有一份）补时区。 SQL 里用绑定参数比较不受影响，只有 Python 侧比较需要注意 —— P0 判缓存过期时会再遇到；
• 每个阶段独立可发布，新作业/新功能一律开关默认关闭；
• 迁移是应用启动时自动跑的（database.init_db() → run_migrations() → alembic upgrade head）。 所以「部署」就等于「跑迁移」，不要再手动执行一遍；同时也意味着迁移写坏了会挡住整个应用启动， 必须保持幂等（先 sa.inspect 查存在再改）。想先看效果可在本地 dev 库跑；
• ⚠️ 删除登录任务 = 删除该账号的 CK（2026-10-03 出过事故，丢过 5019 个 CK，详见 事故复盘）：斗鱼 CK 只存在 login_tasks.cookie， accounts 表没有 cookie 列。列表显示的「状态」是 attempt_status（最近一次尝试）， 与「是否持有 CK」（status/cookie）语义不同 —— 当时有 752 行「显示失败但持有 有效 CK」。任何按条件筛选/删除的入口，判定必须基于 cookie 字段；
• ⚠️ 动手前先核实外部库的真实表结构，别信文档和早期分析（P0 踩过一次，差点白干）： 规划 §6.2 写的 orders.order_no(PK) 在真实库里根本不存在，实际是 platform_order_id（且非唯一，541 组重复）。同一订单号下还有「发货方内部行 + 真实店铺行」的成对结构，按单行判 route 会放行 540 个已发货订单。 做法：先用只读账号 SELECT column_name FROM information_schema.columns 核对一遍， 再把结论写进文档（§6.5.1 就是这么留档的）。跨系统的字段假设一律当作待验证；
• 加依赖后必须重锁 uv.lock：Dockerfile 用的是 uv sync --frozen（见 §C.3）， 只改 pyproject.toml 不重锁，生产构建会直接失败。P0 加 psycopg[binary] 时走过一遍： 本地 uv lock + uv sync，提交时带上 uv.lock；
• 验证容器里的代码要 docker cp，挂载只有 logs/data：compose 只 bind 了 /root/live-hub-py/logs 与 /data，代码在镜像里。改完宿主机文件不会自动生效； 临时验证用 docker cp 进 /app，之后记得删掉，别污染生产工作区（会让 git pull 起冲突）；
• 容器里装包要用 uv pip 且指定 VIRTUAL_ENV：容器的 /app/.venv 里没有 pip， 系统 pip 装的东西 venv 里的 python 看不见（P0 验证时白装过一次）。正确姿势： docker exec -w /app <容器> env VIRTUAL_ENV=/app/.venv uv pip install <包>； 另：docker exec -e 覆盖不了 compose 已注入的同名变量，验证时改用容器自带的 env 或在脚本里 os.environ[...] = ...。
• ⚠️ create_all 不会修改已存在的表：测试库靠 Base.metadata.create_all() 建表， 它只建缺失的表。给已有表加列/改列后，测试库里的旧结构不会更新，症状是一堆 不相关的用例同时挂（例如加 audit_logs.account_id 后 22 个用例报 Unknown column 'account_id'）。处理：改已有表的模型后，对测试库手动 ALTER TABLE， 或 DROP TABLE 让它按新模型重建。新增表不受影响（会直接建出来）；
• 灌测试数据要带 --default-character-set=utf8mb4：docker exec -i mysql ... < file 不带这个参数时中文会被双重编码（套装 存成 套装）。排查这类问题的快捷判断： 对可疑列取 HEX()，若是 C3A5C2A5... 这种「UTF-8 再编码一次」的形态， 说明是写坏了而不是读坏了。

C.3 已核实的环境事实

事实	值	对实现的影响
uvicorn worker 数	--workers 1（单容器单进程）	进程内调度线程安全，不需要分布式锁；调度器在 lifespan 里启停
生产路径	/root/live-hub-py，容器 live-hub-py-douyu-login-1	部署 = git pull + ./deploy.sh
鉴权	无全局中间件，逐路由 Depends(get_current_user)	公开路由只要不挂依赖；新路由要在 main.py 注册
PG 驱动	psycopg[binary] 已进 pyproject.toml + uv.lock，已随镜像上线（2026-10-03，容器实测 3.3.6）	部署时随镜像装上
只读 PG	livehub_ro @ order_site-postgres-1:5432，.env 已配（容器内 3 个 ORDER_SITE_* 均可见）	适配层直接用 ORDER_SITE_DATABASE_URL；LOOKUP_ENABLED 仍是 false
OSS	桶 live-hub-assets（私有+版本控制）、RAM live-hub-oss、.env 已配	P2 用 oss2；不要用 HeadBucket
迁移 head / 测试基线	20261002_0039 / 338 条（2026-10-03）	见 C.1；应用启动会自动跑迁移，0039 已在生产应用
时区	库/NOW() 都是 UTC（--default-time-zone=+00:00），接口返回 +00:00，前端转北京时间	别把 SELECT NOW() 当真实时间，详见 README「时区口径」
备份	没有定期逻辑备份；依赖 MySQL ROW 格式 binlog（log_bin=ON，保留 30 天）	误删只能靠 binlog 恢复；不要关 binlog 或缩短保留期；镜像里没有 mysqlbinlog，用 pymysqlreplication

C.4 P1a 施工单（✅ 已按此完成，8 步）

#	动作	文件	验证
1	迁移 0037：automation_jobs、automation_runs；login_tasks +3 字段；accounts.auto_managed	migrations/versions/20261002_0037_automation_jobs.py、models.py	pytest tests/test_migrations.py；本地建表通过
2	调度器骨架：作业注册表、60s tick、进程内锁、开关、automation_runs 记录、优雅停止	services/automation/scheduler.py	单测：假时钟驱动 tick，断言「作业 enabled=false 时不执行」「不重叠执行」
3	ck_health 作业：选行（cookie_holding_filter + 超期 + 排除在途/auto_managed=false）、并发 5、调 check_douyu_cookie()、写回 ck_check_*	services/automation/jobs/ck_health.py	单测：选行条件正确；断言全程不写 cookie / status（P1a 的核心约束）
4	接口 + 权限 + 注册：4 个 /api/automation/*；automation:view / automation:manage；lifespan 启停	routers/automation.py、permissions.py、main.py	tests/test_automation_api.py：权限校验、开关生效、手动触发
5	补 login:batch 审计	routers/login.py	单测：发起批次后 audit_logs 有记录
6	前端：作业卡片 + 运行历史 + 手动触发；路由/菜单/接口封装	pages/AutomationPage.tsx、App.tsx、MainLayout.tsx、api/automation.ts	tsc -b + npm run build
7	本地端到端：对 3~5 个账号跑一轮，与人工点「检测」的结果逐条比对	——	结果一致才进入下一步
8	上线：git pull + ./deploy.sh → 先 batch_size=50 跑一轮看风控 → 无异常再调到 200	——	/automation 页面能看到每轮明细；CK 未被改动

P1a 完成定义（DoD）：接口能开关与手动触发；巡检结果与人工检测一致；login_tasks.status / cookie 全程无变化；关掉开关后调度立即停止。

C.4-bis P0 施工单（✅ 已完成，2026-10-02；迁移 0039）

#	动作	文件	验证
1	加 PG 驱动 psycopg[binary] 并重锁 uv.lock（Dockerfile 用 uv sync --frozen，不重锁构建会失败）	pyproject.toml、uv.lock	容器内 import psycopg 通过
2	迁移 0039：external_order_cache，主键 platform_order_id + source_order_id	migrations/versions/20261002_0039_external_order_cache.py、models.py	pytest tests/test_migrations.py（HEAD_REVISION 已同步）；本地建表通过
3	适配层（唯一跨库 SQL）：URL 归一、statement_timeout=3s、2 条连接池、订单号维度聚合 route、回显取真实店铺行	services/external_order_source.py	tests/test_external_order_source.py（24 条）
4	真机验证（只读账号 livehub_ro）	tests/test_external_order_source_live.py（手工跑，未配 URL 时 skip）	见下
5	降级开关验证	——	未配 URL / ENABLED=false / 库不可用时均抛 OrderLookupUnavailable，主流程照常

真机验证结果（生产容器，ORDER_SITE_LOOKUP_ENABLED 临时打开）

用例	route	回显	结论
C 桶 2627501602915345	unhandled	激萌罗小黑	✅ 进候选
B 桶 2627501932004488	worker_platform	指挥官密钥4个	✅ 拒绝
A 桶 2627501850053080	auto_fulfilled	套装-浪漫天命	✅ 拒绝
重复组 2624100167260659	auto_fulfilled	狂沙舞者	✅ 拦下，且回显真实店铺行
重复组 2624100563293477	auto_fulfilled	100011	✅ 拦下
不存在 0000000000000000	——	——	✅ 明确「订单号不存在」
单次查询耗时	——	——	✅ 3.3 ms（要求 < 50ms）

⚠️ 上线前还需做（P0 未完的部分）

1. ORDER_SITE_LOOKUP_ENABLED 仍为 false（默认关闭）—— 要正式启用需改生产 .env 并重启；
2. 生产库还没跑迁移 0039 ✅ 已于 2026-10-03 部署时自动应用（external_order_cache 表已存在，psycopg 3.3.6 随镜像装上）；
3. P0 目前只有适配层，没有接口和页面 —— 运营还查不了。按 §12 排期，接口/页面可随 P2 收集链接一起上（用户填订单号时调用）。

C.5 其余阶段的施工顺序（粗粒度）

阶段	顺序
P0	① pyproject.toml 加 psycopg[binary] → ② 迁移（取下一个号）+ models.py → ③ external_order_source.py（唯一跨库 SQL；URL 归一成 postgresql+psycopg://；statement_timeout；2 条连接池） → ④ tests/test_external_order_source.py（用真实只读账号跑只读查询，覆盖 A/B/C 三桶与不存在订单） → ⑤ 降级开关验证
P2	① 迁移（取下一个号）→ ② object_storage.py（oss2，Put/Get/Delete/List，不用 HeadBucket） → ③ collect_service.py（token/限流/图片校验+Pillow 重编码+缩略图） → ④ 公开路由 /api/public/collect/* + 内部 /api/collect/* → ⑤ 前端公开页（放 App.tsx 的 /login 同级）+ 内部两页 → ⑥ 测试（含"宿主机找不到图片副本"的验收）
P3	① 迁移（取下一个号）→ ② skin_catalog 从 douyu_goods_snapshot 同步 + sku_catalog_sync 作业（挂 P1 调度器） → ③ skin_service.py（别名归一 + can_exchange 365 天 + 落账） → ④ /api/skins/* → ⑤ /skins 页 → ⑥ 把 62 条唯一映射 + 14 条多选映射导入
P4	① 迁移（取下一个号）→ ② exchange_order_service.py（resolve_skin 两步匹配 + 状态机 + 事件） → ③ 前置校验（CK/365 天/绑定/积分） → ④ 工单接口 + 与 collect_submissions 衔接 → ⑤ /exchange-rules + /exchange-orders 两页 → ⑥ 端到端联调（发链接 → 提交 → 校验 → 执行 → 台账）