affiliate_dash/docs/Rock发货记录时间与备注及失效状态优化方案.md

Rock发货记录时间与备注及失效状态优化方案

日期：2026-10-08
任务背景：Rock (0666.pro) 发货平台看板中，提货记录缺少时间追踪与运营备注；当发生 UID 绑定错误（mismatch）并上报给上游（0868/0666 客服）后，该链接实际已废弃无法使用，但原有仅有的「解冻重置」会将坏卡重新释放回可用库存池，存在严重业务安全隐患。

---

一、进度与证据分类登记

1.1 已知事实 (Known Facts)

1. 现有数据结构与表定义：
   • 源码位置：backend/internal/model/rock.go、backend/internal/database/migrations/012_rock_fulfillment.sql
   • rock_tokens 表已有字段：id, upstream_token_id, redeem_code, status, assigned_order_no, expected_uid, actual_role_id, actual_role_name, mismatch_at, mismatch_reason, claimed_at, bound_at, redeemed_at, created_at, updated_at。
   • 确信度：100%（源码与迁移文件已确认）。
2. 状态机支持情况：
   • model.RockStatusAbnormal = "abnormal" 已经定义（注释为“异常/作废”），并在 rock_assign.go:50-62、rock_service.go:215 等处被处理（当 status 为 abnormal 时，领号逻辑会直接拦截阻断该订单再次分配此号）。
   • 当前缺少从前端直接将 Token 标记为 abnormal / 已上报失效的流转入口。
   • 确信度：100%（源码已确认）。
3. 表格现有列：
   • 源码位置：frontend/src/pages/platformRock/tokenColumns.tsx
   • 现有列包含：0666 编号 / 提取码, 规格与适用范围, 库存状态, 关联业务工单, 预期 UID vs 扫码角色, 发货结果图片, 操作。
   • 缺乏：时间列（入库时间、绑错时间、绑定/发货时间）以及备注列。
   • 确信度：100%（源码与截图已确认）。
4. 原有「解冻重置」的逻辑与缺陷：
   • 源码位置：backend/internal/service/rock_recover.go:101-127（ResetMismatchToken）
   • 现有逻辑：只要是 mismatch 状态，调用 resetToken 会直接无条件将 status 更新为 available，清空 assigned_order_no 和 expected_uid。
   • 业务缺陷：若运营人员已向 0868 上游反馈坏卡/上报问题，该链接在上游已被处理或作废，一旦客服误点“解冻重置”，该废卡被重新分给后续新订单，导致下一单继续报错。
   • 确信度：100%（源码与业务逻辑已确认）。

1.2 目标 (Goals)

1. 数据库与数据模型升级：
   • 在 rock_tokens 表增加 remark 字段（TEXT / VARCHAR(255)）。
   • 新增安全数据库迁移脚本（013_rock_tokens_remark.sql），自动为现有表增列。
   • 在 model.RockToken 补充 Remark string json:"remark" 字段。
2. 后端 API 扩展：
   • 提供 Token 备注更新与状态联动接口：POST /api/platform/rock/tokens/:id/remark。
   • 支持设置备注（例如“已上报上游”、“卡密绑定错误已上报”、“买家填错UID”等），并支持可选传参 status（如置为 abnormal / 已失效作废）。
   • 提供针对已失效/作废的专门操作或优化现有 Reset 行为（若已上报失效，明确区分是作废还是强制重置）。
   • 搜索功能支持对备注 remark 进行模糊查询。
3. 前端表格重构 (tokenColumns.tsx & RockTokenTable.tsx)：
   • 新增「时间信息」列：
     • 入库时间（created_at）；
     • 关键节点流转时间（如 mismatch_at 绑错时间、bound_at 授权时间、redeemed_at 发货时间），带醒目标识。
   • 新增「备注」列：
     • 支持快捷选择标签（下拉/气泡快捷选填）：
       • 🔴 已上报上游 (作废失效)（自动设置备注并将状态置为失效 abnormal，阻断再次使用）；
       • ⚠️ 绑定错误 (已上报)（设置备注并将状态置为失效 abnormal）；
       • ✏️ 买家UID填错 (待核对)；
       • ⏳ 上报处理中；
       • 📝 自定义输入备注；
       • 🧹 清空备注。
     • 行内直观展示当前备注内容。
   • 优化「操作」列：
     • 对于 mismatch 状态：
       • 保留「修改 UID」（适用于买家扫对了但填错了）；
       • 新增一键「上报失效」（快捷将链接标记为已上报并作废，不再入库存池）；
       • 优化「解冻重置」的提示文案与门禁（警告不可将已上报上游的卡重置回库存）。
     • 对于 abnormal（已上报失效 / 作废）状态：
       • 展示「已作废 (不可用)」徽章，不再显示常规解冻重置；
       • 如确需误操作恢复，提供带高危确认的「强制恢复为可用」。
   • 优化筛选栏 (RockTokenFilterBar.tsx)：
     • 增加「已失效/已上报」（abnormal）筛选 Tab，方便运营检索所有上报废弃卡。

1.3 下一步执行计划 (Next Steps)

1. 现状分析与数据库/代码核查完成。
2. 编写数据库迁移 013_rock_tokens_remark.sql 并更新 Go 结构体 model.RockToken。
3. 扩展后端 service 与 handler：实现 Token 备注与状态流转接口，编写对应单元测试并通过验证。
4. 前端类型与 API 定义补充 (frontend/src/api/index.ts)。
5. 前端组件实现：
   • tokenColumns.tsx 增加流转时间列、备注列（含快速设置交互）、优化操作列。
   • TokenRemarkCell.tsx 实现一键快捷选择（上报错误失效等）与自定义备注输入。
   • RockTokenFilterBar.tsx 增加 abnormal 已上报失效状态筛选。
6. 完整回归验证：
   • 前端构建 npm run build、代码规范 oxlint 全部通过 (0 errors, 0 warnings)。
   • 后端代码格式化 make fmt、类型检查 go vet 全部通过。
   • 单元测试 go test -count=1 ./internal/service -run TestRock 全部通过。

---

二、验收与验证结果清单

检查项	验证命令 / 方式	结果
数据库增列与迁移	检查 013_rock_tokens_remark.sql 与 model.RockToken	通过，新增 remark 字段
接口联通与流转逻辑	运行单测 TestRockService_TokenRemarkAndAbnormal	通过，支持备注更新、一键标记 abnormal、模糊搜索备注及异常重置
前端 TypeScript 编译	npm run build (tsc -b && vite build)	通过 (0 errors)
前端代码质量检查	npm run lint (oxlint)	通过 (0 errors, 0 warnings)
后端代码格式与单测	make fmt && go vet ./... && go test -count=1 ./internal/service -run TestRock	全部通过