feat(consignment): 一个寄卖单号锚定全流程 + 统一状态机 + 卖家侧确认加好友/提交赠送截图

问题:一件货身上挂着三套互不相通的状态(提报单审核态、仓库库存态、工单赠送态),
my-items 同时返回两个数组、卖家端分两个列表渲染,同一件货显示两行两个号;
且卖家端只映射了前两套状态,"已出库"之后流程就断了,卖家不知道该干什么。

- 提报单号 SUB… 作为唯一「寄卖单号」从发布锚定到结算(零迁移);
  listWorkerConsignments 改成一件货一条记录,库存/工单信息挂上去,
  客服手工入库的现货(无提报单)才回退用库存号当锚点
- 新增 domain/consignment-item-stage.ts:把三套底层状态推导成卖家看得懂的一个阶段
  (待审核/已通过待匹配/已匹配-待加好友/冷却中/待赠送/已赠送待审核/已完成/驳回/作废/取消)
  + 一句"下一步做什么" + 能力位(谁能确认加好友、谁该传截图),列表筛选与 KPI 也改由它驱动
- 卖家侧新增动作(以前只有 publish + my-items,卖家只能干看):
  POST /worker/consignment/items/:submissionId/{confirm-friend,gift-evidence}
  POST /worker/consignment/inventories/:inventoryId/{confirm-friend,gift-evidence}(手工入库现货)
  复用既有工单链路 confirmWorkOrderFriendAdded / submitWorkerOrderAcceptance,
  只加归属校验(不是本人履约的订单 403),顺带白拿"冷却没结束不许提交凭证""必须带图"
- 客服端用同一个号:库存列表/详情补 sourceSubmissionNo(LEFT JOIN 提报单),
  履约/指派写进工单的寄售信息也带上;关键字搜索支持按寄卖单号搜(计数 SQL 同步补 join)

真实库端到端验证:确认加好友 → gift_phase=friend_countdown / friend_added_at 落库 /
gift_available_at 正好 +72h;冷却期内提交截图被拒(work_order_gift_cooldown_active);
越权操作被拒(consignment_item_not_found);按寄卖单号搜索命中正确。临时数据已清理。
This commit is contained in:
yml2213
2026-09-17 10:57:57 +08:00
parent 99752dce9e
commit 44de11a3a7
19 changed files with 1574 additions and 204 deletions
@@ -0,0 +1,175 @@
import assert from 'node:assert/strict'
import test from 'node:test'
import { CONSIGNMENT_ITEM_STAGE, deriveConsignmentItemStage } from './consignment-item-stage.js'
const SELLER = { role: 'seller', workerId: 7 } as const
const NOW = Date.parse('2026-09-17T12:00:00.000Z')
function friendGiftOrder(overrides: Record<string, unknown> = {}) {
return {
status: 'in_progress',
acceptance_mode: 'friend_gift',
gift_phase: 'material_required',
gift_available_at: null,
friend_added_at: null,
assignedWorkerId: 7,
...overrides,
}
}
test('提报审核态:待审核 / 已驳回', () => {
const pending = deriveConsignmentItemStage({ submissionStatus: 'pending_review' })
assert.equal(pending.stage, CONSIGNMENT_ITEM_STAGE.PENDING_REVIEW)
assert.equal(pending.label, '待审核')
assert.equal(pending.group, 'reviewing')
const rejected = deriveConsignmentItemStage({
submissionStatus: 'rejected',
inventoryStatus: null,
})
assert.equal(rejected.stage, CONSIGNMENT_ITEM_STAGE.REJECTED)
assert.equal(rejected.group, 'finished')
})
test('审核通过到在库:已通过(在库待匹配),没人需要操作', () => {
const result = deriveConsignmentItemStage({
submissionStatus: 'approved',
inventoryStatus: 'in_stock',
})
assert.equal(result.stage, CONSIGNMENT_ITEM_STAGE.IN_STOCK)
assert.equal(result.label, '已通过(在库待匹配)')
assert.equal(result.canConfirmFriend, false)
assert.equal(result.canSubmitEvidence, false)
})
test('内部现货履约:卖家只等客服确认加好友,不给卖家按钮', () => {
const result = deriveConsignmentItemStage({
submissionStatus: 'approved',
inventoryStatus: 'consumed',
workOrder: friendGiftOrder({ internalStock: true, assignedWorkerId: null }),
viewer: SELLER,
})
assert.equal(result.stage, CONSIGNMENT_ITEM_STAGE.MATCHED_WAITING_FRIEND)
assert.equal(result.canConfirmFriend, false)
assert.ok(result.hint.includes('客服'))
})
test('指派打手线:本人履约时卖家可以点确认加好友,别人不行', () => {
const mine = deriveConsignmentItemStage({
submissionStatus: 'approved',
inventoryStatus: 'consumed',
workOrder: friendGiftOrder({ gift_phase: 'material_submitted' }),
viewer: SELLER,
})
assert.equal(mine.stage, CONSIGNMENT_ITEM_STAGE.MATCHED_WAITING_FRIEND)
assert.equal(mine.canConfirmFriend, true)
assert.ok(mine.hint.includes('押金不退'), '确认加好友必须提示押金不退')
const others = deriveConsignmentItemStage({
submissionStatus: 'approved',
inventoryStatus: 'consumed',
workOrder: friendGiftOrder({ gift_phase: 'material_submitted', assignedWorkerId: 99 }),
viewer: SELLER,
})
assert.equal(others.canConfirmFriend, false)
})
test('冷却中:给倒计时阶段,不给提交按钮;冷却到点后变成待赠送', () => {
const cooling = deriveConsignmentItemStage({
submissionStatus: 'approved',
inventoryStatus: 'consumed',
workOrder: friendGiftOrder({
gift_phase: 'friend_countdown',
friend_added_at: '2026-09-17T00:00:00.000Z',
gift_available_at: '2026-09-20T00:00:00.000Z',
}),
viewer: SELLER,
now: NOW,
})
assert.equal(cooling.stage, CONSIGNMENT_ITEM_STAGE.GIFT_COOLDOWN)
assert.equal(cooling.label, '加好友赠送冷却中')
assert.equal(cooling.canSubmitEvidence, false, '冷却期没走完不允许上传赠送截图')
const ready = deriveConsignmentItemStage({
submissionStatus: 'approved',
inventoryStatus: 'consumed',
workOrder: friendGiftOrder({
gift_phase: 'friend_countdown',
friend_added_at: '2026-09-14T00:00:00.000Z',
gift_available_at: '2026-09-17T00:00:00.000Z',
}),
viewer: SELLER,
now: NOW,
})
assert.equal(ready.stage, CONSIGNMENT_ITEM_STAGE.GIFT_READY)
assert.equal(ready.label, '待赠送')
assert.equal(ready.canSubmitEvidence, true)
assert.equal(ready.evidenceButtonLabel, '提交赠送截图')
})
test('已赠送与已完成:凭证待审 → 客服验收后完成', () => {
const submitted = deriveConsignmentItemStage({
submissionStatus: 'approved',
inventoryStatus: 'consumed',
workOrder: friendGiftOrder({
status: 'pending_acceptance',
gift_phase: 'friend_countdown',
friend_added_at: '2026-09-14T00:00:00.000Z',
gift_available_at: '2026-09-17T00:00:00.000Z',
}),
viewer: SELLER,
now: NOW,
})
assert.equal(submitted.stage, CONSIGNMENT_ITEM_STAGE.GIFT_SUBMITTED)
assert.equal(submitted.label, '已赠送待审核')
assert.equal(submitted.canSubmitEvidence, false)
const completed = deriveConsignmentItemStage({
submissionStatus: 'approved',
inventoryStatus: 'consumed',
workOrder: friendGiftOrder({ status: 'accepted' }),
viewer: SELLER,
})
assert.equal(completed.stage, CONSIGNMENT_ITEM_STAGE.COMPLETED)
assert.equal(completed.group, 'finished')
})
test('终态:已下架作废 / 关联订单取消', () => {
assert.equal(
deriveConsignmentItemStage({ submissionStatus: 'approved', inventoryStatus: 'archived' }).stage,
CONSIGNMENT_ITEM_STAGE.ARCHIVED,
)
assert.equal(
deriveConsignmentItemStage({
submissionStatus: 'approved',
inventoryStatus: 'consumed',
workOrder: friendGiftOrder({ status: 'cancelled' }),
}).stage,
CONSIGNMENT_ITEM_STAGE.CANCELLED,
)
})
test('标准验收的寄卖单:履约中 / 待验收,按钮文案是提交验收材料', () => {
const fulfilling = deriveConsignmentItemStage({
submissionStatus: 'approved',
inventoryStatus: 'consumed',
workOrder: {
status: 'in_progress',
acceptance_mode: 'standard',
assignedWorkerId: 7,
},
viewer: SELLER,
})
assert.equal(fulfilling.stage, CONSIGNMENT_ITEM_STAGE.FULFILLING)
assert.equal(fulfilling.canSubmitEvidence, true)
assert.equal(fulfilling.evidenceButtonLabel, '提交验收材料')
const pending = deriveConsignmentItemStage({
submissionStatus: 'approved',
inventoryStatus: 'consumed',
workOrder: { status: 'pending_acceptance', acceptance_mode: 'standard' },
viewer: SELLER,
})
assert.equal(pending.stage, CONSIGNMENT_ITEM_STAGE.PENDING_ACCEPTANCE)
})
@@ -0,0 +1,261 @@
/**
* 寄卖单统一状态机。
*
* 以前一件寄卖货身上挂着三套互不相通的状态(提报单审核态、仓库库存态、工单赠送态),
* 卖家端只能看到前两套,"已出库"之后流程就断在黑暗里。这里把三套状态**推导成一个**
* 卖家看得懂的阶段,作为"我的寄卖"列表与详情页的唯一展示口径。
*
* 阶段顺序(正常流程):
* 待审核 → 已通过(在库待匹配) → 已匹配-待加好友 → 加好友赠送冷却中 → 待赠送
* → 已赠送待审核 → 已完成
* 异常/终态:已驳回、已下架作废、已取消
*/
import {
WORK_ORDER_ACCEPTANCE_MODE,
WORK_ORDER_GIFT_PHASE,
isFriendGiftAcceptanceMode,
} from './work-order-acceptance-mode.js'
export const CONSIGNMENT_ITEM_STAGE = {
PENDING_REVIEW: 'pending_review',
IN_STOCK: 'in_stock',
MATCHED_WAITING_FRIEND: 'matched_waiting_friend',
GIFT_COOLDOWN: 'gift_cooldown',
GIFT_READY: 'gift_ready',
GIFT_SUBMITTED: 'gift_submitted',
COMPLETED: 'completed',
REJECTED: 'rejected',
ARCHIVED: 'archived',
CANCELLED: 'cancelled',
/** 标准验收(非好友赠送)的履约中 / 待验收 */
FULFILLING: 'fulfilling',
PENDING_ACCEPTANCE: 'pending_acceptance',
} as const
export type ConsignmentItemStage =
(typeof CONSIGNMENT_ITEM_STAGE)[keyof typeof CONSIGNMENT_ITEM_STAGE]
/** 列表筛选分组:进行中 / 已结束 */
export type ConsignmentItemStageGroup = 'reviewing' | 'active' | 'finished'
const STAGE_META: Record<
ConsignmentItemStage,
{ label: string; group: ConsignmentItemStageGroup; color: string }
> = {
[CONSIGNMENT_ITEM_STAGE.PENDING_REVIEW]: { label: '待审核', group: 'reviewing', color: 'gold' },
[CONSIGNMENT_ITEM_STAGE.REJECTED]: { label: '已驳回', group: 'finished', color: 'red' },
[CONSIGNMENT_ITEM_STAGE.IN_STOCK]: {
label: '已通过(在库待匹配)',
group: 'active',
color: 'blue',
},
[CONSIGNMENT_ITEM_STAGE.MATCHED_WAITING_FRIEND]: {
label: '已匹配-待加好友',
group: 'active',
color: 'purple',
},
[CONSIGNMENT_ITEM_STAGE.GIFT_COOLDOWN]: {
label: '加好友赠送冷却中',
group: 'active',
color: 'orange',
},
[CONSIGNMENT_ITEM_STAGE.GIFT_READY]: { label: '待赠送', group: 'active', color: 'orange' },
[CONSIGNMENT_ITEM_STAGE.GIFT_SUBMITTED]: {
label: '已赠送待审核',
group: 'active',
color: 'processing',
},
[CONSIGNMENT_ITEM_STAGE.FULFILLING]: { label: '履约中', group: 'active', color: 'purple' },
[CONSIGNMENT_ITEM_STAGE.PENDING_ACCEPTANCE]: {
label: '待验收',
group: 'active',
color: 'processing',
},
[CONSIGNMENT_ITEM_STAGE.COMPLETED]: { label: '已完成', group: 'finished', color: 'green' },
[CONSIGNMENT_ITEM_STAGE.ARCHIVED]: { label: '已下架作废', group: 'finished', color: 'default' },
[CONSIGNMENT_ITEM_STAGE.CANCELLED]: { label: '已取消', group: 'finished', color: 'default' },
}
export function getConsignmentItemStageMeta(stage: ConsignmentItemStage) {
return STAGE_META[stage] || STAGE_META[CONSIGNMENT_ITEM_STAGE.PENDING_REVIEW]
}
export type ConsignmentItemWorkOrderInput = {
status: string
acceptance_mode?: string | null
gift_phase?: string | null
gift_available_at?: string | null
friend_added_at?: string | null
/** 是否走内部现货履约(内部仓账号交付,客服操作) */
internalStock?: boolean
assignedWorkerId?: number | null
}
export type DeriveConsignmentItemStageInput = {
submissionStatus: string
inventoryStatus?: string | null
workOrder?: ConsignmentItemWorkOrderInput | null
/** 当前查看者身份:卖家端要判断"是不是我在履约"才能给出按钮 */
viewer?: { role: 'seller'; workerId: number } | { role: 'admin' }
/** 便于测试注入"现在" */
now?: number
}
export type ConsignmentItemStageResult = {
stage: ConsignmentItemStage
label: string
group: ConsignmentItemStageGroup
color: string
/** 卖家侧下一步该做什么,直接可展示给用户 */
hint: string
/** 卖家能否自己点「确认加好友」 */
canConfirmFriend: boolean
/** 卖家能否上传赠送/验收截图 */
canSubmitEvidence: boolean
evidenceButtonLabel: '提交赠送截图' | '提交验收材料'
}
const ACTIVE_WORK_ORDER_STATUSES = new Set(['in_progress', 'problem', 'pending_acceptance'])
function build(
stage: ConsignmentItemStage,
hint: string,
capabilities?: {
canConfirmFriend?: boolean
canSubmitEvidence?: boolean
evidenceButtonLabel?: '提交赠送截图' | '提交验收材料'
},
): ConsignmentItemStageResult {
const meta = getConsignmentItemStageMeta(stage)
return {
stage,
label: meta.label,
group: meta.group,
color: meta.color,
hint,
canConfirmFriend: Boolean(capabilities?.canConfirmFriend),
canSubmitEvidence: Boolean(capabilities?.canSubmitEvidence),
evidenceButtonLabel: capabilities?.evidenceButtonLabel || '提交赠送截图',
}
}
/**
* 把「提报单 + 库存 + 绑定工单」三套状态推导成卖家端唯一阶段。
*/
export function deriveConsignmentItemStage(
input: DeriveConsignmentItemStageInput,
): ConsignmentItemStageResult {
const submissionStatus = String(input.submissionStatus || '').trim()
const inventoryStatus = String(input.inventoryStatus || '').trim()
if (submissionStatus === 'rejected') {
return build(CONSIGNMENT_ITEM_STAGE.REJECTED, '提报未通过,可修改后重新提报')
}
if (submissionStatus === 'pending_review') {
return build(CONSIGNMENT_ITEM_STAGE.PENDING_REVIEW, '客服审核中,通过后自动进入在库待匹配')
}
if (!inventoryStatus) {
// 审核已通过但库存行还没读到(正常不会发生),按在库展示而不是给卖家一个空白
return build(CONSIGNMENT_ITEM_STAGE.IN_STOCK, '已通过审核,正在入库')
}
if (inventoryStatus === 'archived') {
return build(CONSIGNMENT_ITEM_STAGE.ARCHIVED, '该现货已下架作废,如需继续寄卖请重新提报')
}
if (inventoryStatus !== 'consumed') {
return build(CONSIGNMENT_ITEM_STAGE.IN_STOCK, '已在库待匹配,匹配到订单后会自动占用')
}
const workOrder = input.workOrder || null
if (!workOrder) {
return build(CONSIGNMENT_ITEM_STAGE.FULFILLING, '已占用但未读到关联订单,请联系客服核对')
}
const status = String(workOrder.status || '').trim()
if (status === 'cancelled') {
return build(CONSIGNMENT_ITEM_STAGE.CANCELLED, '关联订单已取消,现货已按规则处理')
}
if (status === 'accepted' || status === 'completed') {
return build(CONSIGNMENT_ITEM_STAGE.COMPLETED, '订单已完成,货款与押金已结算')
}
if (!ACTIVE_WORK_ORDER_STATUSES.has(status)) {
return build(CONSIGNMENT_ITEM_STAGE.FULFILLING, '关联订单状态已变化,请联系客服核对')
}
const isFriendGift = isFriendGiftAcceptanceMode(workOrder.acceptance_mode)
const viewerWorkerId = input.viewer?.role === 'seller' ? Number(input.viewer.workerId) : 0
const selfFulfilling =
viewerWorkerId > 0 && Number(workOrder.assignedWorkerId || 0) === viewerWorkerId
if (isFriendGift) {
const now = input.now ?? Date.now()
const rawPhase = String(workOrder.gift_phase || '').trim()
const phase =
rawPhase === WORK_ORDER_GIFT_PHASE.FRIEND_COUNTDOWN && isGiftAvailable(workOrder, now)
? WORK_ORDER_GIFT_PHASE.GIFT_READY
: rawPhase
if (status === 'pending_acceptance') {
return build(CONSIGNMENT_ITEM_STAGE.GIFT_SUBMITTED, '赠送凭证已提交,等待客服审核')
}
if (
phase === WORK_ORDER_GIFT_PHASE.MATERIAL_SUBMITTED ||
phase === WORK_ORDER_GIFT_PHASE.MATERIAL_REQUIRED
) {
const internalStock = Boolean(workOrder.internalStock)
if (internalStock) {
// 内部仓账号由客服操作,卖家只等
return build(
CONSIGNMENT_ITEM_STAGE.MATCHED_WAITING_FRIEND,
'等待客服确认加好友,确认后进入赠送冷却期',
)
}
if (phase === WORK_ORDER_GIFT_PHASE.MATERIAL_REQUIRED) {
return build(
CONSIGNMENT_ITEM_STAGE.MATCHED_WAITING_FRIEND,
selfFulfilling
? '请先在订单页提交赠送资料,再确认加好友'
: '等待打手提交赠送资料后确认加好友',
)
}
return build(
CONSIGNMENT_ITEM_STAGE.MATCHED_WAITING_FRIEND,
selfFulfilling
? '好友加好后点「确认加好友」:确认即进入赠送冷却期,未完成赠送押金不退'
: '等待接单打手确认加好友,确认后进入赠送冷却期',
{ canConfirmFriend: selfFulfilling },
)
}
if (phase === WORK_ORDER_GIFT_PHASE.FRIEND_COUNTDOWN) {
return build(CONSIGNMENT_ITEM_STAGE.GIFT_COOLDOWN, '冷却期结束后才能赠送,请耐心等待')
}
if (phase === WORK_ORDER_GIFT_PHASE.GIFT_READY) {
return build(
CONSIGNMENT_ITEM_STAGE.GIFT_READY,
selfFulfilling
? '冷却已结束,请用账号赠送并上传赠送截图给客服审核(未完成赠送押金不退)'
: '冷却已结束,等待履约方赠送并上传截图',
{ canSubmitEvidence: selfFulfilling, evidenceButtonLabel: '提交赠送截图' },
)
}
return build(CONSIGNMENT_ITEM_STAGE.MATCHED_WAITING_FRIEND, '等待确认加好友')
}
// 标准验收(非好友赠送)的寄卖单
if (status === 'pending_acceptance') {
return build(CONSIGNMENT_ITEM_STAGE.PENDING_ACCEPTANCE, '验收材料已提交,等待客服验收')
}
return build(
CONSIGNMENT_ITEM_STAGE.FULFILLING,
selfFulfilling ? '请在订单页提交验收材料' : '履约中,等待打手提交验收材料',
{ canSubmitEvidence: selfFulfilling, evidenceButtonLabel: '提交验收材料' },
)
}
function isGiftAvailable(workOrder: ConsignmentItemWorkOrderInput, now: number) {
if (String(workOrder.acceptance_mode || '') !== WORK_ORDER_ACCEPTANCE_MODE.FRIEND_GIFT) {
return false
}
const availableAt = Date.parse(String(workOrder.gift_available_at || ''))
return Number.isFinite(availableAt) && availableAt <= now
}