feat(douyin-mashida): 皮肤自动发货(按内部 SKU 分流 + 领取链接 + 买家领取接口)
抖音码速达的皮肤类商品改为「自动发货 + 领取链接」:买家不用输订单号,点链接直接领。
**分流(按内部 SKU)**
- 平台闸门放行 `provider='douyin_mashida' && platform='doudian'`,走**独立分支**
(原有 91/快手路径一行未动,避免外溢)
- 判据:内部 SKU(`sku_order_list[].code`,即 order_items.sku_code)命中权威表
`AFFILIATE_DASH_SKU_MAPPING` → 新执行器 `douyin_mashida_skin`;未命中 → `manual_dispatch`
- 皮肤判定与商品图同源(都用那张权威表),保证「能路由 ⇒ 有图」
- 履约路由新增 `internal_sku` 匹配维度(`rules[].internalSku`,NFKC+去空白+小写,exact/contains);
旧规则缺 `matchField` 时默认 `product_name`,**归一化/优先级/回退顺序完全不变**
**执行器与领取 token**
- 新增 `douyin-mashida-skin-executor`:建 claim token、置 `link_generated/pending_claim`,
`resolveDeliveryLink` 返回本站路径式领取链接;注册进 registry、planner 分支、
bootstrap 种子 profile(`抖音皮肤自动发货`);进 `ROUTABLE_EXECUTOR_KEYS`
- token 粒度 = 一个履约单元一个(`claim_tokens.task_id` 唯一);一单多项时
cert_link/买家消息取 task id 最小的那个并告警
**cert_link 与发消息**
- 皮肤订单且该订单项已有 token 且配了 `claimLinkBase` → `cert_link = claimLinkBase/token`;
其它情况一律用 `certLink`(老行为不变)
- 领取链接**只认** `claimLinkBase`,绝不回退 `buildClaimUrl`/`orders.claimBaseUrl`
(那是 hash 形式的打手领取页,语义不同)
- 付款建单+发券成功后按 `messageTemplate`(`{link}/{sku}/{orderNo}/{productTitle}`)
经 `order.message` 发给买家;best-effort,失败只记 warn
**买家领取接口**
- `GET/POST /api/v1/claim-skin/:token`(限流、公开);详情含内部SKU/引流标题/商品图/
数量/金额/支付时间/动态表单字段;token 失效给明确 errorCode(404/410/409),不打 500
- 提交账号:先核销平台券再落记录(避免「记账了但券没核销」的资损),已提交幂等
**隐私**
- 买家游戏账号落 `fulfillment_tasks.claim_submission_json`(迁移 096),
**不进** `work_orders.material_json`(那是发给打手的素材);详情接口不返回券码明文/手机号/地址/open_id
This commit is contained in:
@@ -1,7 +1,7 @@
|
||||
import assert from 'node:assert/strict'
|
||||
import test from 'node:test'
|
||||
|
||||
import { resolveClaimTokenExpiration } from './claim-service.js'
|
||||
import { resolveClaimTokenExpiration, buildSkinClaimUrl } from './claim-service.js'
|
||||
|
||||
test('领取链接默认可配置为长期有效', () => {
|
||||
assert.equal(resolveClaimTokenExpiration('2026-08-11T08:00:00.000Z', 0), null)
|
||||
@@ -13,3 +13,25 @@ test('领取链接保留正整数小时的限时配置能力', () => {
|
||||
'2026-08-12T08:00:00.000Z',
|
||||
)
|
||||
})
|
||||
|
||||
test('皮肤领取链接只拼传入基址(去尾斜杠),不读全局 claimBaseUrl', () => {
|
||||
assert.equal(
|
||||
buildSkinClaimUrl('https://x.ngrok-free.app/claim', 'AbC123'),
|
||||
'https://x.ngrok-free.app/claim/AbC123',
|
||||
)
|
||||
assert.equal(
|
||||
buildSkinClaimUrl('https://x.ngrok-free.app/claim/', 'AbC123'),
|
||||
'https://x.ngrok-free.app/claim/AbC123',
|
||||
)
|
||||
assert.equal(
|
||||
buildSkinClaimUrl('https://x.ngrok-free.app', 'AbC123'),
|
||||
'https://x.ngrok-free.app/AbC123',
|
||||
)
|
||||
})
|
||||
|
||||
test('皮肤领取链接基址/token 缺失返回空串(由调用方决定不发链接、不发消息)', () => {
|
||||
assert.equal(buildSkinClaimUrl('', 'AbC123'), '')
|
||||
assert.equal(buildSkinClaimUrl(undefined, 'AbC123'), '')
|
||||
assert.equal(buildSkinClaimUrl('https://x/claim', ''), '')
|
||||
assert.equal(buildSkinClaimUrl('https://x/claim', null), '')
|
||||
})
|
||||
|
||||
@@ -49,3 +49,23 @@ export function buildClaimUrl(token: string): string {
|
||||
const baseUrl = String(runtimeConfig.orders.claimBaseUrl || '').trim()
|
||||
return baseUrl ? `${baseUrl.replace(/\/+$/, '')}/${token}` : token
|
||||
}
|
||||
|
||||
/**
|
||||
* 「皮肤自动发货」领取链接:`${领取页基址去尾斜杠}/${token}`。
|
||||
*
|
||||
* ⚠️ 与 `buildClaimUrl` 刻意分开,绝不互相回退:
|
||||
* `buildClaimUrl` 读 `runtimeConfig.orders.claimBaseUrl`,默认值是**hash 形式**的打手领取页
|
||||
* (`http://127.0.0.1:5173/#/claim`,会走游戏 UID 绑定那套流程);皮肤买家页是**路径式**独立页面
|
||||
* (`/claim/:token`),基址只能来自抖音配置的 `claimLinkBase`。
|
||||
* 基址或 token 缺失时返回空串,由调用方决定「不生成链接 / 不发消息」,不猜、不回退。
|
||||
*/
|
||||
export function buildSkinClaimUrl(baseUrl: unknown, token: unknown): string {
|
||||
const base = String(baseUrl || '')
|
||||
.trim()
|
||||
.replace(/\/+$/, '')
|
||||
const normalizedToken = String(token || '').trim()
|
||||
if (!base || !normalizedToken) {
|
||||
return ''
|
||||
}
|
||||
return `${base}/${normalizedToken}`
|
||||
}
|
||||
|
||||
@@ -0,0 +1,249 @@
|
||||
import assert from 'node:assert/strict'
|
||||
import test from 'node:test'
|
||||
|
||||
import {
|
||||
assertValidSkinGameAccount,
|
||||
buildSkinClaimDetailPayload,
|
||||
normalizeSkinGameAccount,
|
||||
parseSkinClaimSubmission,
|
||||
resolveSkinClaimOrderNo,
|
||||
resolveSkinClaimStatus,
|
||||
resolveSkinClaimTokenStatus,
|
||||
SKIN_CLAIM_FIELDS,
|
||||
SKIN_GAME_ACCOUNT_MAX_LENGTH,
|
||||
} from './claim-skin-service.js'
|
||||
import { buildMessageSuccessPayload } from '../../utils/http.js'
|
||||
import type { OrderItemRow, OrderRow, TaskRow } from '../../types/repository/rows.js'
|
||||
|
||||
const DOUYIN_SKIN_TITLE = '【测试专用】和平精英皮肤小店入口出售返场吃鸡皮肤浪漫天命专用'
|
||||
|
||||
function createOrder(overrides: Partial<OrderRow> = {}): OrderRow {
|
||||
return {
|
||||
id: 1,
|
||||
provider: 'douyin_mashida',
|
||||
platform: 'doudian',
|
||||
shop_id: 'shop-1',
|
||||
shop_name: '测试小店',
|
||||
platform_order_id: '6930318258716179555',
|
||||
order_status: 'paid',
|
||||
pay_status: 'paid',
|
||||
buyer_id: 'open-id-should-not-leak',
|
||||
buyer_name: '买家张三',
|
||||
receiver_contact: '13800000000',
|
||||
total_amount: 100,
|
||||
currency: 'CNY',
|
||||
raw_payload_json: {},
|
||||
paid_at: '2026-10-09T05:18:20.000Z',
|
||||
created_at: '2026-10-09T05:18:20.000Z',
|
||||
updated_at: '2026-10-09T05:18:20.000Z',
|
||||
...overrides,
|
||||
}
|
||||
}
|
||||
|
||||
function createOrderItem(overrides: Partial<OrderItemRow> = {}): OrderItemRow {
|
||||
return {
|
||||
id: 11,
|
||||
order_id: 1,
|
||||
sku_code: '幸运币2个',
|
||||
sku_name: DOUYIN_SKIN_TITLE,
|
||||
quantity: 1,
|
||||
spec_json: {},
|
||||
item_snapshot_json: {
|
||||
douyinSubOrderId: '6930318258716179555',
|
||||
code: '幸运币2个',
|
||||
productName: DOUYIN_SKIN_TITLE,
|
||||
},
|
||||
...overrides,
|
||||
}
|
||||
}
|
||||
|
||||
function createTask(overrides: Partial<TaskRow> = {}): Partial<TaskRow> {
|
||||
return {
|
||||
id: 9,
|
||||
executor_key: 'douyin_mashida_skin',
|
||||
task_status: 'link_generated',
|
||||
user_action_status: 'pending_claim',
|
||||
claim_submission_json: {},
|
||||
...overrides,
|
||||
}
|
||||
}
|
||||
|
||||
test('领取页详情严格贴合前端契约字段', () => {
|
||||
const payload = buildSkinClaimDetailPayload({
|
||||
claimToken: { id: 1, token: 'AbC123', status: 'active', expired_at: null },
|
||||
task: createTask(),
|
||||
order: createOrder(),
|
||||
orderItem: createOrderItem(),
|
||||
})
|
||||
|
||||
assert.deepEqual(payload, {
|
||||
tokenStatus: 'active',
|
||||
flowType: 'douyin_mashida_skin',
|
||||
orderNo: '6930318258716179555',
|
||||
productName: '幸运币2个',
|
||||
productTitle: DOUYIN_SKIN_TITLE,
|
||||
imageUrl: '/images/products/lucky_coin_x2.webp',
|
||||
quantity: 1,
|
||||
amountFen: 100,
|
||||
paidAt: '2026-10-09T05:18:20.000Z',
|
||||
status: 'pending_claim',
|
||||
claimFields: [
|
||||
{
|
||||
key: 'gameAccount',
|
||||
label: '游戏账号 / 角色ID',
|
||||
placeholder: '请输入你的游戏账号(角色ID)',
|
||||
required: true,
|
||||
},
|
||||
],
|
||||
submittedGameAccount: '',
|
||||
})
|
||||
})
|
||||
|
||||
test('领取页详情不泄露券码/买家手机号/地址/open_id', () => {
|
||||
const payload = buildSkinClaimDetailPayload({
|
||||
claimToken: { id: 1, token: 'AbC123', status: 'active', expired_at: null },
|
||||
task: createTask(),
|
||||
order: createOrder(),
|
||||
orderItem: createOrderItem(),
|
||||
})
|
||||
|
||||
const serialized = JSON.stringify(payload)
|
||||
assert.equal(serialized.includes('open-id-should-not-leak'), false)
|
||||
assert.equal(serialized.includes('13800000000'), false)
|
||||
assert.equal(serialized.includes('买家张三'), false)
|
||||
assert.equal(serialized.includes('cert'), false)
|
||||
})
|
||||
|
||||
test('paidAt 经响应归一化后是北京时间字符串(前端直接展示)', () => {
|
||||
const response = buildMessageSuccessPayload(
|
||||
buildSkinClaimDetailPayload({
|
||||
claimToken: { id: 1, token: 'AbC123', status: 'active', expired_at: null },
|
||||
task: createTask(),
|
||||
order: createOrder(),
|
||||
orderItem: createOrderItem(),
|
||||
}),
|
||||
)
|
||||
|
||||
assert.equal(response.code, 0)
|
||||
assert.equal(response.message, 'success')
|
||||
assert.equal((response.data as { paidAt: string }).paidAt, '2026-10-09 13:18:20')
|
||||
})
|
||||
|
||||
test('已提交的任务返回 submitted + 买家填写的账号(token 显示 used 但仍可回看)', () => {
|
||||
const payload = buildSkinClaimDetailPayload({
|
||||
claimToken: {
|
||||
id: 1,
|
||||
token: 'AbC123',
|
||||
// 提交后 token 保持 status=active(否则 getClaimContext 会拦截),只标记 used_at/used_count
|
||||
status: 'active',
|
||||
expired_at: null,
|
||||
used_at: '2026-10-10T00:00:00.000Z',
|
||||
used_count: 1,
|
||||
max_use_count: 1,
|
||||
},
|
||||
task: createTask({
|
||||
task_status: 'claimed',
|
||||
claim_submission_json: { gameAccount: '123456', submittedAt: '2026-10-10T00:00:00.000Z' },
|
||||
}),
|
||||
order: createOrder(),
|
||||
orderItem: createOrderItem(),
|
||||
})
|
||||
|
||||
assert.equal(payload.status, 'submitted')
|
||||
assert.equal(payload.submittedGameAccount, '123456')
|
||||
assert.equal(payload.tokenStatus, 'used')
|
||||
})
|
||||
|
||||
test('resolveSkinClaimTokenStatus 覆盖 active/closed/revoked/expired/used', () => {
|
||||
const now = Date.parse('2026-10-10T00:00:00.000Z')
|
||||
|
||||
assert.equal(resolveSkinClaimTokenStatus({ status: 'active', expired_at: null }, now), 'active')
|
||||
assert.equal(resolveSkinClaimTokenStatus({ status: 'closed' }, now), 'closed')
|
||||
assert.equal(resolveSkinClaimTokenStatus({ status: 'revoked' }, now), 'revoked')
|
||||
assert.equal(resolveSkinClaimTokenStatus({ status: 'expired' }, now), 'expired')
|
||||
assert.equal(
|
||||
resolveSkinClaimTokenStatus({ status: 'active', expired_at: '2026-10-09T00:00:00.000Z' }, now),
|
||||
'expired',
|
||||
)
|
||||
assert.equal(
|
||||
resolveSkinClaimTokenStatus({ status: 'active', used_at: '2026-10-09T00:00:00.000Z' }, now),
|
||||
'used',
|
||||
)
|
||||
assert.equal(
|
||||
resolveSkinClaimTokenStatus(
|
||||
{ status: 'active', expired_at: null, max_use_count: 1, used_count: 1 },
|
||||
now,
|
||||
),
|
||||
'used',
|
||||
)
|
||||
})
|
||||
|
||||
test('parseSkinClaimSubmission 兼容 JSONB 对象与字符串,坏数据不抛错', () => {
|
||||
assert.deepEqual(
|
||||
parseSkinClaimSubmission({ claim_submission_json: { gameAccount: ' 123 ', submittedAt: 't' } }),
|
||||
{ gameAccount: '123', submittedAt: 't' },
|
||||
)
|
||||
assert.deepEqual(parseSkinClaimSubmission({ claim_submission_json: '{"gameAccount":"abc"}' }), {
|
||||
gameAccount: 'abc',
|
||||
submittedAt: '',
|
||||
})
|
||||
assert.deepEqual(parseSkinClaimSubmission({ claim_submission_json: '{invalid' }), {
|
||||
gameAccount: '',
|
||||
submittedAt: '',
|
||||
})
|
||||
assert.deepEqual(parseSkinClaimSubmission(null), { gameAccount: '', submittedAt: '' })
|
||||
})
|
||||
|
||||
test('resolveSkinClaimStatus 以提交记录为准,claimed 状态也算已领取', () => {
|
||||
assert.equal(resolveSkinClaimStatus(createTask()), 'pending_claim')
|
||||
assert.equal(resolveSkinClaimStatus(createTask({ task_status: 'claimed' })), 'submitted')
|
||||
assert.equal(
|
||||
resolveSkinClaimStatus(createTask({ claim_submission_json: { gameAccount: '123' } })),
|
||||
'submitted',
|
||||
)
|
||||
})
|
||||
|
||||
test('游戏账号归一化与校验', () => {
|
||||
assert.equal(normalizeSkinGameAccount(' 123456\u200B '), '123456')
|
||||
assert.equal(assertValidSkinGameAccount(' 123456 '), '123456')
|
||||
|
||||
assert.throws(
|
||||
() => assertValidSkinGameAccount(' '),
|
||||
(error: { errorCode?: string; statusCode?: number }) =>
|
||||
error.errorCode === 'claim_skin_game_account_required' && error.statusCode === 400,
|
||||
)
|
||||
|
||||
const tooLong = 'a'.repeat(SKIN_GAME_ACCOUNT_MAX_LENGTH + 1)
|
||||
assert.throws(
|
||||
() => assertValidSkinGameAccount(tooLong),
|
||||
(error: { errorCode?: string; statusCode?: number }) =>
|
||||
error.errorCode === 'claim_skin_game_account_too_long' && error.statusCode === 400,
|
||||
)
|
||||
|
||||
assert.equal('a'.repeat(SKIN_GAME_ACCOUNT_MAX_LENGTH).length, SKIN_GAME_ACCOUNT_MAX_LENGTH)
|
||||
})
|
||||
|
||||
test('resolveSkinClaimOrderNo 子订单号优先、父单兜底', () => {
|
||||
assert.equal(resolveSkinClaimOrderNo(createOrder(), createOrderItem()), '6930318258716179555')
|
||||
assert.equal(
|
||||
resolveSkinClaimOrderNo(
|
||||
createOrder({ platform_order_id: 'parent-1' }),
|
||||
createOrderItem({ item_snapshot_json: {} }),
|
||||
),
|
||||
'parent-1',
|
||||
)
|
||||
})
|
||||
|
||||
test('claimFields 每次都是副本,调用方修改不会污染常量', () => {
|
||||
const payload = buildSkinClaimDetailPayload({
|
||||
claimToken: { id: 1, token: 'AbC123', status: 'active', expired_at: null },
|
||||
task: createTask(),
|
||||
order: createOrder(),
|
||||
orderItem: createOrderItem(),
|
||||
})
|
||||
|
||||
const firstField = payload.claimFields[0]
|
||||
assert.ok(firstField)
|
||||
firstField.label = '被改了'
|
||||
assert.equal(SKIN_CLAIM_FIELDS[0]?.label, '游戏账号 / 角色ID')
|
||||
})
|
||||
@@ -0,0 +1,324 @@
|
||||
import { TASK_STATUS } from '../../domain/task-status.js'
|
||||
import { updateClaimToken } from '../../repositories/claim-token-repo.js'
|
||||
import { updateTask } from '../../repositories/task-repo.js'
|
||||
import { createHttpError } from '../../utils/http.js'
|
||||
import { logIntegration } from '../../utils/logger.js'
|
||||
import { normalizeFen } from '../../utils/money.js'
|
||||
import { nowIso } from '../../utils/time.js'
|
||||
import { getClaimContext } from './kuaishou-cloud-claim-context.js'
|
||||
import type { ClaimTokenRow, OrderItemRow, OrderRow, TaskRow } from '../../types/repository/rows.js'
|
||||
import { FULFILLMENT_EXECUTOR_KEYS } from '../fulfillment/executors/types.js'
|
||||
import { resolveProductImageUrl } from '../platforms/affiliate-dash/product-image.js'
|
||||
import { extractDouyinMashidaSubOrderId } from '../platforms/douyin-mashida/order-mapper.js'
|
||||
import { verifyCertificateForOrderItem } from '../redeem/certificate-service.js'
|
||||
|
||||
/**
|
||||
* 抖音码速达「皮肤自动发货」买家领取页(公开接口,无需登录)。
|
||||
*
|
||||
* 契约(前端并行开发中,字段名不可改):
|
||||
* - `GET /api/v1/claim-skin/:token`
|
||||
* - `POST /api/v1/claim-skin/:token` body `{ gameAccount }`
|
||||
*
|
||||
* 隐私红线:页面只暴露脱敏信息 —— 内部 SKU、引流标题、商品图、金额、支付时间、买家自己填的账号;
|
||||
* **不返回**券码明文、买家手机号/地址/open_id,也不把账号写进 work_orders.material_json
|
||||
* (落 `fulfillment_tasks.claim_submission_json`,见迁移 096)。
|
||||
*/
|
||||
|
||||
export const SKIN_CLAIM_FLOW_TYPE = 'douyin_mashida_skin'
|
||||
export const SKIN_GAME_ACCOUNT_FIELD_KEY = 'gameAccount'
|
||||
export const SKIN_GAME_ACCOUNT_MAX_LENGTH = 64
|
||||
export const SKIN_CLAIM_SUCCESS_MESSAGE = '领取成功,我们会尽快把物品发到你的账号'
|
||||
|
||||
export type SkinClaimTokenStatus = 'active' | 'closed' | 'revoked' | 'expired' | 'used'
|
||||
export type SkinClaimStatus = 'pending_claim' | 'submitted'
|
||||
|
||||
/** claim_tokens 的完整行(公共 Row 类型未列 used_* 字段,这里按仓储实际列补齐)。 */
|
||||
export type SkinClaimTokenLike = Partial<ClaimTokenRow> & {
|
||||
used_at?: string | null
|
||||
max_use_count?: number | null
|
||||
used_count?: number | null
|
||||
}
|
||||
|
||||
export type SkinClaimField = {
|
||||
key: string
|
||||
label: string
|
||||
placeholder: string
|
||||
required: boolean
|
||||
}
|
||||
|
||||
/** 领取页需要买家填的字段(目前只有游戏账号;前端按此渲染表单)。 */
|
||||
export const SKIN_CLAIM_FIELDS: SkinClaimField[] = [
|
||||
{
|
||||
key: SKIN_GAME_ACCOUNT_FIELD_KEY,
|
||||
label: '游戏账号 / 角色ID',
|
||||
placeholder: '请输入你的游戏账号(角色ID)',
|
||||
required: true,
|
||||
},
|
||||
]
|
||||
|
||||
export type SkinClaimSubmission = {
|
||||
gameAccount: string
|
||||
submittedAt: string
|
||||
}
|
||||
|
||||
export type SkinClaimDetailPayload = {
|
||||
tokenStatus: SkinClaimTokenStatus
|
||||
flowType: typeof SKIN_CLAIM_FLOW_TYPE
|
||||
orderNo: string
|
||||
productName: string
|
||||
productTitle: string
|
||||
imageUrl: string
|
||||
quantity: number
|
||||
amountFen: number
|
||||
paidAt: string | null
|
||||
status: SkinClaimStatus
|
||||
claimFields: SkinClaimField[]
|
||||
submittedGameAccount: string
|
||||
}
|
||||
|
||||
export type SkinClaimSubmitPayload = {
|
||||
status: SkinClaimStatus
|
||||
message: string
|
||||
}
|
||||
|
||||
/** token 状态归一化:DB 里的状态 + 过期/用尽信息 → 契约里的 5 个值。 */
|
||||
export function resolveSkinClaimTokenStatus(
|
||||
claimToken: SkinClaimTokenLike | null | undefined,
|
||||
nowMs: number = Date.now(),
|
||||
): SkinClaimTokenStatus {
|
||||
const status = String(claimToken?.status || '').trim()
|
||||
|
||||
if (status === 'closed' || status === 'revoked' || status === 'used') {
|
||||
return status
|
||||
}
|
||||
if (status === 'expired') {
|
||||
return 'expired'
|
||||
}
|
||||
|
||||
const expiredAt = claimToken?.expired_at ? Date.parse(String(claimToken.expired_at)) : NaN
|
||||
if (Number.isFinite(expiredAt) && expiredAt <= nowMs) {
|
||||
return 'expired'
|
||||
}
|
||||
|
||||
const usedAt = String(claimToken?.used_at || '').trim()
|
||||
const maxUseCount = Number(claimToken?.max_use_count || 0)
|
||||
const usedCount = Number(claimToken?.used_count || 0)
|
||||
if (usedAt || (maxUseCount > 0 && usedCount >= maxUseCount)) {
|
||||
return 'used'
|
||||
}
|
||||
|
||||
return 'active'
|
||||
}
|
||||
|
||||
/** 从任务的 claim_submission_json 读取买家提交内容(兼容 PG 返回对象或字符串)。 */
|
||||
export function parseSkinClaimSubmission(
|
||||
task: Partial<TaskRow> | null | undefined,
|
||||
): SkinClaimSubmission {
|
||||
const raw = task?.claim_submission_json
|
||||
let parsed: unknown = raw
|
||||
|
||||
if (typeof raw === 'string') {
|
||||
try {
|
||||
parsed = JSON.parse(raw)
|
||||
} catch {
|
||||
parsed = null
|
||||
}
|
||||
}
|
||||
|
||||
if (Object.prototype.toString.call(parsed) !== '[object Object]') {
|
||||
return { gameAccount: '', submittedAt: '' }
|
||||
}
|
||||
|
||||
const record = parsed as Record<string, unknown>
|
||||
return {
|
||||
gameAccount: String(record.gameAccount || '').trim(),
|
||||
submittedAt: String(record.submittedAt || '').trim(),
|
||||
}
|
||||
}
|
||||
|
||||
/** 待领取 / 已领取:以「任务上是否已有提交记录」为准,保证重复提交幂等。 */
|
||||
export function resolveSkinClaimStatus(task: Partial<TaskRow> | null | undefined): SkinClaimStatus {
|
||||
const submission = parseSkinClaimSubmission(task)
|
||||
if (submission.gameAccount || submission.submittedAt) {
|
||||
return 'submitted'
|
||||
}
|
||||
|
||||
const taskStatus = String(task?.task_status || '').trim()
|
||||
if (
|
||||
taskStatus === TASK_STATUS.CLAIMED ||
|
||||
taskStatus === TASK_STATUS.REDEEMED ||
|
||||
taskStatus === TASK_STATUS.COMPLETED
|
||||
) {
|
||||
return 'submitted'
|
||||
}
|
||||
|
||||
return 'pending_claim'
|
||||
}
|
||||
|
||||
/** 游戏账号归一化:去掉首尾空白与不可见字符。 */
|
||||
export function normalizeSkinGameAccount(value: unknown): string {
|
||||
return String(value ?? '')
|
||||
.replace(/[\u200B-\u200D\uFEFF]/g, '')
|
||||
.trim()
|
||||
}
|
||||
|
||||
/** 校验并返回可入库的游戏账号;不合法直接抛 4xx(不产生 500)。 */
|
||||
export function assertValidSkinGameAccount(value: unknown): string {
|
||||
const gameAccount = normalizeSkinGameAccount(value)
|
||||
|
||||
if (!gameAccount) {
|
||||
throw createHttpError('请填写游戏账号(角色ID)', {
|
||||
statusCode: 400,
|
||||
errorCode: 'claim_skin_game_account_required',
|
||||
})
|
||||
}
|
||||
if (gameAccount.length > SKIN_GAME_ACCOUNT_MAX_LENGTH) {
|
||||
throw createHttpError(`游戏账号过长(最多 ${SKIN_GAME_ACCOUNT_MAX_LENGTH} 个字符)`, {
|
||||
statusCode: 400,
|
||||
errorCode: 'claim_skin_game_account_too_long',
|
||||
context: { length: gameAccount.length, maxLength: SKIN_GAME_ACCOUNT_MAX_LENGTH },
|
||||
})
|
||||
}
|
||||
|
||||
return gameAccount
|
||||
}
|
||||
|
||||
/** 订单号口径与回执一致:子订单号优先、父单兜底。 */
|
||||
export function resolveSkinClaimOrderNo(order: OrderRow, orderItem: OrderItemRow): string {
|
||||
const subOrderId = extractDouyinMashidaSubOrderId(orderItem.item_snapshot_json)
|
||||
return String(subOrderId || order.platform_order_id || '').trim()
|
||||
}
|
||||
|
||||
/** 纯函数:把 token/任务/订单拼成领取页详情(便于单测,不碰数据库)。 */
|
||||
export function buildSkinClaimDetailPayload(input: {
|
||||
claimToken: SkinClaimTokenLike
|
||||
task: Partial<TaskRow>
|
||||
order: OrderRow
|
||||
orderItem: OrderItemRow
|
||||
nowMs?: number
|
||||
}): SkinClaimDetailPayload {
|
||||
const { claimToken, task, order, orderItem } = input
|
||||
const submission = parseSkinClaimSubmission(task)
|
||||
const productName = String(orderItem.sku_code || orderItem.sku_name || '').trim()
|
||||
const productTitle = String(orderItem.sku_name || productName).trim()
|
||||
|
||||
return {
|
||||
tokenStatus: resolveSkinClaimTokenStatus(claimToken, input.nowMs),
|
||||
flowType: SKIN_CLAIM_FLOW_TYPE,
|
||||
orderNo: resolveSkinClaimOrderNo(order, orderItem),
|
||||
productName,
|
||||
productTitle,
|
||||
imageUrl: resolveProductImageUrl(productName),
|
||||
quantity: Math.max(1, Number(orderItem.quantity || 1) || 1),
|
||||
amountFen: normalizeFen(order.total_amount),
|
||||
paidAt: order.paid_at || null,
|
||||
status: resolveSkinClaimStatus(task),
|
||||
claimFields: SKIN_CLAIM_FIELDS.map((field) => ({ ...field })),
|
||||
submittedGameAccount: submission.gameAccount,
|
||||
}
|
||||
}
|
||||
|
||||
function assertSkinTask(task: Partial<TaskRow>): TaskRow {
|
||||
if (String(task.executor_key || '').trim() !== FULFILLMENT_EXECUTOR_KEYS.DOUYIN_MASHIDA_SKIN) {
|
||||
throw createHttpError('该领取链接不是皮肤自动发货订单', {
|
||||
statusCode: 409,
|
||||
errorCode: 'claim_skin_task_invalid',
|
||||
context: { taskId: task.id, executorKey: task.executor_key || '' },
|
||||
})
|
||||
}
|
||||
|
||||
return task as TaskRow
|
||||
}
|
||||
|
||||
/** `GET /api/v1/claim-skin/:token`:领取页详情(token 失效/过期/关闭由 getClaimContext 抛明确 4xx)。 */
|
||||
export async function getSkinClaimDetail(token: unknown): Promise<SkinClaimDetailPayload> {
|
||||
const context = await getClaimContext(token)
|
||||
assertSkinTask(context.task)
|
||||
|
||||
return buildSkinClaimDetailPayload({
|
||||
claimToken: context.claimToken,
|
||||
task: context.task,
|
||||
order: context.order,
|
||||
orderItem: context.orderItem,
|
||||
})
|
||||
}
|
||||
|
||||
/**
|
||||
* `POST /api/v1/claim-skin/:token`:提交游戏账号 + 核销平台券。
|
||||
*
|
||||
* 幂等:已有提交记录直接返回「已领取」,不重复核销、不报错。
|
||||
*/
|
||||
export async function submitSkinClaim(
|
||||
token: unknown,
|
||||
payload: { gameAccount?: unknown } = {},
|
||||
): Promise<SkinClaimSubmitPayload> {
|
||||
const context = await getClaimContext(token)
|
||||
const task = assertSkinTask(context.task)
|
||||
|
||||
if (parseSkinClaimSubmission(task).gameAccount) {
|
||||
logIntegration('[claim-skin]', '重复提交已忽略(任务已领取)', {
|
||||
taskId: task.id,
|
||||
platformOrderId: task.platform_order_id,
|
||||
})
|
||||
return { status: 'submitted', message: SKIN_CLAIM_SUCCESS_MESSAGE }
|
||||
}
|
||||
|
||||
const gameAccount = assertValidSkinGameAccount(payload.gameAccount)
|
||||
|
||||
// 先核销平台券(verifyCertificate 自带幂等:本地已核销直接返回);
|
||||
// 核销失败不落提交记录,买家可重试,避免「我们记了已领取但平台券没核销」的资损。
|
||||
await verifyCertificateForOrderItem({ order: context.order, orderItem: context.orderItem })
|
||||
|
||||
const now = nowIso()
|
||||
const updatedTask = await updateTask(task.id, {
|
||||
task_status: TASK_STATUS.CLAIMED,
|
||||
user_action_status: 'not_required',
|
||||
claimed_at: task.claimed_at || now,
|
||||
// 买家账号只落任务自身字段(隐私红线:不进 work_orders.material_json)
|
||||
claim_submission_json: {
|
||||
gameAccount,
|
||||
submittedAt: now,
|
||||
source: 'claim_skin',
|
||||
},
|
||||
last_error: '',
|
||||
updated_at: now,
|
||||
})
|
||||
|
||||
if (!updatedTask) {
|
||||
throw createHttpError('领取结果保存失败,请稍后重试', {
|
||||
statusCode: 500,
|
||||
errorCode: 'claim_skin_submit_failed',
|
||||
context: { taskId: task.id },
|
||||
})
|
||||
}
|
||||
|
||||
logIntegration('[claim-skin]', '皮肤订单已领取(游戏账号已提交,平台券已核销)', {
|
||||
taskId: task.id,
|
||||
platformOrderId: task.platform_order_id,
|
||||
orderId: context.order.id,
|
||||
orderItemId: context.orderItem.id,
|
||||
})
|
||||
|
||||
// 把 token 标记为「已使用」(used_at/used_count),领取页据此显示 used 状态。
|
||||
// ⚠️ 刻意**不改 status**(保持 active):`getClaimContext` 会拦截非 active 的 token,
|
||||
// 改成 used 会让买家重开链接看到「链接不可用」,破坏「重复打开/重复提交幂等」。
|
||||
// 幂等读已成功落库,这里失败只记 warn,不把已完成的领取回报成失败。
|
||||
await updateClaimToken(context.claimToken.id, {
|
||||
used_at: now,
|
||||
used_count: 1,
|
||||
updated_at: now,
|
||||
}).catch((error) => {
|
||||
logIntegration(
|
||||
'[claim-skin]',
|
||||
'标记领取 token 已使用失败(领取结果已保存)',
|
||||
{
|
||||
taskId: task.id,
|
||||
claimTokenId: context.claimToken.id,
|
||||
error: error instanceof Error ? error.message : String(error),
|
||||
},
|
||||
{ level: 'warn' },
|
||||
)
|
||||
})
|
||||
|
||||
return { status: 'submitted', message: SKIN_CLAIM_SUCCESS_MESSAGE }
|
||||
}
|
||||
Reference in New Issue
Block a user