From c115f5e94419ca59299eb9b3413af4b3bab4d294 Mon Sep 17 00:00:00 2001 From: yml2213 Date: Sun, 20 Sep 2026 14:05:14 +0800 Subject: [PATCH] =?UTF-8?q?fix(claim):=20=E4=BF=AE=E5=A4=8D=E5=90=8E?= =?UTF-8?q?=E5=8F=B0=E6=89=8B=E5=8A=A8=E5=85=B3=E9=97=AD=E4=BB=BB=E5=8A=A1?= =?UTF-8?q?=E5=90=8E=E9=A2=86=E5=8F=96=E9=93=BE=E6=8E=A5=E6=9C=AA=E5=A4=B1?= =?UTF-8?q?=E6=95=88=E7=9A=84=E7=BC=BA=E9=99=B7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. 鉴权层激活 CLAIM_TERMINAL_STATUSES：在 getClaimContext 中增加 task 状态校验，对 closed 与 expired 终态任务实施 410 拦截并自愈更新关联 Token； 2. 仓储层新增 closeClaimTokensByTaskId()：支持按 taskId 批量更新所有非 closed 状态的 Token 为 closed，彻底杜绝多 Token 或重发链接导致的历史活跃残留； 3. 后台关闭任务流程闭环：closeAdminTask 显式触发 closeClaimTokensByTaskId，确保任务关闭时关联领取链接立即失效； 4. 补充 CLAIM_TERMINAL_STATUSES 单元测试与完整排查分析方案文档。 --- .../src/repositories/claim-token-repo.ts | 19 +++++++ .../src/services/admin/write/task-actions.ts | 7 ++- .../kuaishou-cloud-claim-context.test.ts | 12 ++++ .../claim/kuaishou-cloud-claim-context.ts | 40 +++++++++++-- ...动关闭任务链接未失效问题排查与修复方案.md | 56 +++++++++++++++++++ 5 files changed, 129 insertions(+), 5 deletions(-) create mode 100644 apps/backend/src/services/claim/kuaishou-cloud-claim-context.test.ts create mode 100644 docs/履约配置/后台手动关闭任务链接未失效问题排查与修复方案.md diff --git a/apps/backend/src/repositories/claim-token-repo.ts b/apps/backend/src/repositories/claim-token-repo.ts index 6f475ad3..d119ec41 100644 --- a/apps/backend/src/repositories/claim-token-repo.ts +++ b/apps/backend/src/repositories/claim-token-repo.ts @@ -127,3 +127,22 @@ export async function updateClaimToken( return result.rows[0] || null } + +export async function closeClaimTokensByTaskId( + taskId: number | string, + closedAt: string = new Date().toISOString(), +): Promise { + const result = await query( + ` + UPDATE claim_tokens + SET + status = 'closed', + expired_at = $1, + updated_at = $1 + WHERE task_id = $2 AND status != 'closed' + RETURNING * + `, + [closedAt, Number(taskId)], + ) + return result.rows +} diff --git a/apps/backend/src/services/admin/write/task-actions.ts b/apps/backend/src/services/admin/write/task-actions.ts index de4ff934..f952ef91 100644 --- a/apps/backend/src/services/admin/write/task-actions.ts +++ b/apps/backend/src/services/admin/write/task-actions.ts @@ -1,4 +1,7 @@ -import { updateClaimToken } from '../../../repositories/claim-token-repo.js' +import { + closeClaimTokensByTaskId, + updateClaimToken, +} from '../../../repositories/claim-token-repo.js' import { updateTask } from '../../../repositories/task-repo.js' import { createTaskEvent } from '../../../repositories/task-event-repo.js' import { createTaskClaimToken, buildClaimUrl } from '../../claim/claim-service.js' @@ -57,6 +60,8 @@ export async function closeAdminTask( }) } + await closeClaimTokensByTaskId(task.id, now) + const updatedTask = await updateTask(task.id, { task_status: TASK_STATUS.CLOSED, delivery_status: 'closed', diff --git a/apps/backend/src/services/claim/kuaishou-cloud-claim-context.test.ts b/apps/backend/src/services/claim/kuaishou-cloud-claim-context.test.ts new file mode 100644 index 00000000..4e0a4931 --- /dev/null +++ b/apps/backend/src/services/claim/kuaishou-cloud-claim-context.test.ts @@ -0,0 +1,12 @@ +import assert from 'node:assert/strict' +import test from 'node:test' + +import { CLAIM_TERMINAL_STATUSES } from './kuaishou-cloud-claim-context.js' +import { TASK_STATUS } from '../../domain/task-status.js' + +test('CLAIM_TERMINAL_STATUSES 包含 closed 与 expired 状态', () => { + assert.equal(CLAIM_TERMINAL_STATUSES.has(TASK_STATUS.CLOSED), true) + assert.equal(CLAIM_TERMINAL_STATUSES.has(TASK_STATUS.EXPIRED), true) + assert.equal(CLAIM_TERMINAL_STATUSES.has(TASK_STATUS.PAID), false) + assert.equal(CLAIM_TERMINAL_STATUSES.has(TASK_STATUS.LINK_GENERATED), false) +}) diff --git a/apps/backend/src/services/claim/kuaishou-cloud-claim-context.ts b/apps/backend/src/services/claim/kuaishou-cloud-claim-context.ts index 17ddeb56..c445a338 100644 --- a/apps/backend/src/services/claim/kuaishou-cloud-claim-context.ts +++ b/apps/backend/src/services/claim/kuaishou-cloud-claim-context.ts @@ -13,7 +13,7 @@ import { normalizeAffiliateDashFlow } from '../fulfillment/affiliate-dash/index. import type { ClaimTokenRow, OrderItemRow, OrderRow, TaskRow } from '../../types/repository/rows.js' import type { JsonObject } from '../../types/json.js' -export const CLAIM_TERMINAL_STATUSES = new Set([TASK_STATUS.EXPIRED, TASK_STATUS.CLOSED]) +export const CLAIM_TERMINAL_STATUSES = new Set([TASK_STATUS.EXPIRED, TASK_STATUS.CLOSED]) const RETIRED_CHANNEL_MESSAGE: Record = { kuaishou_feifei: '飞飞履约渠道已下线，本链接仅可查看历史信息，无法继续领取', @@ -55,13 +55,45 @@ export async function getClaimContext(token: unknown) { }) } - if (claimToken.status !== 'active') { - throw createHttpError('领取链接当前不可用', { + if (CLAIM_TERMINAL_STATUSES.has(task.task_status)) { + if (claimToken.status === 'active') { + await updateClaimToken(claimToken.id, { + status: task.task_status === TASK_STATUS.EXPIRED ? 'expired' : 'closed', + expired_at: nowIso(), + updated_at: nowIso(), + }).catch(() => null) + } + + const isExpired = task.task_status === TASK_STATUS.EXPIRED + throw createHttpError(isExpired ? '领取链接已过期' : '任务已关闭，领取链接已失效', { statusCode: 410, - errorCode: 'claim_token_inactive', + errorCode: isExpired ? 'claim_token_expired' : 'claim_task_closed', + context: { + claimToken: { + ...claimToken, + status: isExpired ? 'expired' : 'closed', + }, + task, + }, }) } + if (claimToken.status !== 'active') { + const isClosed = claimToken.status === 'closed' + const isExpired = claimToken.status === 'expired' + throw createHttpError( + isClosed ? '任务已关闭，领取链接已失效' : isExpired ? '领取链接已过期' : '领取链接当前不可用', + { + statusCode: 410, + errorCode: isClosed + ? 'claim_task_closed' + : isExpired + ? 'claim_token_expired' + : 'claim_token_inactive', + }, + ) + } + if (claimToken.expired_at && new Date(claimToken.expired_at).getTime() <= Date.now()) { const expiredContext = await expireClaimContext(claimToken, task) diff --git a/docs/履约配置/后台手动关闭任务链接未失效问题排查与修复方案.md b/docs/履约配置/后台手动关闭任务链接未失效问题排查与修复方案.md new file mode 100644 index 00000000..0f2064d1 --- /dev/null +++ b/docs/履约配置/后台手动关闭任务链接未失效问题排查与修复方案.md @@ -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):///#/claim/` -> 前端调用 `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 个测试全部通过。