fix(claim): 修复后台手动关闭任务后领取链接未失效的缺陷
1. 鉴权层激活 CLAIM_TERMINAL_STATUSES：在 getClaimContext 中增加 task 状态校验，对 closed 与 expired 终态任务实施 410 拦截并自愈更新关联 Token； 2. 仓储层新增 closeClaimTokensByTaskId()：支持按 taskId 批量更新所有非 closed 状态的 Token 为 closed，彻底杜绝多 Token 或重发链接导致的历史活跃残留； 3. 后台关闭任务流程闭环：closeAdminTask 显式触发 closeClaimTokensByTaskId，确保任务关闭时关联领取链接立即失效； 4. 补充 CLAIM_TERMINAL_STATUSES 单元测试与完整排查分析方案文档。
This commit is contained in:
yml2213
@@ -0,0 +1,56 @@
|
||||
# 后台手动关闭任务后领取链接未失效问题分析与修复方案
|
||||
|
||||
## 1. 目标与登记信息 (Target & Registration)
|
||||
|
||||
- **目标 (Goal)**: 查明并修复在管理后台手动关闭任务（Fulfillment Task）后，该任务对应的领取链接（Claim Link）仍然可以正常打开并操作领取的 Bug。
|
||||
- **确信度 (Confidence Level)**: 100%（已完成代码修复并通过全量测试验证）。
|
||||
|
||||
### 状态登记表 (Status Matrix)
|
||||
|
||||
| 类别 | 内容描述 | 确信度 | 关联文件/模块 | 解决状态 |
|
||||
| :--- | :--- | :--- | :--- | :--- |
|
||||
| **已知 (Known)** | 1. 之前为了支持长期有效链接，在 `015_allow_permanent_claim_tokens.sql` 中将 `expired_at` 设为可为 NULL，默认 TTL 为 0 时 `expired_at = null`。 | 100% | [`015_allow_permanent_claim_tokens.sql`](file:///Users/yml/codes/order_site/apps/backend/src/db/migrations/015_allow_permanent_claim_tokens.sql), [`claim-service.ts`](file:///Users/yml/codes/order_site/apps/backend/src/services/claim/claim-service.ts) | 已确认机制 |
|
||||
| **已知 (Known)** | 2. 用户访问领取链接时调用的核心鉴权服务 `getClaimContext()` 完全没有校验 `task.task_status` 是否处于 `closed` 或 `expired`。 | 100% | [`kuaishou-cloud-claim-context.ts:58-73`](file:///Users/yml/codes/order_site/apps/backend/src/services/claim/kuaishou-cloud-claim-context.ts#L58-L73) | **已修复**：引入 `CLAIM_TERMINAL_STATUSES` 校验，终态直接 410 阻断并自动修复 Token 状态 |
|
||||
| **已知 (Known)** | 3. `kuaishou-cloud-claim-context.ts` 第 16 行虽定义了 `CLAIM_TERMINAL_STATUSES = new Set([TASK_STATUS.EXPIRED, TASK_STATUS.CLOSED])`，但在全代码库中**从未被实际调用**。 | 100% | [`kuaishou-cloud-claim-context.ts:16`](file:///Users/yml/codes/order_site/apps/backend/src/services/claim/kuaishou-cloud-claim-context.ts#L16) | **已修复**：在鉴权第一步激活生效 |
|
||||
| **已知 (Known)** | 4. 后台手动关闭任务 `closeAdminTask()` 在关闭 token 时，依赖 `task.primary_claim_token_id`。如果该任务重发过链接，LEFT JOIN 没有加 ORDER BY，会匹配到旧的 token ID，导致真正生效的新 token 仍然保持 `active` 状态。 | 100% | [`task-actions.ts:50-58`](file:///Users/yml/codes/order_site/apps/backend/src/services/admin/write/task-actions.ts#L50-L58), [`task-repo.ts:58-63`](file:///Users/yml/codes/order_site/apps/backend/src/repositories/task-repo.ts#L58-L63) | **已修复**：增加 `closeClaimTokensByTaskId(task.id, now)` 批量作废所有关联 Token |
|
||||
| **已知 (Known)** | 5. 提交 UID 接口 (`submitClaimUid`) 和提交发货接口 (`submitAffiliateDashClaim`) 虽最终依赖 `getClaimContext()`，但由于 `getClaimContext()` 放行，已关闭任务的订单仍能被提交发货或录入 UID。 | 100% | [`claims.ts`](file:///Users/yml/codes/order_site/apps/backend/src/routes/claims.ts), [`kuaishou-cloud-claim-service.ts`](file:///Users/yml/codes/order_site/apps/backend/src/services/claim/kuaishou-cloud-claim-service.ts) | **已修复**：底座鉴权拦截后，所有下游提交接口全部被阻断 |
|
||||
| **未知 (Unknown)** | 线上是否存在已有历史订单在被手动关闭后，打手或客户仍通过该链接提交了发货并造成资产损失的情况。 | 50% | 需查线上库 `claim_events` / `task_events` | 建议上线后核对线上数据 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 证据链分类与根因解构 (Evidence & Root Cause Analysis)
|
||||
|
||||
### 证据 A：链接鉴权层（Claim Context）缺少 Task 状态校验
|
||||
|
||||
- **代码链路**：
|
||||
客户访问 `http(s)://<domain>/#/claim/<token>` -> 前端调用 `GET /api/v1/claim/:token` -> 进入 [`getClaimContext(token)`](file:///Users/yml/codes/order_site/apps/backend/src/services/claim/kuaishou-cloud-claim-context.ts#L30)。
|
||||
- **代码缺陷**：
|
||||
原代码只校验了 `claimToken.status` 和 `claimToken.expired_at`，完全没有检查 `task.task_status`。
|
||||
- **为何改“有效期”后显现？**
|
||||
- 在改动前：所有链接均有绝对过期时间（例如 24 小时）。即使关闭任务时 token 未能及时置为 closed，链接到了 24 小时后也会自动被 `claimToken.expired_at` 拦截；
|
||||
- 改为“长期有效”后：`tokenTtlHours` 设置为 0，`claimToken.expired_at` 为 `NULL`。`claimToken.expired_at && ...` 永远为 `false`，一旦 token 的 status 没有被标记为 `closed`，链接永远不过期，永久可以打开！
|
||||
|
||||
### 证据 B：后台关闭任务（Close Admin Task）关闭 Token 机制存在单点失效隐患
|
||||
|
||||
- **代码链路**：
|
||||
管理员在后台点击“关闭任务” -> 调用 [`closeAdminTask(taskId)`](file:///Users/yml/codes/order_site/apps/backend/src/services/admin/write/task-actions.ts#L35)。
|
||||
- **代码缺陷**：
|
||||
原代码仅通过 `task.primary_claim_token_id` 单条更新。若存在重发链接产生的多条 Token，或者 JOIN 未取最新一条，真正生效的 Token 状态依然是 `active`。
|
||||
|
||||
---
|
||||
|
||||
## 3. 修复实施记录 (Changes Implemented)
|
||||
|
||||
1. **仓储层批量安全关闭 Token**：
|
||||
- 文件：[`apps/backend/src/repositories/claim-token-repo.ts`](file:///Users/yml/codes/order_site/apps/backend/src/repositories/claim-token-repo.ts)
|
||||
- 新增 `closeClaimTokensByTaskId(taskId, closedAt)`，原子更新该任务名下所有非 closed 的 Token。
|
||||
2. **后台关闭任务流程闭环**：
|
||||
- 文件：[`apps/backend/src/services/admin/write/task-actions.ts`](file:///Users/yml/codes/order_site/apps/backend/src/services/admin/write/task-actions.ts)
|
||||
- 在 `closeAdminTask()` 中调用 `closeClaimTokensByTaskId(task.id, now)`，确保任务关闭时关联 Token 全部失效。
|
||||
3. **鉴权端终态拦截与自愈**：
|
||||
- 文件：[`apps/backend/src/services/claim/kuaishou-cloud-claim-context.ts`](file:///Users/yml/codes/order_site/apps/backend/src/services/claim/kuaishou-cloud-claim-context.ts)
|
||||
- 激活 `CLAIM_TERMINAL_STATUSES`：当任务处于 `closed` 或 `expired` 状态时，抛出 `410`（`claim_task_closed` / `claim_token_expired`，文案“任务已关闭，领取链接已失效”），并自愈修正 Token 状态。
|
||||
4. **单元测试与全量回归**：
|
||||
- 新增测试：[`apps/backend/src/services/claim/kuaishou-cloud-claim-context.test.ts`](file:///Users/yml/codes/order_site/apps/backend/src/services/claim/kuaishou-cloud-claim-context.test.ts)
|
||||
- 后端 501 个测试全部通过（498 pass, 0 fail, 3 skip）。
|
||||
- 前端 54 个测试全部通过。
|
||||
Reference in New Issue
Block a user