feat(platform): 增加履约分类映射管理并锁定迁移

This commit is contained in:
yml
2026-11-21 14:41:36 +08:00
parent 8580f9738d
commit 7396126c73
20 changed files with 3093 additions and 115 deletions
+2
View File
@@ -18,7 +18,9 @@
- [精英宝典 HAR 提取](虎牙/HAR提取CK与积分中心.md):HAR 中的完整 CK、积分中心和商品结构。
- [皮肤准入映射分析](皮肤准入映射分析.md):快手皮肤订单到斗鱼商品的覆盖与映射边界。
- [直播账号履约工作台](直播账号履约工作台.md):order_site 人工订单、斗鱼账号租约、客户扫码绑定和人工兑换。
- [直播账号履约分类与映射规划](直播账号履约工作台分类与映射规划.md):斗鱼单平台阶段的预售/现货分类、工作队列、映射 CRUD 和分阶段 TODO。
- [斗鱼协议总览](斗鱼/DOUYU_PROTOCOL_OVERVIEW.md):斗鱼绑定、精英宝典、兑换、支付、多 alias 判定和排障日志的统一入口。
- [数据库迁移规范](数据库迁移规范.md):迁移文件不可变 manifest、启动校验、repair revision 和禁止 stamp 的规则。
## 协议与逆向证据
+100
View File
@@ -0,0 +1,100 @@
# 数据库迁移规范
更新时间:2026-11-21
## 硬性规则
1. **已经提交并可能执行过的迁移文件禁止修改**:包括改 SQL、改 `revision`、
改 downgrade、改注释和格式化。
2. 发现历史结构不一致时,只能新增后续 `repair` revision,不能回头改旧迁移。
3. 禁止通过 `alembic stamp` 伪造版本;只有灾难恢复且完成备份、人工审查后才能使用。
4. 新迁移必须在真实 MySQL 临时库执行完整 `upgrade head` 和模型一致性测试。
5. 迁移修复不能依赖“本地已经手工执行过某条 SQL”,所有结构变化必须在 revision 中。
## 迁移不可变 Manifest
仓库维护:
```text
web/backend/migrations/migration_manifest.json
```
其中记录每个迁移文件的:
- 文件名
- revision
- SHA256
应用启动、`dev.sh` 迁移和测试都会先校验 manifest。
只要已登记迁移发生变化,启动会直接失败,例如:
```text
迁移不可变校验失败:
- 已发布迁移内容被修改: 20261120_0101_douyu_task_durable_schedule.py
```
此时不能重新生成 manifest 了事,必须:
1. 还原旧迁移文件;
2. 新增后续修复 revision;
3. 运行测试;
4. 再登记新迁移。
## 新增迁移流程
```bash
uv run alembic revision -m "说明"
```
编辑新迁移后:
```bash
uv run pytest -q tests/test_migrations.py tests/test_migration_immutability.py
uv run python -m web.backend.migrations.immutability --write
uv run python -m web.backend.migrations.immutability
```
`--write` 默认只接受“新增文件”;如果已有迁移的 revision 或 SHA256 发生变化,
它也会拒绝写入。
只有灾难恢复才允许:
```bash
uv run python -m web.backend.migrations.immutability --write --force
```
使用 `--force` 必须在提交说明中写明原因,并人工审查 manifest diff。
## 生产核对
只读检查不会改变结构。常用命令:
```sql
SELECT version_num FROM alembic_version;
SHOW COLUMNS FROM douyu_tasks;
SHOW INDEX FROM douyu_tasks;
```
`SELECT`、`SHOW COLUMNS`、`information_schema` 查询都不会删除或修改列。
如果应用报 `Unknown column`,优先检查:
- 当前运行镜像是否和代码提交一致;
- `alembic_version` 是否与实际表结构一致;
- 是否存在旧迁移被修改、手工 stamp 或未执行完的 DDL;
- 新环境执行迁移时是否因为没有 manifest 校验而得到了另一套结构。
## 本次事故
`20261120_0101` 在首次提交后又修改过 generated column 的持久化选项。Alembic
只记录 revision,不记录脚本内容,因此本地数据库可能已经执行过旧内容,但版本号
仍然显示在新 revision。另一次本地库漂移表现为所有 0101 字段都在,只有
`active_binding_key` 缺失。
处理方式:
- 新增 `20261121_0107_repair_douyu_active_binding_key.py` 幂等修复;
- 清理重复活动二维码任务;
- 补回列和唯一索引;
- 从现在开始用 manifest 锁定全部 107 个迁移文件;
- 不再允许通过修改旧迁移“顺便优化”。
+24
View File
@@ -101,6 +101,30 @@
履约详情会长期展示该凭证,支持查看大图、复制和下载;斗鱼任务日志被清理后,
履约任务上的图片引用仍保留。
## 销售模式与工作队列
商品映射是销售模式的主要录入入口。新建或编辑斗鱼商品映射时必须选择:
- `预售`:客户下单时商品尚未开放;
- `直接兑换`:商品已开放;
- `人工`:必须人工确认的特殊单。
销售模式属于活动批次快照。任务应用映射时复制 `saleMode`、活动批次和开放时间;
后续修改映射不能反向改写履约中的历史任务。预售任务到达开放时间后仍保留
`saleMode=presale`,但开放状态变为 `available`,并自动进入“可履约”队列。
工作台默认显示“当前待办”,不再把已完成和已取消订单混入“全部”。一级队列包括:
- 当前待办
- 预售待开放
- 可履约
- 需要人工
- 已完成
- 已取消
“需要人工”继续按积分不足、宝典未开通、限兑、绑定异常、账号冷却等原因细分。
商品映射支持新建、编辑、启停、归档、恢复和删除;已被任务引用的映射只能归档。
## 账号租约
账号租约默认无限制,适合当前“分配后由运营人工处理”的流程。管理员可在
@@ -0,0 +1,411 @@
# 直播账号履约工作台分类与映射规划
更新时间:2026-11-21
## 范围
近期只优化斗鱼单平台,不接虎牙。
本计划解决:
- 预售、直接兑换和历史任务混在一个列表;
- `manual_required` 把积分不足、未开通宝典、限兑等问题混成一类;
- 商品映射只有覆盖式新增,没有完整 CRUD、版本和归档;
- 同一商品后续返场时,旧映射会被覆盖,历史语义丢失。
暂不实现:
- 虎牙履约;
- 跨平台统一适配器;
- 自动兑换、自动充值;
- 物理拆分履约任务表。
虎牙只在“未来兼容边界”中保留,不进入本轮开发。
## 当前问题
### 1. 单表不是根因
`platform_fulfillment_tasks` 同时承载订单、账号租约、绑定和兑换阶段是合理的。
任务必须共享幂等、Outbox、租约和时间线,不能按平台或销售模式拆表。
真正缺少的是正交分类字段:
- 销售模式:预售 / 直接兑换;
- 商品开放状态:未开放 / 可兑换 / 售罄 / 已结束;
- 履约阶段:待映射 / 待分配 / 待绑定 / 待兑换 / 待人工 / 已结束。
这三类信息不能用同一个 `execution_status` 表达。
### 2. 订单源没有明确销售模式
当前 `order_site` 快照只提供订单、SKU、支付和履约状态,没有稳定的
`sale_mode` 字段。`spec_json` 虽被保留,但不能作为可靠业务字段直接解析。
因此首期不能让代码从商品名猜“预售/现货”:
- 新字段未知时显示“未分类”;
- 管理员在创建或编辑商品映射时明确选择“预售 / 直接兑换 / 人工”;
- 任务应用映射时把销售模式快照到任务;
- 管理员可在报价映射或任务上人工修正;
- 后续推动 `order_site` 在快照中增加明确 `saleMode`。
映射是首期销售模式的主要录入入口。人工区分必须作为新映射/返场批次的必填项,
不能在列表里逐单临时猜测。后续 `order_site` 提供正式字段时,订单字段优先,
映射值作为缺失时的回退,并在任务上记录 `classification_source`。
### 3. 斗鱼“预兑”不等于业务“预售”
`subscribe`、`pre_exchange`、`wait` 是斗鱼商品当前动作状态,不等于用户下单时
购买的销售模式。业务预售应由订单/报价快照决定;斗鱼动作状态只决定当前能否兑换。
### 4. 现有映射没有版本
当前唯一约束是:
```text
(target_platform, internal_sku_key)
```
同一皮肤下一次返场时只能覆盖旧映射。即使暂时不接虎牙,也需要“同平台多返场
批次”的历史记录。
### 5. 映射 API 和页面不完整
当前只有:
- `GET /mappings`
- `PUT /mappings` 覆盖式新增/更新
缺少:
- 按 ID 编辑;
- 启用/停用;
- 归档/恢复;
- 历史版本;
- 关联任务预览;
- 删除前引用检查;
- 返场批次和开放时间。
## 分类模型
### 销售模式
`sale_mode`:
| 值 | 含义 |
| --- | --- |
| `presale` | 预售/返场预约,平台尚未开放兑换 |
| `direct` | 已开售,按正常履约流程处理 |
| `manual` | 必须人工确认的特殊单 |
| `unknown` | 来源未提供,不能猜 |
销售模式由管理员在映射表单中人工选择。销售模式表示“客户购买时这一批商品是
预售还是直接兑换”,属于历史事实;活动到期或开放后不能把任务上的
`presale` 改写为 `direct`。
### 平台开放状态
`availability_state` 为派生状态,不落业务真值:
| 值 | 判定 |
| --- | --- |
| `waiting_release` | 当前时间早于 `available_from` |
| `available` | 在开放区间且有库存 |
| `sold_out` | 在活动期内但无库存 |
| `ended` | 当前时间晚于 `available_until` |
| `unknown` | 没有可靠的商品开放快照 |
### 履约队列
`queue_bucket` 由 API 派生:
| 队列 | 判定 |
| --- | --- |
| `pending_mapping` | 没有有效映射 |
| `presale_waiting` | 销售模式预售,平台未开放 |
| `ready_for_fulfillment` | 平台已开放,待选号/待绑定/待兑换 |
| `needs_action` | 积分不足、未开通宝典、限兑、绑定异常等 |
| `completed` | 已完成 |
| `cancelled` | 已取消/关闭 |
`manual_required` 需要进一步细分为:
- `points_short`
- `elite_not_opened`
- `limit_reached`
- `binding_failed`
- `account_cooldown`
- `other_manual`
这些细分优先从现有 `issue_code`、`exchange_status` 和绑定状态派生,不立即增加
大量状态枚举。
## 数据模型
### PlatformCommodityMapping
继续作为斗鱼商品报价表,新增:
- `campaign_key`:返场/活动批次,如 `douyu-2026-11-return`;
- `campaign_name`;
- `sale_mode`;
- `available_from`;
- `available_until`;
- `released_at`;
- `goods_status`:最近刷新商品时的平台状态;
- `version`;
- `archived_at`;
- `archived_by`。
唯一约束从:
```text
(target_platform, internal_sku_key)
```
调整为:
```text
(target_platform, internal_sku_key, campaign_key)
```
同一内部 SKU 可以保留历史返场记录,但同一批次仍只允许一条。
### PlatformFulfillmentTask
新增报价快照字段:
- `sale_mode`
- `campaign_key`
- `offer_available_from`
- `offer_available_until`
- `classification_source`:`order_sync / mapping / manual / unknown`
任务创建或映射应用时复制快照。后续修改报价不能改变历史任务。
映射应用规则:
- 新任务:从当前有效映射复制 `sale_mode` 和开放时间;
- 已存在但 `pending_mapping` 的任务:应用映射时补快照;
- 已进入履约中的任务:默认不因映射编辑而改变销售模式;
- 管理员确需纠正时,走单独“修正分类”操作并写审计和任务事件。
### 不新增的表
斗鱼单平台阶段不新增 `products`、`platforms`、`offers` 三套表。先用现有
`internal_sku_key` 和 `platform_commodity_mappings` 演进,避免过度设计。
虎牙接入时再评估:
- 抽出内部商品表;
- 平台报价表增加平台引用;
- 履约编排层增加平台适配器。
## 映射 CRUD
### API
```text
GET /api/platform-fulfillment/mappings
POST /api/platform-fulfillment/mappings
PATCH /api/platform-fulfillment/mappings/{id}
POST /api/platform-fulfillment/mappings/{id}/enable
POST /api/platform-fulfillment/mappings/{id}/disable
POST /api/platform-fulfillment/mappings/{id}/archive
POST /api/platform-fulfillment/mappings/{id}/restore
GET /api/platform-fulfillment/mappings/{id}/impact
```
删除规则:
- 未被任务引用:允许管理员物理删除;
- 已被任务引用:只能归档,禁止删除;
- 所有写操作保留审计。
### 页面
映射不再只放在任务弹窗中,改为独立“商品映射”管理页或抽屉:
- 搜索内部 SKU、平台商品 ID、商品名;
- 按销售模式、开放状态、启用状态、活动批次筛选;
- 新建、编辑、启停、归档、恢复;
- 复制上一次返场生成新批次;
- 查看该映射影响的任务数量;
- 展示最近刷新商品状态和开放时间。
新建或编辑映射时必须包含:
- 销售模式:预售 / 直接兑换 / 人工 / 未分类;
- 活动批次;
- 预售时填写“预计开放时间”;
- 直接兑换时填写或自动读取开放区间;
- 选择后预览会影响的待分配任务数量和销售模式。
任务详情里的“商品映射”只负责进入该 SKU 的映射管理,不再承担完整 CRUD。
## 工作台 UI
### 默认视图
默认不再显示“全部”。默认进入“当前待办”:
- 排除 `completed`、`cancelled`;
- 按待映射、预售、可履约、人工异常分组;
- 保持分页和关键词搜索。
### 一级分类
建议使用 Tabs:
- `当前待办`
- `预售待开放`
- `可履约`
- `需要人工`
- `已结束`
预售单到达开放时间后仍保留 `sale_mode=presale`,但 `availability_state` 从
`waiting_release` 变为 `available`,并进入“可履约”工作队列。历史销售分类和
当前可执行性必须分开保存。
### 二级筛选
- 销售模式:全部 / 预售 / 直接兑换 / 未分类
- 履约阶段
- 人工原因
- 商品活动批次
- 平台商品开放状态
- 账号与客服
### 表格列
增加:
- 销售模式
- 活动批次
- 商品开放状态
- 开放/结束时间
- 人工原因
保留:
- 订单/SKU
- 映射
- 账号
- 绑定
- 兑换资格
- 更新时间
- 操作
## 实施计划
### Phase 0:数据审计与口径确认
- 盘点 `spec_json` 中可能存在的销售模式字段;
- 与 `order_site` 确认未来是否能提供稳定 `saleMode`;
- 确认“预售”的业务定义:下单时商品未开放,还是订单需要两阶段履约;
- 统计现有任务中预售/现货可回填比例。
验收:不靠商品名猜测,未知数据明确显示“未分类”。
### Phase 1:模型和迁移
- 给映射增加批次、销售模式、开放时间、版本、归档字段;
- 给任务增加报价快照字段;
- 调整唯一约束;
- 现有 19 条映射回填 `sale_mode=unknown`、活动批次 `douyu-current`;
- 保持现有斗鱼流程不变。
验收:迁移可回滚,历史任务不被覆盖,现有选号和兑换流程无变化。
### Phase 2:映射 CRUD
- 增加创建、编辑、启停、归档、恢复和影响预览 API;
- 开发独立映射管理界面;
- 增加审计和引用保护;
- 支持复制历史批次生成新返场映射。
验收:管理员不再覆盖旧映射即可完成新返场配置。
### Phase 3:分类查询和 UI
- 列表 API 增加 `queue_bucket`、`sale_mode`、`availability_state`;
- 默认隐藏结束任务;
- 增加一级 Tabs 和二级筛选;
- 细分 `manual_required` 原因;
- 保留旧 `status` 参数兼容现有调用。
验收:客服进入页面能直接看到当前待办,不需要从全部历史单中人工寻找。
### Phase 4:自动分类
- 商品刷新时同步开放/结束时间和库存状态;
- 定时将预售任务从 `presale_waiting` 派生到 `ready_for_fulfillment`;
- 仍然只更新派生展示,不把平台状态写入履约终态。
验收:活动开放后不需要人工重新映射,任务自动进入可履约队列。
## TODO
### P0
- [ ] 确认 `order_site` 是否已有预售/现货字段;
- [ ] 确认 `spec_json` 的稳定字段清单;
- [ ] 确定预售业务定义和人工修正权限;
- [ ] 确定映射表单中销售模式默认值:建议默认 `unknown`,禁止静默默认成现货;
- [ ] 确定预售开放时间的必填/可选规则;
- [ ] 盘点当前 358 条待映射任务的 SKU;
- [ ] 盘点 `manual_required` 1512 条的原因分布。
### P1
- [x] 增加映射 `campaign_key/campaign_name/sale_mode/available_from/available_until/version/archived_at`;
- [x] 增加任务报价快照字段;
- [x] 调整映射唯一约束;
- [x] 回填现有映射和任务;
- [x] 增加迁移和模型一致性测试。
### P2
- [x] 增加映射创建 API;
- [x] 增加映射编辑 API;
- [x] 增加启停、归档、恢复 API;
- [x] 增加任务影响预览;
- [x] 增加审计;
- [x] 开发映射管理页面;
- [ ] 增加“复制为下一返场批次”。
- [x] 映射表单增加“预售 / 直接兑换 / 人工”人工选择和开放时间;
- [ ] 保存前展示受影响的待映射任务数量。
### P3
- [x] 列表 API 增加 `queueBucket/saleMode/availabilityState`;
- [x] 默认排除已完成和已取消;
- [x] 增加一级 Tabs;
- [x] 增加二级筛选;
- [x] 细分人工处理原因;
- [x] 调整表格列和详情抽屉;
- [x] 增加前端类型检查、构建和接口测试。
### P4
- [ ] 商品刷新同步开放时间和库存;
- [x] 开放时间到达后更新可履约分类;
- [ ] 增加分类变更日志;
- [ ] 增加管理员修正销售模式操作及审计;
- [ ] 增加分类统计和积压告警。
### 虎牙 TODO
- [ ] 不进入近期排期;
- [ ] 接入前抽出平台适配器;
- [ ] 接入前评估内部商品与平台报价分表;
- [ ] 保持当前任务表和内部 SKU 可复用。
## 兼容边界
- 所有新增 API 字段使用可选值,旧前端仍能只读旧字段;
- `execution_status` 和 `exchange_status` 仍是履约真值;
- `queue_bucket` 和 `availability_state` 是派生字段,可由服务端重算;
- 历史映射不物理删除;
- 任务必须保存映射快照,不允许展示时回查最新映射覆盖历史语义。