feat(rock): 发货记录表格新增时间与备注列并支持上报失效联动
- 做了什么： 1. 数据库新增 013_rock_tokens_remark.sql 迁移，rock_tokens 表补充 remark 字段并在 ListTokens 中支持备注模糊检索； 2. 后端扩展 UpdateTokenRemark、MarkTokenAbnormal 接口，同时优化 ResetMismatchToken 支持 mismatch 与 abnormal 状态的解冻重置； 3. 前端 RockTokenTable 新增「流转时间」列（入库/绑错/发货/绑定/提货）与「备注」列（TokenRemarkCell 浮窗快捷预设选择与自定义输入）； 4. 快捷选择「已上报」或点击「上报失效」自动将链接标记为 abnormal 作废，从可用库存池中剔除，防止被新订单领走； 5. 优化操作列与顶部筛选栏：mismatch 增加「上报失效」与警示重置；abnormal 状态明确显示已失效并提供强制恢复；筛选栏新增「已上报失效」Tab。 - 为什么： 解决绑定错误上报 0868 上游后无法记录备注、且原「解冻重置」容易误将已作废卡密放回可用库存池导致后续订单报错的问题。 - 验证方式： 1. 后端单元测试 TestRockService_TokenRemarkAndAbnormal 与 TestRock 测试集通过； 2. make fmt、go vet 通过； 3. 前端 oxlint 检查通过 (0 errors, 0 warnings)，npm run build 生产构建通过。
This commit is contained in:
yml2213
@@ -0,0 +1,89 @@
|
||||
# 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. [x] 现状分析与数据库/代码核查完成。
|
||||
2. [x] 编写数据库迁移 `013_rock_tokens_remark.sql` 并更新 Go 结构体 `model.RockToken`。
|
||||
3. [x] 扩展后端 service 与 handler：实现 Token 备注与状态流转接口，编写对应单元测试并通过验证。
|
||||
4. [x] 前端类型与 API 定义补充 (`frontend/src/api/index.ts`)。
|
||||
5. [x] 前端组件实现：
|
||||
- `tokenColumns.tsx` 增加流转时间列、备注列（含快速设置交互）、优化操作列。
|
||||
- `TokenRemarkCell.tsx` 实现一键快捷选择（上报错误失效等）与自定义备注输入。
|
||||
- `RockTokenFilterBar.tsx` 增加 `abnormal` 已上报失效状态筛选。
|
||||
6. [x] 完整回归验证：
|
||||
- 前端构建 `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` | 全部通过 |
|
||||
|
||||
Reference in New Issue
Block a user