feat: 重做协作台账状态机并支持充值核账
This commit is contained in:
+121
-55
@@ -43,7 +43,7 @@ CK 自带完整生命周期(导入 → 验证 → 使用/失效 → 重贴/重
|
||||
|
||||
1. 外部 CK 的 CRUD:新增(粘贴 CK)、编辑、删除,解析出 uid/昵称;
|
||||
2. CK 全生命周期:`unverified → valid → invalid`,支持重贴、从 `raw_cookie` 重建、人工停用;
|
||||
3. 业务全生命周期:`pending → bound → recharged → scripted → done`,旁路 `void`;
|
||||
3. 业务全生命周期:`incomplete → to_recharge → recharged → scripted → done`,核账异常 `points_error`,旁路 `failed` / `void`;
|
||||
4. 多人在同一张表上协作:共享视图 + 负责人 + 字段级审计 + 并发保护;
|
||||
5. 两个图片槽位(绑定图 / 主页账号图)走 OSS,行内可预览。
|
||||
|
||||
@@ -97,12 +97,21 @@ CK 自带完整生命周期(导入 → 验证 → 使用/失效 → 重贴/重
|
||||
| `bind_images` | JSON | 绑定图 object_key 数组(E 列) |
|
||||
| `home_images` | JSON | 主页账号图 object_key 数组(F 列) |
|
||||
| `gift_name` | varchar(128) | 礼包名(G 列,原表头写的"备注") |
|
||||
| `required_points` | int nullable | 该单礼包所需积分快照(选中礼包时从 `queryAllocation` 带出,可手工修正) |
|
||||
| `remark` | varchar(512) | 自由备注 |
|
||||
| `status` | varchar(16) index | 业务状态(§4.1) |
|
||||
| `bound_at` | datetime | 绑定完成时间 |
|
||||
| `recharged_at` | datetime | 充值完成时间 |
|
||||
| `bound_at` | datetime | 资料齐全、进入「待充值」的时间(列名沿用历史) |
|
||||
| `recharged_at` | datetime | 充值核账通过时间 |
|
||||
| `scripted_at` | datetime | 上脚本时间 |
|
||||
| `done_at` | datetime | 抢购成功时间 |
|
||||
| `points_checked_at` | datetime | 最近一次充值核账时间 |
|
||||
| `points_balance` | int nullable | 核账时该组账号积分合计 |
|
||||
| `points_required_total` | int nullable | 核账时该组礼包所需积分合计 |
|
||||
| `points_surplus` | int nullable | 结余 = 积分合计 - 礼包合计 |
|
||||
| `points_threshold` | int nullable | 本次核账使用的允许结余阈值 |
|
||||
| `points_check_reason` | varchar(16) | `ok` / `shortage` / `excess` / `error` |
|
||||
| `points_check_message` | varchar(512) | 给人看的核账结论 |
|
||||
| `points_check_detail` | JSON nullable | 同组订单、各 uid 余额、缺口/多余等明细 |
|
||||
| `void_reason` | varchar(256) | 作废原因(`status=void` 时必填) |
|
||||
| `archived_at` | datetime index | **归档时间**;非空 = 已归档(可见性状态,不是业务状态,§4.4) |
|
||||
| `archived_by` | int FK `users.id` | 归档人 |
|
||||
@@ -203,54 +212,74 @@ CK 自带完整生命周期(导入 → 验证 → 使用/失效 → 重贴/重
|
||||
### 4.1 业务状态机(一行的进度)
|
||||
|
||||
```
|
||||
incomplete ─资料齐全─▶ pending ─人工确认─▶ bound ─充值─▶ recharged ─上脚本─▶ scripted ─抢购成功─▶ done
|
||||
│ │ │ │ │ │
|
||||
└──────────────────┴─────────────────┴──────────────┴─────────────────┴──────────────────┴──▶ failed(抢购失败)
|
||||
│ │ │ │ │ │
|
||||
└──────────────────┴─────────────────┴──────────────┴─────────────────┴──────────────────┴──▶ void(作废)
|
||||
incomplete ─资料齐全且 CK 有效─▶ to_recharge ─充值核账─▶ recharged ─上脚本─▶ scripted ─抢购成功─▶ done
|
||||
▲ │ │
|
||||
└────────关键资料被清空──────────┘ ├─▶ points_error(积分不足 / 多出超过阈值)
|
||||
└─▶ failed(抢购失败)
|
||||
任意流程内状态 ───────────────────────────────────────────────▶ void(作废)
|
||||
```
|
||||
|
||||
| 状态 | 含义 | 进入条件 | 谁可触发 |
|
||||
| --- | --- | --- | --- |
|
||||
| `incomplete` | **待补资料** | 新建时只填订单号 + 店铺、CK / 礼包 / 主页截图留空即可(点一次「新建」自动进这里,2026-10-17) | 人工 |
|
||||
| `pending` | 待处理 | 完整新建 / 上传导入后的默认态;或「待补资料」补齐 CK + 礼包名 + 主页截图后进入 | — / 人工 |
|
||||
| `bound` | **已确认绑定** | 人工核对「探针读到的绑定角色」与「主页截图」一致后手动切 | 人工(单行 / 批量) |
|
||||
| `recharged` | 已充值 | 充值完成后手动切(可跳步);写 `recharged_at` | 人工 |
|
||||
| `scripted` | 已上脚本 | 脚本上完后手动切(可跳步);写 `scripted_at` | 人工 |
|
||||
| `incomplete` | **待补资料** | 新建 / 粘贴导入的默认态;资料被清空时也会自动退回 | 人工 / 系统 |
|
||||
| `to_recharge` | **待充值** | 外部 CK、绑定账号、绑定角色、礼包名、至少 1 张主页截图齐全,**且 CK 有效**;由服务层自动推进 | 系统自动 |
|
||||
| `recharged` | 已充值 | **只能**通过充值核账(`POST /external-orders/recharge`):整组积分结余在 `[0, 阈值]`;写 `recharged_at` | 系统核账 |
|
||||
| `points_error` | **积分异常** | 同上,但整组结余 `< 0`(不足)或 `> 阈值`(多出);写 `points_check_*` 快照 | 系统核账 |
|
||||
| `scripted` | 已上脚本 | 人工切换(可跳步);写 `scripted_at` | 人工 |
|
||||
| `done` | **抢购成功** | 人工切;**或**「已上脚本」的单查积分/兑换记录命中礼包后自动切(§5.7) | 人工 / 系统判定 |
|
||||
| `failed` | **抢购失败** | 人工切;**或**「已上脚本」的单查兑换记录**没有**这个礼包后自动切(§5.7) | 人工 / 系统判定 |
|
||||
| `void` | 已作废 | 任意流程内状态可进;`void_reason` 必填 | 人工 |
|
||||
|
||||
**规则**(2026-10-16 用户拍板的口径,旧版"只能一步一步往前"作废):
|
||||
**规则**(2026-10-19 用户拍板的新口径):
|
||||
|
||||
1. **人工切换允许往前跳步**:目标阶段序号 ≥ 当前即放行(`is_forward_status()`)。
|
||||
实际场景就是会跳(没记充值就直接上脚本),逼人一步一步点只会逼出假数据。
|
||||
跳步会把沿途的 `*_at` 时间戳**补齐**(`_sync_stage_timestamps()`),
|
||||
否则会出现"已上脚本但没有充值时间"的自相矛盾。
|
||||
2. **回退必须显式声明**:目标阶段序号 < 当前时必须 `rollback=true`(界面勾「回退」),
|
||||
会**清掉后面阶段的时间戳**(`scripted → pending` 之后 `bound_at/recharged_at/scripted_at` 全为 null),
|
||||
审计里 `rollback=true` 留痕。
|
||||
3. **`failed` / `void` 是旁路**:流程内任意状态都能进(不用勾回退);
|
||||
从这两态回到流程内**必须** `rollback=true`。`void` 不可逆(只能编辑或新建),
|
||||
`failed` 可回流程内(人工确认后重试)。
|
||||
4. **作废 / 失败不动流程时间戳**:`void` / `failed` 保留原来的 `scripted_at` 等 ——
|
||||
那是"什么时候上的脚本"的证据,与"结果成没成"无关。
|
||||
5. **进入 `bound` 的前置校验放在服务层**(`_assert_can_enter_bound()`):
|
||||
**CK + 绑定角色(探针)+ 主页截图**三样缺一不可,缺什么在错误里写清(400)。
|
||||
绑定图(`bind_images`)与自由文本「绑定斗鱼号」**不再**参与这门校验
|
||||
—— 绑定关系现在由探针读,绑定图已停用(§11.3)。
|
||||
6. **不用一个布尔列表达"充值/上脚本"**:`recharged_at` / `scripted_at` 是
|
||||
"什么时候做过"的证据,`status` 是"现在卡在哪"。两者都留,
|
||||
才能既显示"已充值/已上脚本"这种组合,也能显示"只充了没上脚本"的中间态。
|
||||
7. **离开「待补资料」要求资料齐全**(`_assert_can_leave_incomplete()`):
|
||||
外部 CK / 礼包名 / 主页截图三样缺一不可,缺什么在错误里写清(400)。
|
||||
作废 / 抢购失败是旁路,不受这条限制;新建草稿单不跑探针、不做严格校验。
|
||||
1. **不再有人工 `pending` / `bound`**:客户资料齐全 + CK 有效后自动进 `to_recharge`。
|
||||
旧数据里这两个值由迁移 `20261019_0061` 转成 `to_recharge`(资料齐全)或 `incomplete`。
|
||||
2. **自动推进**(`_maybe_advance_to_recharge()`):创建、编辑、补图、验证 CK 后都会检查
|
||||
资料完整性;满足条件时从 `incomplete` 自动切到 `to_recharge`,审计写
|
||||
`huya:collab:status_auto`(`reason=data_complete`)。
|
||||
3. **自动退回**(`_maybe_demote_missing_data()`):`to_recharge` / `points_error` 的关键资料
|
||||
(CK、绑定账号、绑定角色、礼包名、主页截图)被清空时,自动退回 `incomplete`,
|
||||
审计 `reason=data_missing`。**CK 失效本身不触发退回**:业务上可能只是凭据过期,
|
||||
充值核账会强制重验并阻止误判。
|
||||
4. **换 CK 不回退业务状态**:`set_ck()` 只把 `ck_status` 打回 `unverified`;等用户点
|
||||
「充值核账」时强制重验。若探针读到的 `bind_game_account` 变了,整组核账报错,
|
||||
不会把订单误落到旧账号组。
|
||||
5. **人工切换允许往前跳步**:目标阶段序号 ≥ 当前即放行(`is_forward_status()`)。
|
||||
跳步会把沿途的 `*_at` 时间戳**补齐**(`_sync_stage_timestamps()`)。
|
||||
6. **回退必须显式声明**:目标阶段序号 < 当前时必须 `rollback=true`(界面勾「回退」),
|
||||
会清掉后面阶段的时间戳,审计里 `rollback=true` 留痕。
|
||||
7. **`failed` / `void` 是旁路**:流程内任意状态都能进(不用勾回退);从这两态回到流程内
|
||||
**必须** `rollback=true`。`void` 不可逆(只能编辑或新建),`failed` 可回流程内重试。
|
||||
8. **`recharged` / `points_error` 不能人工直写**:`set_status()` 只有核账流程传
|
||||
`allow_recharge=True` 才接受这两个目标;普通状态接口和批量改状态都会返回
|
||||
`recharge_check_required`。`points_error` 补足/调整积分后重新核账即可回到 `recharged`
|
||||
或 `to_recharge`。
|
||||
9. **不用一个布尔列表达"充值/上脚本"**:`recharged_at` / `scripted_at` 是
|
||||
"什么时候做过"的证据,`status` 是"现在卡在哪"。两者都留。
|
||||
10. **离开「待补资料」要求资料齐全**(`_assert_can_leave_incomplete()`):
|
||||
外部 CK / 绑定账号 / 绑定角色 / 礼包名 / 主页截图缺一不可;作废 / 抢购失败是旁路,
|
||||
不受这条限制。
|
||||
|
||||
**充值核账(整组,`check_recharge_groups()`)**:
|
||||
|
||||
- 分组键 = **精确的 `bind_game_account`**;组内只统计 `to_recharge / recharged /
|
||||
points_error`,`incomplete / scripted / done / failed / void` 不参与;
|
||||
- 同一 uid 只验一次 CK、只查一次积分;组内多个 uid 的积分**合计**;
|
||||
- `必充积分 = Σ required_points`;`结余 = 账号积分合计 - 必充积分`;
|
||||
- `结余 < 0` → 整组 `points_error`(`reason=shortage`);
|
||||
`结余 > 阈值` → 整组 `points_error`(`reason=excess`);其余 → 整组 `recharged`;
|
||||
- 阈值默认 `100`,前端可改并记忆;范围 `0..1_000_000`;
|
||||
- CK 失效 / 积分查询失败 / 缺少 `required_points` 时**整组保持原状态**并逐组报错;
|
||||
- 每个组内订单都写同一份快照:`points_checked_at / points_balance /
|
||||
points_required_total / points_surplus / points_threshold / points_check_reason /
|
||||
points_check_message / points_check_detail`,审计动作 `huya:collab:recharge_check`。
|
||||
|
||||
**批量改状态**(`set_status_batch()`,接口 `POST /external-orders/status/batch`):
|
||||
|
||||
- 勾选多行一次切到**同一个**目标状态;**逐行 SAVEPOINT 隔离**,
|
||||
某一行前置校验没过(例如没主页截图进不了「已确认绑定」)只记在该行的 `message` 里,
|
||||
不影响其它行(同 §5.1 导入的做法);一次上限 `PROBE_BATCH_MAX=50`;
|
||||
- 勾选多行一次切到**同一个**目标状态;**逐行 SAVEPOINT 隔离**,某一行前置校验没过
|
||||
(例如资料不全进不了「待充值」)只记在该行的 `message` 里,不影响其它行;
|
||||
一次上限 `PROBE_BATCH_MAX=50`;
|
||||
- 批量接口**不接受** `recharged` / `points_error`;要落这两个状态请用充值核账接口;
|
||||
- 单行与批量走**同一个** `set_status()`,规则不会漂移;错误信息统一带上
|
||||
"要往前的话下一步是 X(也可以直接跳到更后面的状态)"。
|
||||
|
||||
@@ -270,8 +299,9 @@ unverified ──探针成功──▶ valid ──探针失败──▶ invalid
|
||||
| `invalid` | 探针失败(CK 过期/被踢) | "验证 CK"动作失败,`ck_check_message` 记原因 |
|
||||
| `disabled` | 人工停用(不想再用这个号) | `POST /api/huya/external-orders/{id}/ck/status`(**只能**改成 `disabled`/`unverified`,`valid`/`invalid` 归探针) |
|
||||
|
||||
**与业务状态解耦**:CK 失效**不自动**把业务行改成作废——已经绑定/充值的单子,
|
||||
CK 失效了业务上可能仍然有效。列表上只做**显式提示**(红色标签),由人决定怎么处理。
|
||||
**与业务状态解耦**:CK 失效**不自动**把业务行改回待补资料或作废 —— 已经待充值/已充值的单子,
|
||||
凭据过期不等于业务资料缺失。列表上只做**显式提示**(红色标签);充值核账会强制重验 CK,
|
||||
失败时整组保持原状态并报错,由人决定换 CK 还是停用。
|
||||
|
||||
### 4.3 防漂移(学 `docs/设计-账号全生命周期.md` §3.4.1 的教训)
|
||||
|
||||
@@ -366,6 +396,7 @@ CK 失效了业务上可能仍然有效。列表上只做**显式提示**(红
|
||||
| 店铺 | ✅ | **大按钮点选**;没有就点「新店」自定义,自动进字典 |
|
||||
| 外部 CK | ✅ | 贴进来即调 `POST /ck/preview` 预览 |
|
||||
| 礼包名 | ✅ | 从**礼包列表**里点选(= 用户购买的物品);列表平时用浏览器缓存,要更新点「强制刷新礼包」 |
|
||||
| 礼包所需积分 | — | 选中礼包时从积分中心价格自动带出,也可手工修正;核账时按 `Σ required_points` 计算 |
|
||||
| 主页截图 | ✅ | 至少 1 张,第一张作封面;绑定图**不要了**(绑了谁由探针读,见 §11.5) |
|
||||
| 负责人 | — | 默认 = 当前登录账号,不用选 |
|
||||
| 绑定斗鱼号 / 备注 | — | 备注可选;**绑定斗鱼号已从界面下线**(老数据在详情里只读展示) |
|
||||
@@ -374,14 +405,15 @@ CK 失效了业务上可能仍然有效。列表上只做**显式提示**(红
|
||||
(`ck_not_verified`)。所有校验都在落库**之前**做完,失败不留半行 —— 前端只是即时反馈,
|
||||
服务端才是最终关口(AGENTS §2)。
|
||||
|
||||
- **礼包来源**:`webActUI.getActPrizeList`(活动可兑换商品,只读、不落库;拉失败只提示
|
||||
`gifts_message`,不影响 CK 的有效性结论)。**SID 必须用工作台配置里的那个**
|
||||
(`huya_config.sid`,走 `resolve_gifts_sid(db)`)—— 见 §11.4 的真机定位:
|
||||
SID 就是活动 ID、会随活动轮换,写死默认值会出现「接口 200 但礼包列表空白」;
|
||||
- **记住最近选的礼包**:前端 localStorage(`huya.collab.lastGift`),同一个礼包连开几单不用重复选;
|
||||
- **礼包列表缓存**:前端 localStorage(`huya.collab.gifts`,存 `{at, gifts}`)—— 一个活动期间礼包清单基本不变,
|
||||
- **礼包来源**:`PlayMallUI.queryAllocation`(积分中心商品,只读、不落库;拉失败只提示
|
||||
`gifts_message`,不影响 CK 的有效性结论)。商品积分取 `tag75.tag0.tag2`,与积分中心
|
||||
页面显示一致;不再依赖活动 SID。旧 `webActUI.getActPrizeList` 保留给精英宝典工作台的
|
||||
兑换链路,本模块不再调用;
|
||||
- **礼包名默认空白**(2026-10-18 用户要求):不再自动带上次选的礼包,避免没注意时建错单;
|
||||
想少点两下用「常用礼包」快捷按钮;
|
||||
- **礼包列表缓存**:前端 localStorage(`huya.collab.gifts.v2`,存 `{at, gifts}`)—— 一个活动期间礼包清单基本不变,
|
||||
贴 CK 时**不再每次都去虎牙拉**(`with_gifts=false`),要用最新库存点「强制刷新礼包」;
|
||||
缓存时间摆在礼包名下方,活动换了(SID 变了)就点一次强制刷新;
|
||||
缓存时间摆在礼包名下方,商品清单变了就点一次强制刷新;
|
||||
- **探针缓存**:同一份 CK 在 `PROBE_CACHE_TTL_SECONDS`(90 秒)内复用结论 ——
|
||||
"预览一次 + 提交校验一次"只打一次虎牙,别为了校验白白翻倍请求;
|
||||
- 粘贴导入**不受**这些必填项约束(Excel 里本来就可能没有 CK),它走 `require_verified=false`。
|
||||
@@ -486,7 +518,7 @@ CK 失效了业务上可能仍然有效。列表上只做**显式提示**(红
|
||||
### 7.1 共享视图 + 负责人
|
||||
|
||||
- 一张表,**所有登录用户看到同一份数据**(默认不按人过滤);
|
||||
- 默认排序:`待处理优先,再看 updated_at 倒序`;
|
||||
- 默认排序:按创建序号 `seq` 升序(老单在上、新单追加在后);表头可按订单号/店铺/负责人/状态/礼包/更新时间等白名单字段排序;
|
||||
- "我的单"是一个筛选器(`owner_id = 我`),不是权限边界。
|
||||
|
||||
### 7.2 并发保护(解决 Excel 覆盖痛点)
|
||||
@@ -539,7 +571,8 @@ CK 失效了业务上可能仍然有效。列表上只做**显式提示**(红
|
||||
| POST | `/api/huya/external-orders/{id}/verify` | `huya:collab:edit` | 验证这一行的 CK(只读探针,§5.2) |
|
||||
| POST | `/api/huya/external-orders/ck/preview` | `huya:collab:edit` | 粘贴 CK 后的即时预览(探针 + 拉活动礼包,**只读不写库**) |
|
||||
| POST | `/api/huya/external-orders/ck/verify` | `huya:collab:edit` | 批量验证 CK(探针,body `{ids: [...]}`,最多 50 条) |
|
||||
| POST | `/api/huya/external-orders/status/batch` | `huya:collab:edit` | 勾选多行切成同一个状态(逐行 SAVEPOINT 隔离,最多 50 条;§4.1) |
|
||||
| POST | `/api/huya/external-orders/status/batch` | `huya:collab:edit` | 勾选多行切成同一个状态(逐行 SAVEPOINT 隔离,最多 50 条;**不接受** `recharged` / `points_error`;§4.1) |
|
||||
| POST | `/api/huya/external-orders/recharge` | `huya:collab:edit` | **充值核账**:`{ids, threshold}`,按 `bind_game_account` 整组验证 CK + 积分,整组落 `recharged` / `points_error`(§4.1) |
|
||||
| POST | `/api/huya/external-orders/archive` | `huya:collab:edit` | 归档抢购成功订单:`ids` 单条/勾选,或 `archive_filtered=true` + 筛选条件按当前筛选批量;可带 `reason`,`expected_count` 校验数量(§4.4) |
|
||||
| POST | `/api/huya/external-orders/unarchive` | `huya:collab:edit` | 取消归档(`{ids: [...]}`),恢复回活跃台账 |
|
||||
| POST | `/api/huya/external-orders/activity/query` | `huya:collab:edit` | 勾选多行查积分 + 兑换记录(串行带间隔,每行写一条生命周期快照;§5.7) |
|
||||
@@ -578,14 +611,17 @@ CK 失效了业务上可能仍然有效。列表上只做**显式提示**(红
|
||||
- **图片列**:缩略图 + 张数,点击开大图(`Image.PreviewGroup`);
|
||||
- **状态**:**只展示当前状态 Tag**;行内不再放「→ 下一步」快捷按钮(2026-10-19),推进统一走详情抽屉或批量改状态;
|
||||
- **CK 状态**:Tag + 一键"验证";
|
||||
- **工具栏批量动作**(都要先勾选):批量验证 CK / 批量改状态 / 批量查积分·兑换 / 批量归档(仅全部选中行都是活跃 `done`)/ **导出 CK**(勾选几行导几行,写剪贴板;§11.8);
|
||||
- **工具栏批量动作**(都要先勾选):批量验证 CK / 批量改状态 / **充值核账** / 批量查积分·兑换 / 批量归档(仅全部选中行都是活跃 `done`)/ **导出 CK**(勾选几行导几行,写剪贴板;§11.8);
|
||||
- **归档入口**(2026-10-19,§4.4):筛选行右侧「查看归档」开关 + 已归档总数角标;活跃视图提供「批量归档」和(状态筛选为 `done` 时)「归档当前筛选结果(N)」;归档视图提供「批量取消归档」,写操作全部隐藏;
|
||||
- **顶部工具区固定两行**(2026-10-16 用户反馈「不要选中后两行」):
|
||||
第一行永远筛选 = 店铺 / 负责人 / 业务状态 / CK 状态 / 关键词(订单号、店铺、绑定账号、角色、虎牙号、礼包、备注)/ 显示已作废 / 查看归档;
|
||||
第二行永远动作 = 刷新 + 上面那些批量动作 + 粘贴导入 / 店铺管理 / 新建。
|
||||
**不要**用「筛选 + 动作放在同一个 `wrap` 里靠 `space-between` 排」那种写法 ——
|
||||
不勾选时两组挤成一行、勾选后按钮多了「(N)」就被顶到第二行,列表跟着往下跳;
|
||||
- 页头统计条:`全部 N / 待补资料 N / 待处理 N / 已确认绑定 N / 已充值 N / 已上脚本 N / 抢购成功 N / 抢购失败 N / CK 失效 N`,右上角是「实时同步」开关(可手动暂停;暂停后不建 WebSocket、不轮询,只能手动刷新);已归档总数显示在筛选行的「查看归档」开关旁(`done` / `failed` 的展示名 2026-10-16 由「已完成」/「兑换失败」改成「抢购成功」/「抢购失败」,枚举值与库里数据不变)。
|
||||
- 页头统计条:`全部 N / 待补资料 N / 待充值 N / 已充值 N / 已上脚本 N / 抢购成功 N / 抢购失败 N / 积分异常 N / CK 失效 N`。
|
||||
**卡片可点**:点状态卡筛到该状态、点「CK 失效」只筛 CK 状态、点「全部」清空两种筛选;
|
||||
当前筛选对应的卡片高亮,并自动滚到列表。右上角是「实时同步」开关(可手动暂停;暂停后不建 WebSocket、
|
||||
不轮询,只能手动刷新);已归档总数显示在筛选行的「查看归档」开关旁。
|
||||
|
||||
> 交互细节(2026-10-16 用户拍板):**店铺是点选按钮组**(列表里点单元格弹出同一组按钮,
|
||||
> 筛选条里也是),不是下拉;**新建时不用选负责人**——默认就是当前登录账号
|
||||
@@ -641,7 +677,7 @@ CK 失效了业务上可能仍然有效。列表上只做**显式提示**(红
|
||||
| — | 店铺怎么填(2026-10-16 用户拍板) | **点选按钮组**(不是下拉);允许"新店"自定义输入,后端自动登记进字典 |
|
||||
| — | 负责人默认值(同日拍板) | **默认 = 当前登录账号**,新建时不用选;要转单在列表/详情里改 |
|
||||
| — | 新建必填项(同日拍板) | **订单编号 / 店铺 / CK / 礼包名**必填;CK 必须探针通且读到绑定角色 |
|
||||
| — | 礼包来源(同日拍板) | 用这份 CK 现拉活动礼包(`getActPrizeList`),点选 + 记住上次选择 |
|
||||
| — | 礼包来源(2026-10-19 调整) | `PlayMallUI.queryAllocation` 积分中心商品,点选 + 记住上次选择;旧 `getActPrizeList` 保留给精英宝典工作台 |
|
||||
|
||||
> 决定 7 的后果:**本模块不 import 任何 `huya_tasks` / runner 代码**。
|
||||
> 以后要做「一键送进工作台」,那是一个**显式的**新动作(会创建 `HuyaAccount` 并写
|
||||
@@ -766,7 +802,10 @@ CK 失效了业务上可能仍然有效。列表上只做**显式提示**(红
|
||||
(`web&1.0&huya` 与我们的 `webh5&...` 结果一样),解析器也不是原因
|
||||
(`ActPrizeItem` 的 tag 映射与 huya-go 实测一致,`to_dict()["goods"]` 正常)。
|
||||
|
||||
处理:新增 `resolve_gifts_sid(db)` —— **优先读工作台配置 `huya_config.sid`**,
|
||||
> 2026-10-19 起协作台账已切换到 `PlayMallUI.queryAllocation`,不再依赖 SID;
|
||||
> 下面这段是旧 `getActPrizeList` 的排查记录,保留给精英宝典工作台参考。
|
||||
|
||||
处理:新增 `resolve_gifts_sid(db)` —— **优先读工作台配置 `huya_config.sid`**,
|
||||
读不到(没有配置行 / 不是数字)才回落到 `GIFTS_SID`;接口层
|
||||
`POST /external-orders/ck/preview` 注入 `db` 后把它传给 `preview_ck(sid=...)`。
|
||||
配置行不存在时**不建行**(预览是只读动作)。空列表的结论也改成人话:
|
||||
@@ -835,6 +874,8 @@ CK 失效了业务上可能仍然有效。列表上只做**显式提示**(红
|
||||
|
||||
### 11.7 2026-10-16 第四轮:状态机新口径 + 账号全生命周期
|
||||
|
||||
> 历史口径:本节的 `bound`(已确认绑定)已在 2026-10-19 第九轮删除,见 §11.12;保留原文用于追溯当时决策。
|
||||
|
||||
用户原话(这一轮的全部需求):
|
||||
"业务状态刷新一下,目前上传后都属于待处理"、
|
||||
"手动确认绑定角色信息和主页截图相同后,可以手动切换到已确认绑定"、
|
||||
@@ -981,6 +1022,31 @@ CK 失效了业务上可能仍然有效。列表上只做**显式提示**(红
|
||||
**验收口径**:默认列表/统计不含归档行;归档视图能按原有关键词与筛选搜到;归档行改任何东西都提示先取消归档;
|
||||
取消归档后回到原位置(业务状态未变),归档备注仍能在审计时间线里查到。
|
||||
|
||||
### 11.12 2026-10-19 第九轮:状态机重做 + 按绑定账号充值核账
|
||||
|
||||
需求原文:「去掉待处理和已确认绑定;客户资料齐了自动待充值;点已充值要服务端校验 CK 和积分;
|
||||
按 bind_game_account 整组核账,整组落已充值 / 积分异常;积分不足或多出阈值都算异常;阈值可改默认 100」。
|
||||
|
||||
| 面 | 落地 |
|
||||
| --- | --- |
|
||||
| 状态 | 删除 `pending` / `bound`;新增 `to_recharge`(待充值)、`points_error`(积分异常);`incomplete` 成为唯一入口 |
|
||||
| 自动推进 | `_maybe_advance_to_recharge()`:CK 有效 + 绑定账号 + 绑定角色 + 礼包名 + ≥1 张主页截图 → 自动 `incomplete → to_recharge`;创建/编辑/补图/验证 CK 都触发 |
|
||||
| 自动退回 | `_maybe_demote_missing_data()`:`to_recharge` / `points_error` 关键资料被清空 → 自动退回 `incomplete`;CK 失效不触发 |
|
||||
| 核账 | `check_recharge_groups()` + `POST /external-orders/recharge`:按精确 `bind_game_account` 分组;只统计 `to_recharge/recharged/points_error`;同 uid 只验一次 CK、只查一次积分;多 uid 积分合计 |
|
||||
| 判定 | `结余 = 积分合计 - Σ required_points`;`<0` → `points_error/shortage`;`>阈值` → `points_error/excess`;其余 → `recharged`;CK 失效/积分失败/积分缺失整组保持原状态 |
|
||||
| 字段 | 新增 `required_points` + `points_checked_at/points_balance/points_required_total/points_surplus/points_threshold/points_check_reason/points_check_message/points_check_detail` |
|
||||
| 迁移 | `20261019_0061`:加列、`status` 默认改 `incomplete`、旧 `pending/bound` 按资料是否齐全转 `to_recharge` 或 `incomplete`;降级把 `to_recharge → bound`、`points_error → recharged` |
|
||||
| 礼包来源 | 改用 `PlayMallUI.queryAllocation`(`tag75.tag0.tag2` 取积分,`tag13` 库存),不再依赖活动 SID;旧 `webActUI.getActPrizeList` 仅保留给精英宝典工作台 |
|
||||
| 前端 | 统计卡改为 全部/待补资料/待充值/已充值/已上脚本/抢购成功/抢购失败/积分异常/CK 失效,**可点击筛选并高亮**;工具栏新增「充值核账」;新建/补资料/详情增加「礼包所需积分」,选礼包自动带出;核账弹窗阈值默认 100 |
|
||||
| 审计 | 核账逐单写 `huya:collab:recharge_check`;自动推进/退回写 `huya:collab:status_auto`;主操作(create/update/image)先落审计,再追加自动状态,时间线因果顺序不再倒置 |
|
||||
|
||||
**三条边界**:
|
||||
|
||||
1. **不要用 uid 当分组键**:同一买家可能用多份 CK。分组只认探针读到的 `bind_game_account`;
|
||||
`bind_game_account` 为空的行保持/退回 `incomplete`,绝不回落到 uid。
|
||||
2. **不要让人工直写 `recharged` / `points_error`**:这两个状态必须由核账产生,否则积分快照与状态会各说各话。
|
||||
3. **换 CK 不等于资料缺失**:`set_ck()` 只重置 `ck_status`;核账会强制重验,若绑定账号变了整组报错,不会误落旧组。
|
||||
|
||||
---
|
||||
|
||||
## 12. 风险
|
||||
@@ -992,7 +1058,7 @@ CK 失效了业务上可能仍然有效。列表上只做**显式提示**(红
|
||||
| CK 被导出后外传(导出到剪贴板 = 凭据出门) | 独立权限点 `huya:collab:ck_export`(默认只给运营)+ 逐行审计(不含 CK 本体)+ 界面常驻警告;明文只在弹窗 state 里,关掉即清(§11.8) |
|
||||
| 积分 / 兑换记录查询被风控 | 同上:只手动触发(单行 + 勾选批量,串行带间隔),不做定时轮询(§5.7) |
|
||||
| 自动改状态误判(接口抖动 → 判成"抢购失败") | 三态判定:取不到数据一律 `unknown` 且不动状态;只有 `scripted` 的单才自动改;每次查询留快照,人工可回退(`rollback`) |
|
||||
| 活动换 ID(SID 过期)→ 礼包列表空白 | 礼包 SID 一律读 `huya_config.sid`(工作台「虎牙配置」可改,见 §11.4);空列表时结论直接提示去改 SID |
|
||||
| 积分中心 `queryAllocation` 拉不到 / 返回空 → 礼包列表空白 | 只影响「拉礼包」,不影响 CK 有效性;提示用户稍后点「强制刷新礼包」。旧 `getActPrizeList` 的 SID 过期问题只保留给精英宝典工作台(§11.4) |
|
||||
| 自由文本的"绑定斗鱼号"没法校验 | 先按文本存(Excel 里就是文本);能拿到结构化 uid 时补 `bind_douyu_uid` |
|
||||
| 图片越攒越多 | §6.4 孤儿清理脚本 + `file_assets` 台账已有 `size_bytes` 可统计 |
|
||||
| 分支 | 按 AGENTS §1,新功能应从 `main` 开 `feat/*`;开工前需确认当前分支与库迁移版本对齐 |
|
||||
|
||||
Reference in New Issue
Block a user