Merge branch 'dev'

2026-11-01 12:30:02 +08:00
parent 94a1436453 2f20e36a75
commit da16e8cf75
25 changed files with 1718 additions and 4 deletions
@@ -63,3 +63,5 @@ export * from './worker-hall-config-service.js'
 export * from './worker-acceptance-config-service.js'
 export * from './sync-worker-orders-service.js'
 export * from './consignment-contact-service.js'
+export * from './work-order-material-link-service.js'
+export * from './worker-material-link-config-service.js'
@@ -0,0 +1,74 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+import {
+  resolveWorkOrderMaterialLinkUnavailableReason,
+  pickSubmittedMaterialFields,
+} from './work-order-material-link-service.js'
+
+const NOW = '2026-10-31T12:00:00.000Z'
+
+test('补资料链接：active 且未过期时可用', () => {
+  assert.equal(
+    resolveWorkOrderMaterialLinkUnavailableReason(
+      { status: 'active', expires_at: '2026-10-31T13:00:00.000Z' },
+      NOW,
+    ),
+    '',
+  )
+})
+
+test('补资料链接：active 但已过期按过期处理', () => {
+  assert.equal(
+    resolveWorkOrderMaterialLinkUnavailableReason({ status: 'active', expires_at: NOW }, NOW),
+    'expired',
+  )
+})
+
+test('补资料链接：used / expired / revoked 分别返回对应原因', () => {
+  assert.equal(
+    resolveWorkOrderMaterialLinkUnavailableReason(
+      { status: 'used', expires_at: '2026-10-31T13:00:00.000Z' },
+      NOW,
+    ),
+    'used',
+  )
+  assert.equal(
+    resolveWorkOrderMaterialLinkUnavailableReason(
+      { status: 'expired', expires_at: '2026-10-31T13:00:00.000Z' },
+      NOW,
+    ),
+    'expired',
+  )
+  assert.equal(
+    resolveWorkOrderMaterialLinkUnavailableReason(
+      { status: 'revoked', expires_at: '2026-10-31T13:00:00.000Z' },
+      NOW,
+    ),
+    'revoked',
+  )
+})
+
+test('补资料链接：未知状态一律视为失效，避免误放行', () => {
+  assert.equal(
+    resolveWorkOrderMaterialLinkUnavailableReason(
+      {
+        status: 'unknown' as never,
+        expires_at: '2026-10-31T13:00:00.000Z',
+      },
+      NOW,
+    ),
+    'revoked',
+  )
+})
+
+test('补资料链接：提交字段只保留 requirements 白名单，额外字段被丢弃', () => {
+  const result = pickSubmittedMaterialFields([{ key: 'gameId' }, { key: 'gameNickname' }], {
+    gameId: '123',
+    gameNickname: '张三',
+    rewardAmount: '999',
+    status: 'accepted',
+  })
+
+  assert.deepEqual(result, { gameId: '123', gameNickname: '张三' })
+})
@@ -0,0 +1,401 @@
+import { randomBytes } from 'node:crypto'
+
+import { withTransaction } from '../../db/client.js'
+import { WORK_ORDER_STATUS } from '../../domain/work-order-status.js'
+import {
+  createWorkOrderEventWithClient,
+  createWorkOrderMaterialLinkWithClient,
+  findWorkOrderMaterialLinkByToken,
+  findActiveWorkOrderMaterialLinkWithClient,
+  getWorkOrderForUpdateWithClient,
+  getWorkOrderMaterialLinkForUpdateWithClient,
+  markWorkOrderMaterialLinkExpired,
+  markWorkOrderMaterialLinkUsedWithClient,
+  revokeActiveWorkOrderMaterialLinksWithClient,
+  updateWorkOrderMaterialWithClient,
+  type WorkOrderMaterialLinkRow,
+} from '../../repositories/worker-platform/index.js'
+import type { WorkOrderRow } from '../../repositories/worker-platform/types.js'
+import type { JsonObject } from '../../types/json.js'
+import { createHttpError } from '../../utils/http.js'
+import { logWarn } from '../../utils/logger.js'
+import { nowIso } from '../../utils/time.js'
+import { safeParseJson } from '../admin/admin-query-utils.js'
+import { resolveAdminNotificationEntity } from '../admin/admin-notification-service.js'
+import { publishWorkOrderRealtimeChange } from '../realtime/realtime-event-service.js'
+import {
+  mapCollectLookupOrder,
+  mapWorkOrderAdmin,
+  normalizeSubmittedFields,
+  normalizeUploadedFiles,
+  resolveRequirementFields,
+} from './mappers.js'
+import { getWorkerMaterialLinkConfig } from './worker-material-link-config-service.js'
+import { getRequiredWorkOrder } from './worker-session-context-service.js'
+
+const ALLOWED_MATERIAL_LINK_ORDER_STATUSES = new Set<string>([
+  WORK_ORDER_STATUS.PENDING_MATERIAL,
+  WORK_ORDER_STATUS.UNASSIGNED,
+])
+
+const MAX_MATERIAL_SCREENSHOTS = 5
+
+export type WorkOrderMaterialLinkUnavailableReason = 'used' | 'expired' | 'revoked' | ''
+
+/**
+ * 判断链接是否还能用。
+ *
+ * 只做纯函数判断，方便单测覆盖；数据库状态与过期时间都由调用方传入。
+ */
+export function resolveWorkOrderMaterialLinkUnavailableReason(
+  link: Pick<WorkOrderMaterialLinkRow, 'status' | 'expires_at'>,
+  now: string,
+): WorkOrderMaterialLinkUnavailableReason {
+  if (link.status === 'used') return 'used'
+  if (link.status === 'revoked') return 'revoked'
+  if (link.status === 'expired') return 'expired'
+  if (link.status !== 'active') return 'revoked'
+  if (new Date(link.expires_at).getTime() <= new Date(now).getTime()) return 'expired'
+  return ''
+}
+
+/**
+ * 只保留工单 requirement 里定义过的字段。
+ *
+ * 公开链接的提交体是客户可构造的，不能让 `rewardAmount`、`status` 之类的
+ * 额外 key 混进 material.collect.fields；这里按白名单裁剪一次。
+ */
+export function pickSubmittedMaterialFields(
+  fields: Array<{ key: string }>,
+  submitted: Record<string, string>,
+): Record<string, string> {
+  const allowedKeys = new Set(fields.map((field) => field.key))
+  return Object.fromEntries(Object.entries(submitted).filter(([key]) => allowedKeys.has(key)))
+}
+
+function throwMaterialLinkUnavailable(
+  reason: Exclude<WorkOrderMaterialLinkUnavailableReason, ''>,
+): never {
+  if (reason === 'used') {
+    throw createHttpError('链接已使用，如需修改资料请联系客服重新获取', {
+      statusCode: 410,
+      errorCode: 'material_link_used',
+    })
+  }
+  if (reason === 'expired') {
+    throw createHttpError('链接已过期，请联系客服重新获取', {
+      statusCode: 410,
+      errorCode: 'material_link_expired',
+    })
+  }
+  throw createHttpError('链接已失效，请联系客服重新获取', {
+    statusCode: 410,
+    errorCode: 'material_link_revoked',
+  })
+}
+
+/**
+ * 公开链接只对「待完善 / 未分配」开放，且不能已经指派打手或有进行中的拼单份额。
+ * 这三个条件同时满足，提交后才可以安全地把状态改成「未分配」。
+ */
+function assertWorkOrderAllowedForMaterialLink(order: WorkOrderRow): void {
+  if (!ALLOWED_MATERIAL_LINK_ORDER_STATUSES.has(order.status)) {
+    throw createHttpError('订单当前状态不允许补资料，请联系客服重新获取链接', {
+      statusCode: 409,
+      errorCode: 'material_link_order_status_invalid',
+    })
+  }
+  if (order.assigned_worker_id) {
+    throw createHttpError('订单已指派打手，不能通过公开链接修改资料', {
+      statusCode: 409,
+      errorCode: 'material_link_order_status_invalid',
+    })
+  }
+  if (Number(order.active_share_quantity || 0) > 0) {
+    throw createHttpError('订单已有拼单份额，不能通过公开链接修改资料', {
+      statusCode: 409,
+      errorCode: 'material_link_order_status_invalid',
+    })
+  }
+}
+
+function assertMaterialLinkRecordUsable(link: WorkOrderMaterialLinkRow, now: string): void {
+  const reason = resolveWorkOrderMaterialLinkUnavailableReason(link, now)
+  if (reason) throwMaterialLinkUnavailable(reason)
+}
+
+function mapPublicOrder(order: WorkOrderRow) {
+  return {
+    workOrderNo: order.work_order_no,
+    platformOrderId: order.platform_order_id,
+    productName: order.product_name,
+    status: order.status,
+  }
+}
+
+/** PostgreSQL 返回的 timestamptz 可能是 "YYYY-MM-DD HH:mm:ss" 字符串，统一转 ISO。 */
+function toIsoTimestamp(value: string): string {
+  const date = new Date(value)
+  return Number.isNaN(date.getTime()) ? String(value || '') : date.toISOString()
+}
+
+/**
+ * 管理端生成/复用一次性链接。
+ *
+ * 幂等策略：同一工单已有未过期 active 链接时直接返回，避免客服连续点两次
+ * 把刚发出去的链接顶掉；只有已使用/已过期/已撤销时才生成新 token。
+ */
+export async function createAdminWorkOrderMaterialLink(
+  workOrderId: number | string,
+  actorName = '',
+) {
+  const { ttlMinutes } = getWorkerMaterialLinkConfig()
+
+  return withTransaction(async (client) => {
+    const order = await getWorkOrderForUpdateWithClient(client, workOrderId)
+    if (!order) {
+      throw createHttpError('接单订单不存在', {
+        statusCode: 404,
+        errorCode: 'work_order_not_found',
+      })
+    }
+
+    if (!mapWorkOrderAdmin(order).capabilities.canUpdateMaterial) {
+      throw createHttpError('当前状态不能生成补资料链接', {
+        statusCode: 409,
+        errorCode: 'material_link_status_invalid',
+      })
+    }
+    assertWorkOrderAllowedForMaterialLink(order)
+
+    // 锁到手后再取时间，避免等锁期间旧链接过期却仍按旧时间复用。
+    const now = nowIso()
+    const existing = await findActiveWorkOrderMaterialLinkWithClient(client, order.id, now)
+    if (existing) {
+      return {
+        token: existing.token,
+        expiresAt: toIsoTimestamp(existing.expires_at),
+        reused: true,
+      }
+    }
+
+    await revokeActiveWorkOrderMaterialLinksWithClient(client, order.id, now)
+    const token = randomBytes(24).toString('base64url')
+    const expiresAt = new Date(Date.now() + ttlMinutes * 60 * 1000).toISOString()
+    const link = await createWorkOrderMaterialLinkWithClient(client, {
+      workOrderId: order.id,
+      token,
+      expiresAt,
+      createdBy: String(actorName || '').trim(),
+      now,
+    })
+
+    return {
+      token: link.token,
+      expiresAt: toIsoTimestamp(link.expires_at),
+      reused: false,
+    }
+  })
+}
+
+/**
+ * 公开页读取链接内容。
+ *
+ * 只返回客户补资料需要的最少信息：商品/单号、动态字段、已填值、截图、过期时间。
+ * 不返回发单价格、押金、成本、打手、后台备注等任何后台字段。
+ */
+export async function getPublicWorkOrderMaterialLink(token: string) {
+  const link = await findWorkOrderMaterialLinkByToken(token)
+  if (!link) {
+    throw createHttpError('链接无效，请确认链接是否完整', {
+      statusCode: 404,
+      errorCode: 'material_link_not_found',
+    })
+  }
+
+  const now = nowIso()
+  const reason = resolveWorkOrderMaterialLinkUnavailableReason(link, now)
+  if (reason) {
+    if (reason === 'expired') {
+      await markWorkOrderMaterialLinkExpired(link.id, now)
+    }
+    throwMaterialLinkUnavailable(reason)
+  }
+
+  const order = await getRequiredWorkOrder(link.work_order_id)
+  assertWorkOrderAllowedForMaterialLink(order)
+
+  const mapped = mapCollectLookupOrder(order)
+  return {
+    order: {
+      workOrderNo: mapped.workOrderNo,
+      platformOrderId: mapped.platformOrderId,
+      productName: mapped.productName,
+      status: mapped.status,
+    },
+    fields: mapped.fields,
+    values: mapped.values,
+    screenshots: mapped.screenshots,
+    expiresAt: toIsoTimestamp(link.expires_at),
+  }
+}
+
+/**
+ * 公开页提交资料。
+ *
+ * 一次性语义：只有「完整提交」成功时才把 token 标为 used；
+ * 少填必填项、订单状态变化、网络失败等都会在事务里回滚，链接继续可用。
+ */
+export async function submitPublicWorkOrderMaterialLink(token: string, payload: JsonObject = {}) {
+  const preliminary = await findWorkOrderMaterialLinkByToken(token)
+  if (!preliminary) {
+    throw createHttpError('链接无效，请确认链接是否完整', {
+      statusCode: 404,
+      errorCode: 'material_link_not_found',
+    })
+  }
+
+  const result = await withTransaction(async (client) => {
+    // 先锁工单再锁链接，和后台生成链接保持同样的加锁顺序，避免死锁。
+    const order = await getWorkOrderForUpdateWithClient(client, preliminary.work_order_id)
+    if (!order) {
+      throw createHttpError('接单订单不存在', {
+        statusCode: 404,
+        errorCode: 'work_order_not_found',
+      })
+    }
+    const link = await getWorkOrderMaterialLinkForUpdateWithClient(client, preliminary.id)
+    if (!link) {
+      throw createHttpError('链接无效，请确认链接是否完整', {
+        statusCode: 404,
+        errorCode: 'material_link_not_found',
+      })
+    }
+
+    // 锁到手后再取时间：等锁期间链接可能已经过期，不能沿用进入事务前的时间。
+    const now = nowIso()
+    assertMaterialLinkRecordUsable(link, now)
+    assertWorkOrderAllowedForMaterialLink(order)
+
+    const fields = resolveRequirementFields(order)
+    const submittedFields = pickSubmittedMaterialFields(
+      fields,
+      normalizeSubmittedFields(payload.fields || {}),
+    )
+    const missing = fields.filter(
+      (field) => field.required && !String(submittedFields[field.key] || '').trim(),
+    )
+    if (missing.length > 0) {
+      throw createHttpError(
+        `请填写完整必填资料：${missing.map((field) => field.label).join('、')}`,
+        {
+          statusCode: 400,
+          errorCode: 'material_link_fields_incomplete',
+          context: { missingFields: missing.map((field) => field.key) },
+        },
+      )
+    }
+
+    const screenshots = normalizeUploadedFiles(payload.screenshots || [])
+    if (screenshots.length > MAX_MATERIAL_SCREENSHOTS) {
+      throw createHttpError(`买家主页截图最多 ${MAX_MATERIAL_SCREENSHOTS} 张`, {
+        statusCode: 400,
+        errorCode: 'material_link_screenshots_too_many',
+      })
+    }
+
+    const material = {
+      ...safeParseJson(order.material_json),
+      collect: {
+        fields: submittedFields,
+        screenshots,
+        submittedAt: now,
+        complete: true,
+        source: 'customer_link',
+      },
+    }
+
+    const updated = await updateWorkOrderMaterialWithClient(client, {
+      workOrderId: order.id,
+      status: WORK_ORDER_STATUS.UNASSIGNED,
+      materialJson: JSON.stringify(material),
+      now,
+    })
+    if (!updated) {
+      throw createHttpError('更新订单资料失败，请稍后重试', {
+        statusCode: 500,
+        errorCode: 'material_link_update_failed',
+      })
+    }
+
+    const used = await markWorkOrderMaterialLinkUsedWithClient(client, link.id, now)
+    if (!used) {
+      // 并发提交，或刚好在写入瞬间过期：按当前状态给出准确原因，事务整体回滚。
+      const latest = await getWorkOrderMaterialLinkForUpdateWithClient(client, link.id)
+      if (latest) {
+        const reason = resolveWorkOrderMaterialLinkUnavailableReason(latest, now)
+        if (reason) throwMaterialLinkUnavailable(reason)
+      }
+      throwMaterialLinkUnavailable('used')
+    }
+
+    await createWorkOrderEventWithClient(client, {
+      workOrderId: order.id,
+      actorType: 'collect',
+      actorId: '客户补资料链接',
+      eventType: 'material_completed',
+      fromStatus: order.status,
+      toStatus: WORK_ORDER_STATUS.UNASSIGNED,
+      payloadJson: JSON.stringify({
+        fields: submittedFields,
+        complete: true,
+        source: 'customer_link',
+      }),
+      now,
+    })
+
+    return { order: updated, link: used }
+  })
+
+  // 事务已提交，后续通知/实时广播失败不能让客户误以为提交失败。
+  try {
+    await resolveAdminNotificationEntity(
+      'work_order',
+      Number(result.order.id),
+      'material_completed',
+    )
+  } catch (error) {
+    logWarn('[work-order-material-link]', '补资料完成通知处理失败', {
+      workOrderId: result.order.id,
+      error: error instanceof Error ? error.message : String(error),
+    })
+  }
+  publishWorkOrderRealtimeChange({ workOrderId: Number(result.order.id) })
+
+  return {
+    complete: true,
+    order: mapPublicOrder(result.order),
+  }
+}
+
+/**
+ * 上传前校验 token 与工单状态；返回工单 id 供文件归属使用。
+ * 注意：这里不消耗 token，只有最终提交才消耗。
+ */
+export async function getPublicWorkOrderMaterialLinkUploadContext(token: string) {
+  const link = await findWorkOrderMaterialLinkByToken(token)
+  if (!link) {
+    throw createHttpError('链接无效，请确认链接是否完整', {
+      statusCode: 404,
+      errorCode: 'material_link_not_found',
+    })
+  }
+
+  const now = nowIso()
+  assertMaterialLinkRecordUsable(link, now)
+
+  const order = await getRequiredWorkOrder(link.work_order_id)
+  assertWorkOrderAllowedForMaterialLink(order)
+
+  return { link, order, now }
+}
@@ -0,0 +1,41 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+import {
+  createDefaultWorkerMaterialLinkConfig,
+  normalizeWorkerMaterialLinkConfig,
+  WORK_ORDER_MATERIAL_LINK_DEFAULT_TTL_MINUTES,
+  WORK_ORDER_MATERIAL_LINK_MAX_TTL_MINUTES,
+  WORK_ORDER_MATERIAL_LINK_MIN_TTL_MINUTES,
+} from './worker-material-link-config-service.js'
+
+test('补资料链接配置：默认 30 分钟', () => {
+  assert.deepEqual(createDefaultWorkerMaterialLinkConfig(), {
+    ttlMinutes: WORK_ORDER_MATERIAL_LINK_DEFAULT_TTL_MINUTES,
+  })
+  assert.equal(WORK_ORDER_MATERIAL_LINK_DEFAULT_TTL_MINUTES, 30)
+  assert.deepEqual(normalizeWorkerMaterialLinkConfig(undefined), { ttlMinutes: 30 })
+})
+
+test('补资料链接配置：接受 ttlMinutes / ttl_minutes / 数字字符串', () => {
+  assert.deepEqual(normalizeWorkerMaterialLinkConfig({ ttlMinutes: 45 }), { ttlMinutes: 45 })
+  assert.deepEqual(normalizeWorkerMaterialLinkConfig({ ttl_minutes: '10' }), { ttlMinutes: 10 })
+  assert.deepEqual(normalizeWorkerMaterialLinkConfig({ ttlMinutes: 90.4 }), { ttlMinutes: 90 })
+})
+
+test('补资料链接配置：越界值收敛到 1 - 10080 分钟', () => {
+  assert.deepEqual(normalizeWorkerMaterialLinkConfig({ ttlMinutes: 0 }), {
+    ttlMinutes: WORK_ORDER_MATERIAL_LINK_MIN_TTL_MINUTES,
+  })
+  assert.deepEqual(normalizeWorkerMaterialLinkConfig({ ttlMinutes: -5 }), { ttlMinutes: 1 })
+  assert.deepEqual(normalizeWorkerMaterialLinkConfig({ ttlMinutes: 999999 }), {
+    ttlMinutes: WORK_ORDER_MATERIAL_LINK_MAX_TTL_MINUTES,
+  })
+  assert.equal(WORK_ORDER_MATERIAL_LINK_MAX_TTL_MINUTES, 10080)
+})
+
+test('补资料链接配置：非法输入回退默认值，不会写入 NaN', () => {
+  assert.deepEqual(normalizeWorkerMaterialLinkConfig({ ttlMinutes: 'abc' }), { ttlMinutes: 30 })
+  assert.deepEqual(normalizeWorkerMaterialLinkConfig({ ttlMinutes: null }), { ttlMinutes: 30 })
+  assert.deepEqual(normalizeWorkerMaterialLinkConfig('not-an-object'), { ttlMinutes: 30 })
+})
@@ -0,0 +1,62 @@
+import { APP_CONFIG_KEYS } from '../../config/app-config-keys.js'
+import type { JsonObject } from '../../types/json.js'
+import { readAppConfigEntry, saveAppConfigEntry } from '../config/app-config-store.js'
+
+/** 补资料链接默认有效期（分钟）：30 分钟。 */
+export const WORK_ORDER_MATERIAL_LINK_DEFAULT_TTL_MINUTES = 30
+/** 允许配置的最短有效期（分钟）。 */
+export const WORK_ORDER_MATERIAL_LINK_MIN_TTL_MINUTES = 1
+/** 允许配置的最长有效期（分钟）：7 天。 */
+export const WORK_ORDER_MATERIAL_LINK_MAX_TTL_MINUTES = 7 * 24 * 60
+
+export type WorkerMaterialLinkConfig = {
+  /** 新生成的补资料链接有效期，单位分钟。 */
+  ttlMinutes: number
+}
+
+/** 读取配置（内存缓存），未配置时返回默认 30 分钟。 */
+export function getWorkerMaterialLinkConfig(): WorkerMaterialLinkConfig {
+  return readAppConfigEntry({
+    configKey: APP_CONFIG_KEYS.workOrderMaterialLink,
+    fallback: createDefaultWorkerMaterialLinkConfig,
+    normalize: normalizeWorkerMaterialLinkConfig,
+  })
+}
+
+export async function saveWorkerMaterialLinkConfig(
+  rawValue: unknown,
+): Promise<WorkerMaterialLinkConfig> {
+  return saveAppConfigEntry({
+    configKey: APP_CONFIG_KEYS.workOrderMaterialLink,
+    value: rawValue,
+    normalize: normalizeWorkerMaterialLinkConfig,
+  })
+}
+
+export function createDefaultWorkerMaterialLinkConfig(): WorkerMaterialLinkConfig {
+  return { ttlMinutes: WORK_ORDER_MATERIAL_LINK_DEFAULT_TTL_MINUTES }
+}
+
+export function normalizeWorkerMaterialLinkConfig(rawValue: unknown): WorkerMaterialLinkConfig {
+  const source = isPlainObject(rawValue) ? rawValue : {}
+  const raw = source.ttlMinutes ?? source.ttl_minutes
+  if (raw === undefined || raw === null || raw === '') {
+    return createDefaultWorkerMaterialLinkConfig()
+  }
+
+  const value = Number(raw)
+  if (!Number.isFinite(value)) {
+    return createDefaultWorkerMaterialLinkConfig()
+  }
+
+  return {
+    ttlMinutes: Math.min(
+      WORK_ORDER_MATERIAL_LINK_MAX_TTL_MINUTES,
+      Math.max(WORK_ORDER_MATERIAL_LINK_MIN_TTL_MINUTES, Math.round(value)),
+    ),
+  }
+}
+
+function isPlainObject(value: unknown): value is JsonObject {
+  return Object.prototype.toString.call(value) === '[object Object]'
+}