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:
yml2213
2026-10-09 15:06:43 +08:00
parent ecc8ffaee4
commit 56a8184576
30 changed files with 1993 additions and 32 deletions
@@ -0,0 +1,157 @@
import assert from 'node:assert/strict'
import test from 'node:test'
import {
douyinMashidaSkinExecutor,
resolveSkinTaskClaimToken,
} from './douyin-mashida-skin-executor.js'
import { getFulfillmentExecutor } from './registry.js'
import type { FulfillmentPrepareDeps } from './types.js'
import type { TaskRow } from '../../../types/repository/rows.js'
const FIXED_NOW = '2026-10-10T00:00:00.000Z'
function createTask(overrides: Partial<TaskRow> = {}): TaskRow {
return {
id: 9,
order_id: 1,
order_item_id: 11,
unit_index: 1,
platform_order_id: '6930318258716179555',
profile_id: 3,
task_no: 'DT-1',
executor_key: 'douyin_mashida_skin',
task_status: 'paid',
delivery_status: 'pending',
result_code: '',
result_message: '',
automation_mode: 'manual',
requires_claim: true,
user_action_status: 'pending_claim',
attempt_count: 0,
runtime_session_id: '',
login_type: '',
nickname: '',
role_name: '',
role_id: '',
area: '',
partition_name: '',
claim_token: '',
claim_expires_at: null,
primary_claim_token: '',
primary_claim_token_id: null,
primary_claim_token_status: '',
primary_claim_expires_at: null,
artifacts_json: {},
context_json: {},
screenshot_path: '',
last_error: '',
retry_count: 0,
created_at: FIXED_NOW,
updated_at: FIXED_NOW,
claimed_at: null,
role_confirmed_at: null,
redeemed_at: null,
...overrides,
}
}
function createDeps(overrides: Partial<FulfillmentPrepareDeps> = {}) {
const updates: Array<{ taskId: number | string; patch: Record<string, unknown> }> = []
const tokenRequests: Array<number | string> = []
const deps: FulfillmentPrepareDeps = {
updateTask: async (taskId, patch) => {
updates.push({ taskId, patch: { ...patch } })
return { ...createTask(), ...patch }
},
createTaskClaimToken: async (taskId) => {
tokenRequests.push(taskId)
return { token: 'skin-token', expired_at: null }
},
notifyTaskAutoManualReview: async () => null,
nowIso: () => FIXED_NOW,
...overrides,
}
return { deps, updates, tokenRequests }
}
test('皮肤执行器已注册到 registry', () => {
assert.equal(getFulfillmentExecutor('douyin_mashida_skin'), douyinMashidaSkinExecutor)
})
test('preparePaidTask:无 token 时生成 claim token 并置为待领取', async () => {
const { deps, updates, tokenRequests } = createDeps()
const result = await douyinMashidaSkinExecutor.preparePaidTask?.(createTask(), deps)
assert.deepEqual(tokenRequests, [9])
assert.equal(updates.length, 2)
assert.deepEqual(updates[0]?.patch, {
claim_token: 'skin-token',
claim_expires_at: null,
updated_at: FIXED_NOW,
})
assert.deepEqual(updates[1]?.patch, {
task_status: 'link_generated',
user_action_status: 'pending_claim',
last_error: '',
updated_at: FIXED_NOW,
})
assert.equal(result?.task_status, 'link_generated')
})
test('preparePaidTask:已有 token 且已是待领取时完全幂等(不重复建 token)', async () => {
const { deps, updates, tokenRequests } = createDeps()
const result = await douyinMashidaSkinExecutor.preparePaidTask?.(
createTask({
claim_token: 'skin-token',
primary_claim_token: 'skin-token',
primary_claim_token_id: 5,
task_status: 'link_generated',
user_action_status: 'pending_claim',
}),
deps,
)
assert.deepEqual(tokenRequests, [])
assert.deepEqual(updates, [])
assert.equal(result?.task_status, 'link_generated')
})
test('preparePaidTask:已有 token 但状态未就绪时只补状态', async () => {
const { deps, updates, tokenRequests } = createDeps()
await douyinMashidaSkinExecutor.preparePaidTask?.(
createTask({ claim_token: 'skin-token', primary_claim_token: 'skin-token' }),
deps,
)
assert.deepEqual(tokenRequests, [])
assert.equal(updates.length, 1)
assert.equal(updates[0]?.patch.task_status, 'link_generated')
})
test('preparePaidTask:买家已领取的任务不会被降级回待领取', async () => {
const { deps, updates, tokenRequests } = createDeps()
const claimed = createTask({
claim_token: 'skin-token',
primary_claim_token: 'skin-token',
task_status: 'claimed',
user_action_status: 'not_required',
})
const result = await douyinMashidaSkinExecutor.preparePaidTask?.(claimed, deps)
assert.deepEqual(tokenRequests, [])
assert.deepEqual(updates, [])
assert.equal(result?.task_status, 'claimed')
})
test('resolveSkinTaskClaimToken 优先 primary_claim_token', () => {
assert.equal(resolveSkinTaskClaimToken({ claim_token: 'a' }), 'a')
assert.equal(resolveSkinTaskClaimToken({ claim_token: 'a', primary_claim_token: 'b' }), 'b')
assert.equal(resolveSkinTaskClaimToken(null), '')
})
@@ -0,0 +1,134 @@
import { TASK_STATUS } from '../../../domain/task-status.js'
import { listTasksByOrderId } from '../../../repositories/task-repo.js'
import { logWarn } from '../../../utils/logger.js'
import { resolveDouyinMashidaSkinClaimUrl } from '../../platforms/douyin-mashida/claim-link.js'
import type { DouyinMashidaSourceConfig } from '../../platforms/douyin-mashida/source-config-service.js'
import {
FULFILLMENT_EXECUTOR_KEYS,
type FulfillmentDeliveryLink,
type FulfillmentExecutor,
type FulfillmentPrepareDeps,
} from './types.js'
import type { TaskRow } from '../../../types/repository/rows.js'
/**
* 抖音码速达「皮肤自动发货」执行器。
*
* 与 affiliate-dash 执行器的最大区别:**不打任何外部平台**。
* 付款后我们只需要「确保任务有 claim token」并把任务置为待领取(`link_generated` + `pending_claim`),
* 领取链接(`claimLinkBase/token`)由调用方拿去做两件事:
* 1. 写进 `coupons.syncV2` 的 `cert_link`(见 redeem/certificate-service.ts);
* 2. 通过 `order.message` 按模板发给买家(见 douyin-mashida/notify-service.ts)。
*/
export const douyinMashidaSkinExecutor: FulfillmentExecutor = {
key: FULFILLMENT_EXECUTOR_KEYS.DOUYIN_MASHIDA_SKIN,
preparePaidTask,
resolveDeliveryLink,
}
export function resolveSkinTaskClaimToken(task: Partial<TaskRow> | null | undefined): string {
return String(task?.primary_claim_token || task?.claim_token || '').trim()
}
export type OrderItemSkinClaimLink = {
/** 领取链接;未配置 claimLinkBase、或该订单项没有皮肤任务/token 时为空串 */
claimUrl: string
token: string
/** 该订单项下的皮肤履约单元数量(数量 > 1 时会有多个 token) */
taskCount: number
pickedTaskId: number | null
}
/**
* 取某订单项的皮肤领取链接。
*
* 一个订单项按数量会拆成 N 个履约单元(`fulfillment_tasks`),每个单元一个 token
* (`claim_tokens.task_id` 唯一);这里固定取 task id 最小的那个,保证同一张券每次解析结果一致。
* 调用方(certificate-service / notify-service)据 `taskCount` 打 warn 留痕。
*/
export async function resolveOrderItemSkinClaimLink(input: {
orderId: number | string
orderItemId: number | string
config?: DouyinMashidaSourceConfig | undefined
}): Promise<OrderItemSkinClaimLink> {
const skinTasks = (await listTasksByOrderId(input.orderId))
.filter(
(task) =>
Number(task.order_item_id) === Number(input.orderItemId) &&
String(task.executor_key || '').trim() === FULFILLMENT_EXECUTOR_KEYS.DOUYIN_MASHIDA_SKIN,
)
.sort((left, right) => Number(left.id) - Number(right.id))
const pickedTask = skinTasks[0] || null
const token = resolveSkinTaskClaimToken(pickedTask)
return {
claimUrl: resolveDouyinMashidaSkinClaimUrl(token, input.config),
token,
taskCount: skinTasks.length,
pickedTaskId: pickedTask ? Number(pickedTask.id) : null,
}
}
async function preparePaidTask(
task: TaskRow,
deps: FulfillmentPrepareDeps,
): Promise<TaskRow | null> {
let workingTask = task
// 幂等:已有 token 不重复生成(claim_tokens.task_id 唯一,重复插入只会覆盖)。
if (!resolveSkinTaskClaimToken(task)) {
const claimToken = await deps.createTaskClaimToken(task.id)
workingTask =
(await deps.updateTask(task.id, {
claim_token: claimToken.token,
claim_expires_at: claimToken.expired_at,
updated_at: deps.nowIso(),
})) || task
}
// 买家已提交过(claimed)的任务不允许被降级回待领取。
if (
workingTask.task_status === TASK_STATUS.CLAIMED ||
workingTask.task_status === TASK_STATUS.REDEEMED ||
workingTask.task_status === TASK_STATUS.COMPLETED
) {
return workingTask
}
if (
workingTask.task_status !== TASK_STATUS.LINK_GENERATED ||
workingTask.user_action_status !== 'pending_claim'
) {
workingTask =
(await deps.updateTask(task.id, {
task_status: TASK_STATUS.LINK_GENERATED,
user_action_status: 'pending_claim',
last_error: '',
updated_at: deps.nowIso(),
})) || workingTask
}
return workingTask
}
/** 对外统一返回本站皮肤领取链接;基址未配置时返回 null(不猜、不回退 hash 版领取页)。 */
async function resolveDeliveryLink(task: TaskRow): Promise<FulfillmentDeliveryLink | null> {
const token = resolveSkinTaskClaimToken(task)
if (!token) {
return null
}
const claimUrl = resolveDouyinMashidaSkinClaimUrl(token)
if (!claimUrl) {
logWarn('[douyin-mashida/skin]', '未配置领取链接基址(claimLinkBase),无法生成皮肤领取链接', {
taskId: task.id,
taskNo: task.task_no,
platformOrderId: task.platform_order_id,
})
return null
}
const expireTime = String(task.primary_claim_expires_at || task.claim_expires_at || '').trim()
return expireTime ? { claimUrl, expireTime } : { claimUrl }
}
@@ -1,5 +1,6 @@
import { isPaidPreparationStableStatus } from '../../../domain/task-status.js'
import { affiliateDashExecutor } from './affiliate-dash-executor.js'
import { douyinMashidaSkinExecutor } from './douyin-mashida-skin-executor.js'
import { legacyFeifeiExecutor, legacyLewanExecutor } from './legacy-retired-executor.js'
import { manualDispatchExecutor } from './manual-executor.js'
import {
@@ -14,6 +15,7 @@ import type { TaskRow } from '../../../types/repository/rows.js'
const EXECUTORS = new Map<string, FulfillmentExecutor>([
[FULFILLMENT_EXECUTOR_KEYS.AFFILIATE_DASH, affiliateDashExecutor],
[FULFILLMENT_EXECUTOR_KEYS.DOUYIN_MASHIDA_SKIN, douyinMashidaSkinExecutor],
[FULFILLMENT_EXECUTOR_KEYS.MANUAL_DISPATCH, manualDispatchExecutor],
[FULFILLMENT_EXECUTOR_KEYS.KUAISHOU_CLOUD, legacyLewanExecutor],
[FULFILLMENT_EXECUTOR_KEYS.KUAISHOU_FEIFEI, legacyFeifeiExecutor],
@@ -4,6 +4,8 @@ import type { TaskRow } from '../../../types/repository/rows.js'
export const FULFILLMENT_EXECUTOR_KEYS = {
MANUAL_DISPATCH: 'manual_dispatch',
AFFILIATE_DASH: 'affiliate_dash',
/** 抖音码速达「皮肤自动发货」:只发本站领取链接,不打 affiliate-dash 平台 */
DOUYIN_MASHIDA_SKIN: 'douyin_mashida_skin',
/** @deprecated 已下线,仅历史任务 / stub 识别 */
KUAISHOU_CLOUD: 'kuaishou_ct_assisted',
/** @deprecated 已下线,仅历史任务识别 */
@@ -68,6 +70,10 @@ export function isManualDispatchExecutor(value: unknown): boolean {
return normalizeExecutorKey(value) === FULFILLMENT_EXECUTOR_KEYS.MANUAL_DISPATCH
}
export function isDouyinMashidaSkinExecutor(value: unknown): boolean {
return normalizeExecutorKey(value) === FULFILLMENT_EXECUTOR_KEYS.DOUYIN_MASHIDA_SKIN
}
export function isRetiredFulfillmentExecutor(value: unknown): boolean {
const executorKey = normalizeExecutorKey(value)
return (