把 task 的 helper独立出来了

apps/backend/src/routes/admin/dashboard.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 import { Router } from 'express'
 
 import { getAdminDashboardSummary } from '../../services/admin/admin-dashboard-service.js'

apps/backend/src/routes/admin/inventory.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 import { Router } from 'express'
 
 import {
@@ -12,12 +14,20 @@ import {
 } from '../../services/admin/admin-read-service.js'
 import { createJsonHandler, requireAdminRoles } from './shared.js'
 
+/** @typedef {import('../../types/admin-route-inputs.js').AdminInventoryCreateRouteBody} AdminInventoryCreateRouteBody */
+/** @typedef {import('../../types/admin-route-inputs.js').AdminInventoryImportRouteBody} AdminInventoryImportRouteBody */
+/** @typedef {import('../../types/admin-route-inputs.js').AdminInventoryInvalidateRouteBody} AdminInventoryInvalidateRouteBody */
+/** @typedef {import('../../types/admin-route-inputs.js').AdminInventoryRouteParams} AdminInventoryRouteParams */
+/** @typedef {import('../../types/admin-route-inputs.js').AdminInventoryRouteQuery} AdminInventoryRouteQuery */
+/** @typedef {import('../../types/admin-route-inputs.js').AdminInventorySkuSuggestionRouteQuery} AdminInventorySkuSuggestionRouteQuery */
+/** @typedef {import('../../types/admin-write-models.js').AdminInventoryMutationResponse} AdminInventoryMutationResponse */
+
 const router = Router()
 
 router.use('/inventory', requireAdminRoles(['admin', 'operator']))
 
 router.get('/inventory', createJsonHandler(
-  (req) => getAdminInventoryItems(req.query),
+  (req) => getAdminInventoryItems(/** @type {AdminInventoryRouteQuery} */ (req.query)),
   {
     successMessage: 'ok',
     errorMessage: '读取库存列表失败',
@@ -26,7 +36,7 @@ router.get('/inventory', createJsonHandler(
 ))
 
 router.get('/inventory/sku-suggestions', createJsonHandler(
-  (req) => getAdminInventorySkuSuggestions(req.query),
+  (req) => getAdminInventorySkuSuggestions(/** @type {AdminInventorySkuSuggestionRouteQuery} */ (req.query)),
   {
     successMessage: 'ok',
     errorMessage: '读取内部 SKU 建议失败',
@@ -35,7 +45,7 @@ router.get('/inventory/sku-suggestions', createJsonHandler(
 ))
 
 router.post('/inventory', createJsonHandler(
-  (req) => createAdminInventoryItem(req.body),
+  (req) => createAdminInventoryItem(/** @type {AdminInventoryCreateRouteBody} */ (req.body)),
   {
     successMessage: '库存项已新增',
     errorMessage: '新增库存项失败',
@@ -44,7 +54,7 @@ router.post('/inventory', createJsonHandler(
 ))
 
 router.post('/inventory/import', createJsonHandler(
-  (req) => importAdminInventoryItems(req.body),
+  (req) => importAdminInventoryItems(/** @type {AdminInventoryImportRouteBody} */ (req.body)),
   {
     successMessage: '导入完成',
     errorMessage: '导入库存凭据失败',
@@ -53,40 +63,49 @@ router.post('/inventory/import', createJsonHandler(
 ))
 
 router.post('/inventory/:inventoryItemId/release', requireAdminRoles(['admin']), createJsonHandler(
-  (req) => releaseAdminInventoryItem(req.params.inventoryItemId),
+  (req) => releaseAdminInventoryItem((/** @type {AdminInventoryRouteParams} */ (req.params)).inventoryItemId),
   {
     successMessage: '库存项已释放',
     errorMessage: '释放库存项失败',
     scope: '[admin/inventory/:inventoryItemId/release]',
-    audit: (req, data) => ({
+    audit: (req, data) => {
+      const result = /** @type {AdminInventoryMutationResponse} */ (data)
+      return {
       action: 'inventory_item_released',
       targetType: 'inventory_item',
-      targetId: String(req.params.inventoryItemId),
+      targetId: String((/** @type {AdminInventoryRouteParams} */ (req.params)).inventoryItemId),
       data: {
-        inventoryItemId: data.inventoryItem?.inventoryItemId,
+        inventoryItemId: result.inventoryItem?.inventoryItemId,
-        skuCode: data.inventoryItem?.skuCode,
+        skuCode: result.inventoryItem?.skuCode,
-        displayValue: data.inventoryItem?.displayValue,
+        displayValue: result.inventoryItem?.displayValue,
+      },
+      }
     },
-    }),
   },
 ))
 
 router.post('/inventory/:inventoryItemId/invalidate', requireAdminRoles(['admin']), createJsonHandler(
-  (req) => invalidateAdminInventoryItem(req.params.inventoryItemId, req.body),
+  (req) => invalidateAdminInventoryItem(
+    (/** @type {AdminInventoryRouteParams} */ (req.params)).inventoryItemId,
+    /** @type {AdminInventoryInvalidateRouteBody} */ (req.body),
+  ),
   {
     successMessage: '库存项已作废',
     errorMessage: '作废库存项失败',
     scope: '[admin/inventory/:inventoryItemId/invalidate]',
-    audit: (req, data) => ({
+    audit: (req, data) => {
+      const result = /** @type {AdminInventoryMutationResponse} */ (data)
+      return {
       action: 'inventory_item_invalidated',
       targetType: 'inventory_item',
-      targetId: String(req.params.inventoryItemId),
+      targetId: String((/** @type {AdminInventoryRouteParams} */ (req.params)).inventoryItemId),
       data: {
-        inventoryItemId: data.inventoryItem?.inventoryItemId,
+        inventoryItemId: result.inventoryItem?.inventoryItemId,
-        skuCode: data.inventoryItem?.skuCode,
+        skuCode: result.inventoryItem?.skuCode,
-        invalidReason: data.inventoryItem?.invalidReason,
+        invalidReason: result.inventoryItem?.invalidReason,
+      },
+      }
     },
-    }),
   },
 ))
 

apps/backend/src/routes/admin/message-deliveries.js

@@ -1,12 +1,16 @@
+// @ts-check
+
 import { Router } from 'express'
 
 import { getAdminMessageDeliveries } from '../../services/admin/admin-message-delivery-service.js'
 import { createJsonHandler } from './shared.js'
 
+/** @typedef {import('../../types/admin-route-inputs.js').AdminMessageDeliveryRouteQuery} AdminMessageDeliveryRouteQuery */
+
 const router = Router()
 
 router.get('/message-deliveries', createJsonHandler(
-  (req) => getAdminMessageDeliveries(req.query),
+  (req) => getAdminMessageDeliveries(/** @type {AdminMessageDeliveryRouteQuery} */ (req.query)),
   {
     successMessage: 'ok',
     errorMessage: '读取消息发送记录失败',

apps/backend/src/routes/admin/orders.js

@@ -1,12 +1,17 @@
+// @ts-check
+
 import { Router } from 'express'
 
 import { getAdminOrderDetail, getAdminOrders } from '../../services/admin/admin-read-service.js'
 import { createJsonHandler } from './shared.js'
 
+/** @typedef {import('../../types/admin-route-inputs.js').AdminOrderRouteParams} AdminOrderRouteParams */
+/** @typedef {import('../../types/admin-route-inputs.js').AdminOrderRouteQuery} AdminOrderRouteQuery */
+
 const router = Router()
 
 router.get('/orders', createJsonHandler(
-  (req) => getAdminOrders(req.query),
+  (req) => getAdminOrders(/** @type {AdminOrderRouteQuery} */ (req.query)),
   {
     successMessage: 'ok',
     errorMessage: '读取订单列表失败',
@@ -15,7 +20,7 @@ router.get('/orders', createJsonHandler(
 ))
 
 router.get('/orders/:orderId', createJsonHandler(
-  (req) => getAdminOrderDetail(req.params.orderId),
+  (req) => getAdminOrderDetail((/** @type {AdminOrderRouteParams} */ (req.params)).orderId),
   {
     successMessage: 'ok',
     errorMessage: '读取订单详情失败',

apps/backend/src/routes/admin/platform-config.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 import { Router } from 'express'
 
 import {
@@ -9,6 +11,11 @@ import {
 } from '../../services/admin/admin-platform-config-service.js'
 import { createJsonHandler, requireAdminRoles } from './shared.js'
 
+/** @typedef {import('../../types/admin-route-inputs.js').AdminAgisoShopConfigRouteBody} AdminAgisoShopConfigRouteBody */
+/** @typedef {import('../../types/admin-route-inputs.js').AdminFulfillmentBindingConfigRouteBody} AdminFulfillmentBindingConfigRouteBody */
+/** @typedef {import('../../types/admin-route-inputs.js').AdminFulfillmentBindingLookupRouteBody} AdminFulfillmentBindingLookupRouteBody */
+/** @typedef {import('../../types/admin-write-models.js').AdminAgisoShopConfigSaveResponse} AdminAgisoShopConfigSaveResponse */
+
 const router = Router()
 
 router.use('/platform-config', requireAdminRoles(['admin']))
@@ -23,20 +30,23 @@ router.get('/platform-config/agiso-shops', createJsonHandler(
 ))
 
 router.post('/platform-config/agiso-shops', createJsonHandler(
-  (req) => updateAdminAgisoShopConfigs(req.body),
+  (req) => updateAdminAgisoShopConfigs(/** @type {AdminAgisoShopConfigRouteBody} */ (req.body)),
   {
     successMessage: 'Agiso 店铺配置已保存',
     errorMessage: '保存 Agiso 店铺配置失败',
     scope: '[admin/platform-config/agiso-shops]',
-    audit: (_req, data) => ({
+    audit: (_req, data) => {
+      const result = /** @type {AdminAgisoShopConfigSaveResponse} */ (data)
+      return {
         action: 'platform_shop_config_updated',
         targetType: 'platform_config',
         targetId: 'agiso_shops',
         data: {
-        shopCount: data.shops.length,
+          shopCount: result.shops.length,
-        filePath: data.filePath,
+          filePath: result.filePath,
+        },
+      }
     },
-    }),
   },
 ))
 
@@ -50,44 +60,50 @@ router.get('/platform-config/fulfillment-bindings', createJsonHandler(
 ))
 
 router.post('/platform-config/fulfillment-bindings/lookup-order', createJsonHandler(
-  (req) => lookupAdminFulfillmentBindingOrder(req.body),
+  (req) => lookupAdminFulfillmentBindingOrder(/** @type {AdminFulfillmentBindingLookupRouteBody} */ (req.body)),
   {
     successMessage: '订单商品查询成功',
     errorMessage: '手动查询订单商品失败',
     scope: '[admin/platform-config/fulfillment-bindings/lookup-order]',
-    audit: (req, data) => ({
+    audit: (req, data) => {
+      const result = /** @type {{ order?: { provider?: string, platform?: string, shopId?: string, platformOrderId?: string }, items?: unknown[] }} */ (data)
+      return {
         action: 'platform_fulfillment_order_lookup',
         targetType: 'platform_config',
         targetId: [
-        data.order?.provider || 'unknown',
+          result.order?.provider || 'unknown',
-        data.order?.platform || 'unknown',
+          result.order?.platform || 'unknown',
-        data.order?.shopId || 'unknown',
+          result.order?.shopId || 'unknown',
-        data.order?.platformOrderId || 'unknown',
+          result.order?.platformOrderId || 'unknown',
         ].join(':'),
         data: {
-        itemCount: Array.isArray(data.items) ? data.items.length : 0,
+          itemCount: Array.isArray(result.items) ? result.items.length : 0,
-        shopId: data.order?.shopId || String(req.body?.shopId || '').trim(),
+          shopId: result.order?.shopId || String((/** @type {AdminFulfillmentBindingLookupRouteBody} */ (req.body))?.shopId || '').trim(),
-        platformOrderId: data.order?.platformOrderId || String(req.body?.platformOrderId || '').trim(),
+          platformOrderId: result.order?.platformOrderId || String((/** @type {AdminFulfillmentBindingLookupRouteBody} */ (req.body))?.platformOrderId || '').trim(),
+        },
+      }
     },
-    }),
   },
 ))
 
 router.post('/platform-config/fulfillment-bindings', createJsonHandler(
-  (req) => updateAdminFulfillmentBindingConfigs(req.body),
+  (req) => updateAdminFulfillmentBindingConfigs(/** @type {AdminFulfillmentBindingConfigRouteBody} */ (req.body)),
   {
     successMessage: '履约配置已保存',
     errorMessage: '保存履约配置失败',
     scope: '[admin/platform-config/fulfillment-bindings]',
-    audit: (_req, data) => ({
+    audit: (_req, data) => {
+      const result = /** @type {{ bindings?: unknown[], filePath?: string }} */ (data)
+      return {
         action: 'platform_fulfillment_config_updated',
         targetType: 'platform_config',
         targetId: 'fulfillment_bindings',
         data: {
-        bindingCount: data.bindings.length,
+          bindingCount: Array.isArray(result.bindings) ? result.bindings.length : 0,
-        filePath: data.filePath,
+          filePath: result.filePath || '',
+        },
+      }
     },
-    }),
   },
 ))
 

apps/backend/src/routes/admin/shared.js

@@ -1,8 +1,45 @@
+// @ts-check
+
 import { requireAdminRole, verifyAdminSessionToken } from '../../services/admin/admin-auth-service.js'
 import { writeAdminAuditLog } from '../../services/admin/admin-audit-service.js'
 import { buildSuccessPayload, createHttpError, sendRouteError } from '../../utils/http.js'
 import { logWarn } from '../../utils/logger.js'
 
+/** @typedef {import('express').NextFunction} NextFunction */
+/** @typedef {import('express').Request} ExpressRequest */
+/** @typedef {import('express').Response} ExpressResponse */
+/** @typedef {import('../../types/admin-route-inputs.js').AdminRouteAdminSession} AdminRouteAdminSession */
+/** @typedef {ExpressRequest & { adminSession?: AdminRouteAdminSession | null }} AdminExpressRequest */
+
+/**
+ * @typedef {{
+ *   action?: string
+ *   targetType?: string
+ *   targetId?: string
+ *   data?: Record<string, unknown>
+ * }} AdminAuditPayload
+ */
+
+/**
+ * @typedef {{
+ *   successMessage?: string
+ *   errorMessage?: string
+ *   scope?: string
+ *   audit?: (req: AdminExpressRequest, data: unknown) => (AdminAuditPayload | null | undefined)
+ * }} AdminJsonHandlerOptions
+ */
+
+/**
+ * @typedef {{
+ *   errorMessage?: string
+ *   scope?: string
+ * }} AdminFileHandlerOptions
+ */
+
+/**
+ * @param {(req: AdminExpressRequest, res: ExpressResponse) => unknown | Promise<unknown>} action
+ * @param {AdminJsonHandlerOptions} [options]
+ */
 export function createJsonHandler(action, { successMessage = 'ok', errorMessage, scope, audit } = {}) {
   return async (req, res) => {
     try {
@@ -15,6 +52,10 @@ export function createJsonHandler(action, { successMessage = 'ok', errorMessage,
   }
 }
 
+/**
+ * @param {(req: AdminExpressRequest, res: ExpressResponse) => string | Promise<string>} action
+ * @param {AdminFileHandlerOptions} [options]
+ */
 export function createFileHandler(action, { errorMessage, scope } = {}) {
   return async (req, res) => {
     try {
@@ -26,6 +67,9 @@ export function createFileHandler(action, { errorMessage, scope } = {}) {
   }
 }
 
+/** @param {AdminExpressRequest} req */
+/** @param {ExpressResponse} res */
+/** @param {NextFunction} next */
 export async function requireAdminSession(req, res, next) {
   try {
     req.adminSession = await verifyAdminSessionToken(extractBearerToken(req))
@@ -35,6 +79,7 @@ export async function requireAdminSession(req, res, next) {
   }
 }
 
+/** @param {string[]} allowedRoles */
 export function requireAdminRoles(allowedRoles) {
   return (req, res, next) => {
     try {

apps/backend/src/routes/admin/tasks.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 import { Router } from 'express'
 
 import {
@@ -18,10 +20,21 @@ import {
 } from '../../services/admin/admin-read-service.js'
 import { createFileHandler, createJsonHandler, requireAdminRoles } from './shared.js'
 
+/** @typedef {import('../../types/admin-route-inputs.js').AdminRouteAdminSession} AdminRouteAdminSession */
+/** @typedef {import('../../types/admin-route-inputs.js').AdminTaskManualDispatchRouteBody} AdminTaskManualDispatchRouteBody */
+/** @typedef {import('../../types/admin-route-inputs.js').AdminTaskRouteParams} AdminTaskRouteParams */
+/** @typedef {import('../../types/admin-route-inputs.js').AdminTaskRouteQuery} AdminTaskRouteQuery */
+/** @typedef {import('../../types/admin-write-models.js').AdminTaskActionResponse} AdminTaskActionResponse */
+/** @typedef {import('../../types/admin-write-models.js').AdminTaskBindingReleaseResponse} AdminTaskBindingReleaseResponse */
+/** @typedef {import('../../types/admin-write-models.js').AdminTaskManualDispatchResponse} AdminTaskManualDispatchResponse */
+
 const router = Router()
 
 router.get('/tasks', createJsonHandler(
-  (req) => getAdminTasks(req.query, req.adminSession),
+  (req) => getAdminTasks(
+    /** @type {AdminTaskRouteQuery} */ (req.query),
+    /** @type {AdminRouteAdminSession | null} */ (req.adminSession),
+  ),
   {
     successMessage: 'ok',
     errorMessage: '读取任务列表失败',
@@ -30,7 +43,10 @@ router.get('/tasks', createJsonHandler(
 ))
 
 router.get('/tasks/:taskId', createJsonHandler(
-  (req) => getAdminTaskDetail(req.params.taskId, req.adminSession),
+  (req) => getAdminTaskDetail(
+    (/** @type {AdminTaskRouteParams} */ (req.params)).taskId,
+    /** @type {AdminRouteAdminSession | null} */ (req.adminSession),
+  ),
   {
     successMessage: 'ok',
     errorMessage: '读取任务详情失败',
@@ -39,7 +55,10 @@ router.get('/tasks/:taskId', createJsonHandler(
 ))
 
 router.get('/tasks/:taskId/screenshot', createFileHandler(
-  (req) => getAdminTaskScreenshotPath(req.params.taskId, req.adminSession),
+  (req) => getAdminTaskScreenshotPath(
+    (/** @type {AdminTaskRouteParams} */ (req.params)).taskId,
+    /** @type {AdminRouteAdminSession | null} */ (req.adminSession),
+  ),
   {
     errorMessage: '读取任务截图失败',
     scope: '[admin/tasks/:taskId/screenshot]',
@@ -47,7 +66,7 @@ router.get('/tasks/:taskId/screenshot', createFileHandler(
 ))
 
 router.post('/tasks/:taskId/retry', requireAdminRoles(['admin', 'operator']), createJsonHandler(
-  (req) => retryAdminTask(req.params.taskId),
+  (req) => retryAdminTask((/** @type {AdminTaskRouteParams} */ (req.params)).taskId),
   {
     successMessage: '任务已重试',
     errorMessage: '重试任务失败',
@@ -56,158 +75,198 @@ router.post('/tasks/:taskId/retry', requireAdminRoles(['admin', 'operator']), cr
 ))
 
 router.post('/tasks/:taskId/release-inventory', requireAdminRoles(['admin']), createJsonHandler(
-  (req) => releaseAdminTaskInventory(req.params.taskId),
+  (req) => releaseAdminTaskInventory((/** @type {AdminTaskRouteParams} */ (req.params)).taskId),
   {
     successMessage: '库存凭据已释放',
     errorMessage: '释放库存凭据失败',
     scope: '[admin/tasks/:taskId/release-inventory]',
-    audit: (req, data) => ({
+    audit: (req, data) => {
+      const result = /** @type {AdminTaskActionResponse} */ (data)
+      return {
       action: 'task_release_inventory',
       targetType: 'task',
-      targetId: String(req.params.taskId),
+      targetId: String((/** @type {AdminTaskRouteParams} */ (req.params)).taskId),
       data: {
-        taskId: data.task.taskId,
+        taskId: result.task.taskId,
-        taskNo: data.task.taskNo,
+        taskNo: result.task.taskNo,
-        inventoryItemId: data.task.inventoryItemId,
+        inventoryItemId: result.task.inventoryItemId,
+      },
+      }
     },
-    }),
   },
 ))
 
 router.post('/tasks/:taskId/inventory-bindings/:bindingId/release', requireAdminRoles(['admin']), createJsonHandler(
-  (req) => releaseAdminTaskInventoryBinding(req.params.taskId, req.params.bindingId),
+  (req) => releaseAdminTaskInventoryBinding(
+    (/** @type {AdminTaskRouteParams} */ (req.params)).taskId,
+    (/** @type {AdminTaskRouteParams} */ (req.params)).bindingId,
+  ),
   {
     successMessage: '库存绑定已释放',
     errorMessage: '释放库存绑定失败',
     scope: '[admin/tasks/:taskId/inventory-bindings/:bindingId/release]',
-    audit: (req, data) => ({
+    audit: (req, data) => {
+      const result = /** @type {AdminTaskBindingReleaseResponse} */ (data)
+      return {
       action: 'task_release_inventory_binding',
       targetType: 'task_inventory_binding',
-      targetId: String(req.params.bindingId),
+      targetId: String((/** @type {AdminTaskRouteParams} */ (req.params)).bindingId),
       data: {
-        taskId: data.task.taskId,
+        taskId: result.task.taskId,
-        taskNo: data.task.taskNo,
+        taskNo: result.task.taskNo,
-        bindingId: data.bindingId,
+        bindingId: result.bindingId,
-        inventoryItemId: data.inventoryItemId,
+        inventoryItemId: result.inventoryItemId,
+      },
+      }
     },
-    }),
   },
 ))
 
 router.post('/tasks/:taskId/regenerate-claim-link', requireAdminRoles(['admin', 'operator', 'support']), createJsonHandler(
-  (req) => regenerateAdminTaskClaimLink(req.params.taskId, req.adminSession),
+  (req) => regenerateAdminTaskClaimLink(
+    (/** @type {AdminTaskRouteParams} */ (req.params)).taskId,
+    /** @type {AdminRouteAdminSession | null} */ (req.adminSession),
+  ),
   {
     successMessage: '领取链接已重新生成',
     errorMessage: '重新生成领取链接失败',
     scope: '[admin/tasks/:taskId/regenerate-claim-link]',
-    audit: (req, data) => ({
+    audit: (req, data) => {
+      const result = /** @type {AdminTaskActionResponse} */ (data)
+      return {
       action: 'task_regenerate_claim_link',
       targetType: 'task',
-      targetId: String(req.params.taskId),
+      targetId: String((/** @type {AdminTaskRouteParams} */ (req.params)).taskId),
       data: {
-        taskId: data.task.taskId,
+        taskId: result.task.taskId,
-        taskNo: data.task.taskNo,
+        taskNo: result.task.taskNo,
-        primaryClaimTokenId: data.task.primaryClaimTokenId,
+        primaryClaimTokenId: result.task.primaryClaimTokenId,
+      },
+      }
     },
-    }),
   },
 ))
 
 router.post('/tasks/:taskId/support-confirm-role', requireAdminRoles(['admin', 'operator', 'support']), createJsonHandler(
-  (req) => confirmAdminTaskAssistedRole(req.params.taskId, req.adminSession),
+  (req) => confirmAdminTaskAssistedRole(
+    (/** @type {AdminTaskRouteParams} */ (req.params)).taskId,
+    /** @type {AdminRouteAdminSession | null} */ (req.adminSession),
+  ),
   {
     successMessage: '角色已确认',
     errorMessage: '客服确认角色失败',
     scope: '[admin/tasks/:taskId/support-confirm-role]',
-    audit: (req, data) => ({
+    audit: (req, data) => {
+      const result = /** @type {AdminTaskActionResponse} */ (data)
+      return {
       action: 'task_support_confirm_role',
       targetType: 'task',
-      targetId: String(req.params.taskId),
+      targetId: String((/** @type {AdminTaskRouteParams} */ (req.params)).taskId),
       data: {
-        taskId: data.task.taskId,
+        taskId: result.task.taskId,
-        taskNo: data.task.taskNo,
+        taskNo: result.task.taskNo,
-        status: data.task.status,
+        status: result.task.status,
+      },
+      }
     },
-    }),
   },
 ))
 
 router.post('/tasks/:taskId/support-redeem', requireAdminRoles(['admin', 'operator', 'support']), createJsonHandler(
-  (req) => redeemAdminTaskAssisted(req.params.taskId, req.adminSession),
+  (req) => redeemAdminTaskAssisted(
+    (/** @type {AdminTaskRouteParams} */ (req.params)).taskId,
+    /** @type {AdminRouteAdminSession | null} */ (req.adminSession),
+  ),
   {
     successMessage: '兑换任务已启动',
     errorMessage: '客服发起兑换失败',
     scope: '[admin/tasks/:taskId/support-redeem]',
-    audit: (req, data) => ({
+    audit: (req, data) => {
+      const result = /** @type {AdminTaskActionResponse} */ (data)
+      return {
       action: 'task_support_redeem',
       targetType: 'task',
-      targetId: String(req.params.taskId),
+      targetId: String((/** @type {AdminTaskRouteParams} */ (req.params)).taskId),
       data: {
-        taskId: data.task.taskId,
+        taskId: result.task.taskId,
-        taskNo: data.task.taskNo,
+        taskNo: result.task.taskNo,
-        status: data.task.status,
+        status: result.task.status,
-        deliveryStatus: data.task.deliveryStatus,
+        deliveryStatus: result.task.deliveryStatus,
+      },
+      }
     },
-    }),
   },
 ))
 
 router.post('/tasks/:taskId/close', requireAdminRoles(['admin', 'operator']), createJsonHandler(
-  (req) => closeAdminTask(req.params.taskId),
+  (req) => closeAdminTask((/** @type {AdminTaskRouteParams} */ (req.params)).taskId),
   {
     successMessage: '任务已关闭',
     errorMessage: '关闭任务失败',
     scope: '[admin/tasks/:taskId/close]',
-    audit: (req, data) => ({
+    audit: (req, data) => {
+      const result = /** @type {AdminTaskActionResponse} */ (data)
+      return {
       action: 'task_closed',
       targetType: 'task',
-      targetId: String(req.params.taskId),
+      targetId: String((/** @type {AdminTaskRouteParams} */ (req.params)).taskId),
       data: {
-        taskId: data.task.taskId,
+        taskId: result.task.taskId,
-        taskNo: data.task.taskNo,
+        taskNo: result.task.taskNo,
-        status: data.task.status,
+        status: result.task.status,
+      },
+      }
     },
-    }),
   },
 ))
 
 router.post('/tasks/:taskId/mark-manual-review', requireAdminRoles(['admin', 'operator']), createJsonHandler(
-  (req) => markAdminTaskManualReview(req.params.taskId),
+  (req) => markAdminTaskManualReview((/** @type {AdminTaskRouteParams} */ (req.params)).taskId),
   {
     successMessage: '任务已转人工处理',
     errorMessage: '标记人工处理失败',
     scope: '[admin/tasks/:taskId/mark-manual-review]',
-    audit: (req, data) => ({
+    audit: (req, data) => {
+      const result = /** @type {AdminTaskActionResponse} */ (data)
+      return {
       action: 'task_mark_manual_review',
       targetType: 'task',
-      targetId: String(req.params.taskId),
+      targetId: String((/** @type {AdminTaskRouteParams} */ (req.params)).taskId),
       data: {
-        taskId: data.task.taskId,
+        taskId: result.task.taskId,
-        taskNo: data.task.taskNo,
+        taskNo: result.task.taskNo,
-        status: data.task.status,
+        status: result.task.status,
+      },
+      }
     },
-    }),
   },
 ))
 
 router.post('/tasks/:taskId/complete-manual-dispatch', requireAdminRoles(['admin', 'operator']), createJsonHandler(
-  (req) => completeAdminTaskManualDispatch(req.params.taskId, req.body, req.adminSession),
+  (req) => completeAdminTaskManualDispatch(
+    (/** @type {AdminTaskRouteParams} */ (req.params)).taskId,
+    /** @type {AdminTaskManualDispatchRouteBody} */ (req.body),
+    /** @type {AdminRouteAdminSession | null} */ (req.adminSession),
+  ),
   {
     successMessage: '人工履约结果已回写',
     errorMessage: '回写人工履约结果失败',
     scope: '[admin/tasks/:taskId/complete-manual-dispatch]',
-    audit: (req, data) => ({
+    audit: (req, data) => {
+      const result = /** @type {AdminTaskManualDispatchResponse} */ (data)
+      return {
       action: 'task_complete_manual_dispatch',
       targetType: 'task',
-      targetId: String(req.params.taskId),
+      targetId: String((/** @type {AdminTaskRouteParams} */ (req.params)).taskId),
       data: {
-        taskId: data.task.taskId,
+        taskId: result.task.taskId,
-        taskNo: data.task.taskNo,
+        taskNo: result.task.taskNo,
-        outcome: data.outcome,
+        outcome: result.outcome,
-        deliveryStatus: data.task.deliveryStatus,
+        deliveryStatus: result.task.deliveryStatus,
-        resultCode: data.task.resultCode,
+        resultCode: result.task.resultCode,
+      },
+      }
     },
-    }),
   },
 ))
 

apps/backend/src/routes/admin/webhook-events.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 import { Router } from 'express'
 
 import {
@@ -9,12 +11,16 @@ import {
 } from '../../services/admin/admin-read-service.js'
 import { createJsonHandler, requireAdminRoles } from './shared.js'
 
+/** @typedef {import('../../types/admin-route-inputs.js').AdminWebhookEventRouteParams} AdminWebhookEventRouteParams */
+/** @typedef {import('../../types/admin-route-inputs.js').AdminWebhookEventRouteQuery} AdminWebhookEventRouteQuery */
+/** @typedef {import('../../types/admin-write-models.js').AdminWebhookReplayResponse} AdminWebhookReplayResponse */
+
 const router = Router()
 
 router.use('/webhook-events', requireAdminRoles(['admin', 'operator']))
 
 router.get('/webhook-events', createJsonHandler(
-  (req) => getAdminWebhookEvents(req.query),
+  (req) => getAdminWebhookEvents(/** @type {AdminWebhookEventRouteQuery} */ (req.query)),
   {
     successMessage: 'ok',
     errorMessage: '读取 webhook 列表失败',
@@ -23,7 +29,7 @@ router.get('/webhook-events', createJsonHandler(
 ))
 
 router.get('/webhook-events/:eventId', createJsonHandler(
-  (req) => getAdminWebhookEventDetail(req.params.eventId),
+  (req) => getAdminWebhookEventDetail((/** @type {AdminWebhookEventRouteParams} */ (req.params)).eventId),
   {
     successMessage: 'ok',
     errorMessage: '读取 webhook 详情失败',
@@ -32,20 +38,23 @@ router.get('/webhook-events/:eventId', createJsonHandler(
 ))
 
 router.post('/webhook-events/:eventId/replay', requireAdminRoles(['admin']), createJsonHandler(
-  (req) => replayAdminWebhookEvent(req.params.eventId),
+  (req) => replayAdminWebhookEvent((/** @type {AdminWebhookEventRouteParams} */ (req.params)).eventId),
   {
     successMessage: 'Webhook 已重放',
     errorMessage: '重放 webhook 失败',
     scope: '[admin/webhook-events/:eventId/replay]',
-    audit: (req, data) => ({
+    audit: (req, data) => {
+      const result = /** @type {AdminWebhookReplayResponse} */ (data)
+      return {
       action: 'webhook_replayed',
       targetType: 'webhook_event',
-      targetId: String(req.params.eventId),
+      targetId: String((/** @type {AdminWebhookEventRouteParams} */ (req.params)).eventId),
       data: {
-        eventId: data.eventId,
+        eventId: result.eventId,
-        replayed: data.replayed,
+        replayed: result.replayed,
+      },
+      }
     },
-    }),
   },
 ))
 

apps/backend/src/services/admin/admin-message-delivery-service.js

@@ -3,7 +3,10 @@
 import { listMessageDeliveries } from '../../repositories/message-delivery-repo.js'
 import { normalizeDateQuery, normalizePage, normalizePageSize, safeParseJson } from './admin-query-utils.js'
 
-export async function getAdminMessageDeliveries(query = {}) {
+/** @typedef {import('../../types/admin-read-inputs.js').AdminMessageDeliveryListQueryInput} AdminMessageDeliveryListQueryInput */
+
+/** @param {AdminMessageDeliveryListQueryInput} [query] */
+export async function getAdminMessageDeliveries(query = /** @type {AdminMessageDeliveryListQueryInput} */ ({})) {
   const page = normalizePage(query.page)
   const pageSize = normalizePageSize(query.pageSize)
   const { items, total } = await listMessageDeliveries({

apps/backend/src/services/admin/admin-platform-config-service.js

@@ -18,7 +18,11 @@ import { createHttpError } from '../../utils/http.js'
 import { formatFenToAmount } from '../../utils/money.js'
 import { syncConfiguredFulfillmentBindings } from '../bootstrap/fulfillment-bootstrap-service.js'
 import { normalizeProductName } from '../order/product-match-service.js'
-import { resolveDisplayShopName } from './admin-read-helpers.js'
+import { resolveDisplayShopName } from './admin-read-shared-helpers.js'
+
+/** @typedef {import('../../types/admin-write-inputs.js').AdminAgisoShopConfigSaveInput} AdminAgisoShopConfigSaveInput */
+/** @typedef {import('../../types/admin-write-inputs.js').AdminFulfillmentBindingConfigSaveInput} AdminFulfillmentBindingConfigSaveInput */
+/** @typedef {import('../../types/admin-write-inputs.js').AdminFulfillmentBindingLookupInput} AdminFulfillmentBindingLookupInput */
 
 export async function getAdminAgisoShopConfigs() {
   const configMap = getAgisoShopConfigMap()
@@ -63,7 +67,8 @@ export async function getAdminAgisoShopConfigs() {
   }
 }
 
-export function updateAdminAgisoShopConfigs(payload = {}) {
+/** @param {AdminAgisoShopConfigSaveInput} [payload] */
+export function updateAdminAgisoShopConfigs(payload = /** @type {AdminAgisoShopConfigSaveInput} */ ({})) {
   const rawItems = Array.isArray(payload.shops) ? payload.shops : []
   const nextMap = {}
 
@@ -179,7 +184,8 @@ export async function getAdminFulfillmentBindingConfigs() {
   }
 }
 
-export async function lookupAdminFulfillmentBindingOrder(payload = {}) {
+/** @param {AdminFulfillmentBindingLookupInput} [payload] */
+export async function lookupAdminFulfillmentBindingOrder(payload = /** @type {AdminFulfillmentBindingLookupInput} */ ({})) {
   const provider = String(payload.provider || 'agiso').trim() || 'agiso'
   const platform = String(payload.platform || 'xianyu').trim() || 'xianyu'
   const shopId = String(payload.shopId || '').trim()
@@ -302,7 +308,10 @@ export async function lookupAdminFulfillmentBindingOrder(payload = {}) {
   }
 }
 
-export async function updateAdminFulfillmentBindingConfigs(payload = {}) {
+/** @param {AdminFulfillmentBindingConfigSaveInput} [payload] */
+export async function updateAdminFulfillmentBindingConfigs(
+  payload = /** @type {AdminFulfillmentBindingConfigSaveInput} */ ({}),
+) {
   const bindingsInput = Array.isArray(payload.bindings) ? payload.bindings : []
   await validateAdminFulfillmentBindingConfigs(bindingsInput)
   const saved = saveOrderFulfillmentBindingConfigs(bindingsInput)

apps/backend/src/services/admin/admin-read-helpers.js

@@ -1,54 +1,23 @@
 // @ts-check
 
-import { getAgisoShopConfig } from '../platforms/agiso/shop-config-service.js'
 import { extractAgisoTradePayload, resolveAgisoTradePlatformOrderId } from '../order/agiso-trade-parsing.js'
 import { getInventoryItemById } from '../../repositories/inventory-repo.js'
 import { listOrderItemsByOrderId } from '../../repositories/order-item-repo.js'
 import { getOrderById } from '../../repositories/order-repo.js'
 import { getTaskById, listTasksByOrderId } from '../../repositories/task-repo.js'
-import { listTaskInventoryBindingSummariesByTaskIds } from '../../repositories/task-inventory-binding-repo.js'
 import { createHttpError } from '../../utils/http.js'
 import { formatFenToAmount, normalizeFen, parseAmountToFen } from '../../utils/money.js'
 import { safeParseJson } from './admin-query-utils.js'
-import { normalizeAdminRole } from './admin-auth-service.js'
+import { resolveDisplayShopName, resolveOrderItemTitle } from './admin-read-shared-helpers.js'
+import { buildOrderBindingSummary, getTaskBindingSummaryMap, mapAdminTaskSummary } from './admin-task-read-helpers.js'
 
 /** @typedef {import('../../types/admin-read-models.js').AdminInventoryItemListItem} AdminInventoryItemListItem */
 /** @typedef {import('../../types/admin-read-models.js').AdminOrderListItem} AdminOrderListItem */
-/** @typedef {import('../../types/admin-read-models.js').AdminTaskBindingSummary} AdminTaskBindingSummary */
-/** @typedef {import('../../types/admin-read-models.js').AdminTaskListItem} AdminTaskListItem */
 /** @typedef {import('../../types/admin-read-models.js').AdminWebhookEventListItem} AdminWebhookEventListItem */
 /** @typedef {import('../../types/repository-rows.js').InventoryItemRow} InventoryItemRow */
 /** @typedef {import('../../types/repository-rows.js').OrderListRow} OrderListRow */
-/** @typedef {import('../../types/repository-rows.js').TaskEventRow} TaskEventRow */
-/** @typedef {import('../../types/repository-rows.js').TaskInventoryBindingRow} TaskInventoryBindingRow */
-/** @typedef {import('../../types/repository-rows.js').TaskRow} TaskRow */
 /** @typedef {import('../../types/repository-rows.js').WebhookEventRow} WebhookEventRow */
 
-export function mapAdminTaskSummary(task, bindingSummary = createEmptyTaskBindingSummary()) {
-  const binding = buildTaskBindingState(task)
-  const taskContext = parseTaskContext(task)
-
-  return {
-    taskId: task.id,
-    taskNo: task.task_no,
-    deliveryStatus: task.delivery_status || '',
-    status: task.task_status,
-    systemBindingStatus: binding.systemBindingStatus,
-    userBindingStatus: binding.userBindingStatus,
-    loginType: task.login_type,
-    browserSessionId: task.browser_session_id,
-    claimedAt: task.claimed_at,
-    roleConfirmedAt: task.role_confirmed_at,
-    redeemedAt: task.redeemed_at,
-    lastError: task.last_error,
-    retryCount: getTaskRetryCount(task),
-    bindingSummary,
-    agisoAutoDelivery: mapAgisoAutoDeliveryContext(taskContext.agisoAutoDelivery),
-    createdAt: task.created_at,
-    updatedAt: task.updated_at,
-  }
-}
-
 /**
  * @param {WebhookEventRow} item
  * @returns {Promise<AdminWebhookEventListItem>}
@@ -186,7 +155,7 @@ export async function mapAdminWebhookEvent(item, { includeRaw = false } = {}) {
 export async function mapAdminInventoryListItem(item) {
   const task = item.reserved_by_task_id ? await getTaskById(item.reserved_by_task_id) : null
   const order = task?.order_id ? await getOrderById(task.order_id) : null
-  const binding = buildTaskBindingState(task)
+  const taskSummary = task ? mapAdminTaskSummary(task) : null
 
   return {
     inventoryItemId: item.id,
@@ -198,8 +167,8 @@ export async function mapAdminInventoryListItem(item) {
     reservedByTaskId: item.reserved_by_task_id,
     reservedByTaskNo: task?.task_no || '',
     platformOrderId: order?.platform_order_id || '',
-    systemBindingStatus: item.status === 'consumed' ? 'system_bound' : binding.systemBindingStatus,
+    systemBindingStatus: item.status === 'consumed' ? 'system_bound' : (taskSummary?.systemBindingStatus || 'pending_binding'),
-    userBindingStatus: item.status === 'consumed' ? 'binding_completed' : binding.userBindingStatus,
+    userBindingStatus: item.status === 'consumed' ? 'binding_completed' : (taskSummary?.userBindingStatus || 'not_started'),
     invalidReason: item.invalid_reason || '',
     deliveredAt: item.delivered_at,
     createdAt: item.created_at,
@@ -207,37 +176,6 @@ export async function mapAdminInventoryListItem(item) {
   }
 }
 
-export function mapTaskActionPayload(task) {
-  const inventoryItemId = getTaskPrimaryInventoryItemId(task)
-  const primaryClaimTokenId = getTaskPrimaryClaimTokenId(task)
-
-  return {
-    taskId: task.id,
-    taskNo: task.task_no,
-    status: task.task_status,
-    deliveryStatus: task.delivery_status,
-    resultCode: task.result_code,
-    resultMessage: task.result_message,
-    inventoryItemId,
-    primaryClaimTokenId,
-    lastError: task.last_error,
-    updatedAt: task.updated_at,
-  }
-}
-
-export async function getRequiredTask(taskId) {
-  const task = await getTaskById(Number(taskId))
-
-  if (!task) {
-    throw createHttpError('任务不存在', {
-      statusCode: 404,
-      errorCode: 'admin_task_not_found',
-    })
-  }
-
-  return task
-}
-
 export async function getRequiredInventoryItem(inventoryItemId) {
   const inventoryItem = await getInventoryItemById(Number(inventoryItemId))
 
@@ -251,133 +189,6 @@ export async function getRequiredInventoryItem(inventoryItemId) {
   return inventoryItem
 }
 
-/**
- * @param {TaskRow} task
- * @returns {AdminTaskListItem}
- */
-export function mapAdminTaskListItem(task, bindingSummary = createEmptyTaskBindingSummary(), viewerContext = createAdminViewerContext()) {
-  const binding = buildTaskBindingState(task)
-  const taskContext = parseTaskContext(task)
-
-  return {
-    taskId: task.id,
-    taskNo: task.task_no,
-    platformOrderId: task.platform_order_id,
-    skuCode: task.sku_code || '',
-    skuName: task.sku_name || '',
-    status: task.task_status,
-    executorKey: task.executor_key || '',
-    deliveryStatus: task.delivery_status || '',
-    resultCode: task.result_code || '',
-    resultMessage: task.result_message || '',
-    systemBindingStatus: binding.systemBindingStatus,
-    userBindingStatus: binding.userBindingStatus,
-    loginType: task.login_type,
-    roleName: task.role_name,
-    roleId: task.role_id,
-    browserSessionId: task.browser_session_id,
-    claimedAt: task.claimed_at,
-    roleConfirmedAt: task.role_confirmed_at,
-    redeemedAt: task.redeemed_at,
-    retryCount: getTaskRetryCount(task),
-    bindingSummary,
-    agisoAutoDelivery: mapAgisoAutoDeliveryContext(taskContext.agisoAutoDelivery),
-    lastError: task.last_error,
-    createdAt: task.created_at,
-    updatedAt: task.updated_at,
-    inventoryDisplayMasked: viewerContext.canViewSensitiveTaskData ? maskCode(task.primary_inventory_display_value) : '',
-    inventoryCredentialType: String(task.primary_inventory_credential_type || '').trim(),
-    claimToken: viewerContext.canViewSensitiveTaskData ? (task.primary_claim_token || task.claim_token || '') : '',
-    screenshotPath: viewerContext.role === 'support' ? '' : (task.screenshot_path || ''),
-  }
-}
-
-/** @param {TaskEventRow} event */
-export function mapAdminTaskEvent(event) {
-  const payload = safeParseJson(event.payload_json)
-
-  return {
-    eventId: event.id,
-    eventType: String(event.event_type || '').trim(),
-    payload: normalizeRecord(payload),
-    createdAt: event.created_at,
-  }
-}
-
-/** @returns {AdminTaskBindingSummary} */
-export function createEmptyTaskBindingSummary() {
-  return {
-    totalBindingCount: 0,
-    reservedBindingCount: 0,
-    consumedBindingCount: 0,
-    releasedBindingCount: 0,
-    roleKeys: [],
-  }
-}
-
-export async function getTaskBindingSummaryMap(taskIds = []) {
-  const rows = await listTaskInventoryBindingSummariesByTaskIds(taskIds)
-  const output = new Map()
-
-  for (const row of rows) {
-    output.set(Number(row.task_id), {
-      totalBindingCount: Number(row.total_binding_count || 0),
-      reservedBindingCount: Number(row.reserved_binding_count || 0),
-      consumedBindingCount: Number(row.consumed_binding_count || 0),
-      releasedBindingCount: Number(row.released_binding_count || 0),
-      roleKeys: Array.isArray(row.role_keys)
-        ? row.role_keys.map((value) => String(value || '').trim()).filter(Boolean)
-        : [],
-    })
-  }
-
-  return output
-}
-
-export function getTaskBindingSummary(summaryMap, taskId) {
-  return summaryMap.get(Number(taskId)) || createEmptyTaskBindingSummary()
-}
-
-export function createTaskBindingSummaryFromBindings(bindings = []) {
-  const normalizedBindings = Array.isArray(bindings) ? bindings : []
-  const roleKeys = Array.from(new Set(normalizedBindings
-    .map((binding) => String(binding?.role_key || '').trim())
-    .filter(Boolean)))
-
-  return {
-    totalBindingCount: normalizedBindings.length,
-    reservedBindingCount: normalizedBindings.filter((binding) => String(binding?.binding_status || '') === 'reserved').length,
-    consumedBindingCount: normalizedBindings.filter((binding) => String(binding?.binding_status || '') === 'consumed').length,
-    releasedBindingCount: normalizedBindings.filter((binding) => String(binding?.binding_status || '') === 'released').length,
-    roleKeys,
-  }
-}
-
-export function mapAdminTaskInventoryBinding(binding, task, viewerContext = createAdminViewerContext()) {
-  const metadata = safeParseJson(binding.metadata_json)
-
-  return {
-    bindingId: binding.id,
-    inventoryItemId: binding.inventory_item_id,
-    roleKey: String(binding.role_key || '').trim(),
-    quantity: Math.max(1, Number(binding.quantity || 1)),
-    bindingStatus: String(binding.binding_status || '').trim(),
-    inventoryStatus: String(binding.inventory_item_status || '').trim(),
-    skuCode: String(binding.sku_code || '').trim(),
-    batchNo: String(binding.batch_no || '').trim(),
-    credentialType: String(binding.credential_type || 'tencent_code').trim() || 'tencent_code',
-    displayValue: viewerContext.canViewSensitiveTaskData ? String(binding.display_value || '').trim() : '',
-    invalidReason: String(binding.invalid_reason || '').trim(),
-    consumedAt: binding.consumed_at || null,
-    releasedAt: binding.released_at || null,
-    createdAt: binding.created_at,
-    updatedAt: binding.updated_at,
-    metadata: normalizeRecord(metadata),
-    isPrimary: Number(binding.inventory_item_id || 0) === getTaskPrimaryInventoryItemId(task),
-    canRelease: viewerContext.canManageSensitiveInventory && canReleaseTaskInventoryBinding(task, binding),
-  }
-}
-
 /**
  * @param {OrderListRow} item
  * @returns {Promise<AdminOrderListItem>}
@@ -442,451 +253,6 @@ export function summarizeOrderItems(items) {
   return `${firstLabel} 等 ${normalizedItems.length} 项`
 }
 
-export function buildOrderBindingSummary(tasks, taskBindingSummaryMap = new Map()) {
-  const normalizedTasks = Array.isArray(tasks) ? tasks : []
-  const totalTaskCount = normalizedTasks.length
-  const taskBindings = normalizedTasks.map((task) => buildTaskBindingState(task))
-  const systemBoundTaskCount = normalizedTasks.filter((task) => isTaskSystemBound(task)).length
-  const completedBindingTaskCount = normalizedTasks.filter((task) => String(task?.task_status || '') === 'redeemed').length
-  const bindingSummaries = normalizedTasks.map((task) => getTaskBindingSummary(taskBindingSummaryMap, task.id))
-  const totalBindingCount = bindingSummaries.reduce((sum, item) => sum + item.totalBindingCount, 0)
-  const reservedBindingCount = bindingSummaries.reduce((sum, item) => sum + item.reservedBindingCount, 0)
-  const consumedBindingCount = bindingSummaries.reduce((sum, item) => sum + item.consumedBindingCount, 0)
-  const releasedBindingCount = bindingSummaries.reduce((sum, item) => sum + item.releasedBindingCount, 0)
-
-  let systemBindingStatus = 'pending_binding'
-  let userBindingStatus = 'not_started'
-
-  if (totalTaskCount === 0) {
-    return {
-      totalTaskCount,
-      systemBoundTaskCount,
-      completedBindingTaskCount,
-      totalBindingCount,
-      reservedBindingCount,
-      consumedBindingCount,
-      releasedBindingCount,
-      systemBindingStatus,
-      userBindingStatus,
-    }
-  }
-
-  if (normalizedTasks.every((task) => String(task.task_status || '') === 'redeemed')) {
-    systemBindingStatus = 'system_bound'
-    userBindingStatus = 'binding_completed'
-  } else if (taskBindings.some((item) => ['binding_in_progress', 'binding_confirmed', 'link_opened'].includes(item.userBindingStatus))) {
-    systemBindingStatus = systemBoundTaskCount > 0 ? 'system_bound' : 'pending_binding'
-    userBindingStatus = 'user_binding'
-  } else if (taskBindings.some((item) => item.userBindingStatus === 'waiting_user_claim')) {
-    systemBindingStatus = systemBoundTaskCount > 0 ? 'system_bound' : 'pending_binding'
-    userBindingStatus = 'waiting_user_claim'
-  } else if (taskBindings.some((item) => item.userBindingStatus === 'binding_exception')) {
-    systemBindingStatus = systemBoundTaskCount > 0 ? 'system_bound' : 'pending_binding'
-    userBindingStatus = 'binding_exception'
-  } else if (systemBoundTaskCount > 0) {
-    systemBindingStatus = 'system_bound'
-  } else if (taskBindings.some((item) => ['manual_review', 'retry_pending', 'waiting_inventory'].includes(item.systemBindingStatus))) {
-    systemBindingStatus = 'binding_exception'
-  }
-
-  return {
-    totalTaskCount,
-    systemBoundTaskCount,
-    completedBindingTaskCount,
-    totalBindingCount,
-    reservedBindingCount,
-    consumedBindingCount,
-    releasedBindingCount,
-    systemBindingStatus,
-    userBindingStatus,
-  }
-}
-
-export function buildOrderAgisoAutoDeliverySummary(order, tasks = []) {
-  if (String(order?.provider || '').trim() !== 'agiso' || String(order?.platform || '').trim() !== 'xianyu') {
-    return null
-  }
-
-  const normalizedTasks = Array.isArray(tasks) ? tasks.filter(Boolean) : []
-  const totalTaskCount = normalizedTasks.length
-  const deliveredTaskCount = normalizedTasks.filter((task) => String(task?.delivery_status || '').trim() === 'delivered').length
-  const latest = normalizedTasks.reduce((best, task) => {
-    const autoDelivery = mapAgisoAutoDeliveryContext(parseTaskContext(task).agisoAutoDelivery)
-
-    if (!autoDelivery) {
-      return best
-    }
-
-    const candidate = {
-      ...autoDelivery,
-      sourceTaskId: Number(task.id || 0) || null,
-      sourceTaskNo: String(task.task_no || '').trim(),
-    }
-    const candidateTime = Date.parse(String(candidate.updatedAt || task.updated_at || ''))
-    const bestTime = Date.parse(String(best?.updatedAt || ''))
-
-    if (!best || (Number.isFinite(candidateTime) && (!Number.isFinite(bestTime) || candidateTime >= bestTime))) {
-      return candidate
-    }
-
-    return best
-  }, null)
-
-  if (latest) {
-    return {
-      ...latest,
-      totalTaskCount,
-      deliveredTaskCount,
-    }
-  }
-
-  return {
-    status: totalTaskCount === 0 ? 'not_started' : deliveredTaskCount >= totalTaskCount ? 'pending' : 'waiting',
-    trigger: '',
-    reason: deliveredTaskCount >= totalTaskCount ? '' : 'waiting_other_tasks',
-    platformOrderId: String(order?.platform_order_id || '').trim(),
-    responseStatus: 0,
-    errorMessage: '',
-    requestId: '',
-    aldsType: null,
-    updatedAt: null,
-    sourceTaskId: null,
-    sourceTaskNo: '',
-    totalTaskCount,
-    deliveredTaskCount,
-  }
-}
-
-export function mapManualDispatchContext(value, viewerContext = createAdminViewerContext()) {
-  if (!value || typeof value !== 'object') {
-    return null
-  }
-
-  return {
-    outcome: String(value.outcome || '').trim(),
-    deliveryReference: String(value.deliveryReference || '').trim(),
-    deliveredCredential: viewerContext.canViewSensitiveTaskData ? String(value.deliveredCredential || '').trim() : '',
-    resultMessage: String(value.resultMessage || '').trim(),
-    completedAt: value.completedAt || null,
-    completedBy: value.completedBy && typeof value.completedBy === 'object'
-      ? {
-        userId: Number(value.completedBy.userId || 0) || 0,
-        username: String(value.completedBy.username || '').trim(),
-        role: String(value.completedBy.role || '').trim(),
-      }
-      : null,
-  }
-}
-
-export function mapRedeemResolutionContext(value) {
-  if (!value || typeof value !== 'object') {
-    return null
-  }
-
-  const attempts = Array.isArray(value.attempts)
-    ? value.attempts
-      .map((attempt) => mapRedeemResolutionAttempt(attempt))
-      .filter(Boolean)
-    : []
-
-  return {
-    status: String(value.status || '').trim(),
-    taskStatus: String(value.taskStatus || '').trim(),
-    replacementCount: Math.max(0, Number(value.replacementCount || 0)),
-    finishedAt: value.finishedAt || null,
-    attempts,
-  }
-}
-
-export function getTaskPrimaryInventoryItemId(task) {
-  const value = Number(task?.primary_inventory_item_id || 0)
-  return Number.isFinite(value) && value > 0 ? value : null
-}
-
-export function getTaskPrimaryClaimTokenId(task) {
-  const value = Number(task?.primary_claim_token_id || 0)
-  return Number.isFinite(value) && value > 0 ? value : null
-}
-
-export function createAdminViewerContext(session = null) {
-  const role = normalizeAdminRole(session?.role)
-
-  return {
-    role,
-    canViewSensitiveTaskData: role === 'admin' || role === 'operator',
-    canManageSensitiveInventory: role === 'admin',
-    canManageTaskLifecycle: role === 'admin' || role === 'operator',
-    canOperateAssistedTask: role === 'admin' || role === 'operator' || role === 'support',
-  }
-}
-
-export async function resolveAdminTaskScreenshotUrl(task, viewerContext) {
-  if (viewerContext.role === 'support') {
-    return task.browser_session_id ? `/api/v1/admin/tasks/${task.id}/screenshot` : ''
-  }
-
-  if (task.screenshot_path || task.browser_session_id) {
-    return `/api/v1/admin/tasks/${task.id}/screenshot`
-  }
-
-  return ''
-}
-
-export function resolveDisplayShopName(provider, shopId, shopName) {
-  const normalizedShopName = String(shopName || '').trim()
-  if (normalizedShopName) {
-    return normalizedShopName
-  }
-
-  const normalizedShopId = String(shopId || '').trim()
-  if (!normalizedShopId) {
-    return ''
-  }
-
-  if (String(provider || '').trim().toLowerCase() === 'agiso') {
-    const configuredName = String(getAgisoShopConfig(normalizedShopId)?.shopName || '').trim()
-    if (configuredName) {
-      return configuredName
-    }
-  }
-
-  return normalizedShopId
-}
-
-export function parseTaskContext(task) {
-  const value = task?.context_json
-
-  if (!value) {
-    return {}
-  }
-
-  if (typeof value === 'object') {
-    return value
-  }
-
-  try {
-    return JSON.parse(String(value || '{}'))
-  } catch {
-    return {}
-  }
-}
-
-export function parseTaskState(task) {
-  const value = task?.state_json
-
-  if (!value) {
-    return {}
-  }
-
-  if (typeof value === 'object') {
-    return value
-  }
-
-  try {
-    return JSON.parse(String(value || '{}'))
-  } catch {
-    return {}
-  }
-}
-
-export function resolveOrderItemTitle(item) {
-  if (!item) {
-    return ''
-  }
-
-  const spec = safeParseJson(item.spec_json)
-
-  return pickFirstNonEmpty([
-    spec.title,
-    spec.Title,
-    spec.itemTitle,
-    spec.item_title,
-    spec.goods_name,
-    spec.goodsName,
-    item.sku_name,
-    item.sku_code,
-  ])
-}
-
-export function resolveOrderItemDeliveryMode(tasks, orderItemId) {
-  const task = (Array.isArray(tasks) ? tasks : []).find((item) => item.order_item_id === orderItemId)
-
-  if (!task) {
-    return ''
-  }
-
-  if (String(task.executor_key || '').trim() === 'manual_dispatch') {
-    return 'manual_dispatch'
-  }
-
-  if (task.requires_claim || getTaskPrimaryClaimTokenId(task) || task.primary_claim_token || task.claim_token) {
-    return 'claim_link'
-  }
-
-  return String(task.executor_key || '').trim()
-}
-
-export function isManualDispatchTask(task) {
-  return String(task?.executor_key || '').trim() === 'manual_dispatch'
-}
-
-export function isAssistedClaimTask(task) {
-  return String(task?.executor_key || '').trim() === 'tencent_claim_assisted'
-}
-
-export function canRegenerateClaimLinkForViewer(task, viewerContext) {
-  if (isManualDispatchTask(task)) {
-    return false
-  }
-
-  const baseAllowed = ['link_generated', 'claimed', 'role_confirmed', 'retry_pending', 'manual_review'].includes(task.task_status)
-
-  if (!baseAllowed) {
-    return false
-  }
-
-  if (viewerContext.canManageTaskLifecycle) {
-    return true
-  }
-
-  return viewerContext.canOperateAssistedTask && isAssistedClaimTask(task)
-}
-
-export function canViewerConfirmAssistedRole(task, viewerContext) {
-  if (!viewerContext.canOperateAssistedTask || !isAssistedClaimTask(task)) {
-    return false
-  }
-
-  return String(task?.task_status || '').trim() === 'claimed'
-}
-
-export function canViewerRedeemAssistedTask(task, viewerContext) {
-  if (!viewerContext.canOperateAssistedTask || !isAssistedClaimTask(task)) {
-    return false
-  }
-
-  return ['role_confirmed', 'redeeming'].includes(String(task?.task_status || '').trim())
-}
-
-function canReleaseTaskInventoryBinding(task, binding) {
-  if (!task || !binding) {
-    return false
-  }
-
-  if (String(binding.binding_status || '').trim() !== 'reserved') {
-    return false
-  }
-
-  return !['redeemed', 'expired'].includes(String(task.task_status || '').trim())
-}
-
-function buildTaskBindingState(task) {
-  const normalizedStatus = String(task?.task_status || '').trim()
-
-  if (!normalizedStatus) {
-    return {
-      systemBindingStatus: 'pending_binding',
-      userBindingStatus: 'not_started',
-    }
-  }
-
-  if (normalizedStatus === 'pending_payment') {
-    return { systemBindingStatus: 'pending_payment', userBindingStatus: 'not_started' }
-  }
-
-  if (normalizedStatus === 'paid') {
-    return { systemBindingStatus: 'pending_binding', userBindingStatus: 'not_started' }
-  }
-
-  if (normalizedStatus === 'waiting_inventory') {
-    return { systemBindingStatus: 'waiting_inventory', userBindingStatus: 'not_started' }
-  }
-
-  if (normalizedStatus === 'manual_review') {
-    return { systemBindingStatus: 'manual_review', userBindingStatus: 'binding_exception' }
-  }
-
-  if (normalizedStatus === 'retry_pending') {
-    return { systemBindingStatus: 'retry_pending', userBindingStatus: 'binding_exception' }
-  }
-
-  if (normalizedStatus === 'closed') {
-    return { systemBindingStatus: 'closed', userBindingStatus: 'closed' }
-  }
-
-  if (normalizedStatus === 'expired') {
-    return { systemBindingStatus: 'expired', userBindingStatus: 'expired' }
-  }
-
-  if (normalizedStatus === 'link_generated') {
-    return { systemBindingStatus: 'system_bound', userBindingStatus: 'waiting_user_claim' }
-  }
-
-  if (normalizedStatus === 'claimed') {
-    return { systemBindingStatus: 'system_bound', userBindingStatus: 'link_opened' }
-  }
-
-  if (normalizedStatus === 'role_confirmed') {
-    return { systemBindingStatus: 'system_bound', userBindingStatus: 'binding_confirmed' }
-  }
-
-  if (normalizedStatus === 'redeeming') {
-    return { systemBindingStatus: 'system_bound', userBindingStatus: 'binding_in_progress' }
-  }
-
-  if (normalizedStatus === 'redeemed') {
-    return { systemBindingStatus: 'system_bound', userBindingStatus: 'binding_completed' }
-  }
-
-  if (isTaskSystemBound(task)) {
-    return { systemBindingStatus: 'system_bound', userBindingStatus: 'waiting_user_claim' }
-  }
-
-  return { systemBindingStatus: 'pending_binding', userBindingStatus: 'not_started' }
-}
-
-function isTaskSystemBound(task) {
-  return Boolean(task && (getTaskPrimaryInventoryItemId(task) || getTaskPrimaryClaimTokenId(task)))
-}
-
-function mapAgisoAutoDeliveryContext(value) {
-  if (!value || typeof value !== 'object') {
-    return null
-  }
-
-  return {
-    status: String(value.status || '').trim(),
-    trigger: String(value.trigger || '').trim(),
-    reason: String(value.reason || '').trim(),
-    platformOrderId: String(value.platformOrderId || '').trim(),
-    responseStatus: Number(value.responseStatus || 0),
-    errorMessage: String(value.errorMessage || '').trim(),
-    requestId: String(value.requestId || '').trim(),
-    aldsType: Number(value.aldsType || 0) || null,
-    updatedAt: value.updatedAt || null,
-  }
-}
-
-function mapRedeemResolutionAttempt(value) {
-  if (!value || typeof value !== 'object') {
-    return null
-  }
-
-  return {
-    attempt: Math.max(1, Number(value.attempt || 1)),
-    inventoryItemId: Number(value.inventoryItemId || 0) || null,
-    codeMasked: String(value.codeMasked || '').trim(),
-    credentialType: String(value.credentialType || '').trim(),
-    outcome: String(value.outcome || '').trim(),
-    resultCode: String(value.resultCode || '').trim(),
-    resultMessage: String(value.resultMessage || '').trim(),
-  }
-}
-
-function normalizeRecord(value) {
-  return value && typeof value === 'object' && !Array.isArray(value) ? value : {}
-}
-
 function extractWebhookPayload(body) {
   return extractAgisoTradePayload(body)
 }
@@ -923,6 +289,10 @@ function extractWebhookItemSources(payload) {
   return []
 }
 
+function normalizeRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {}
+}
+
 function pickFirstNonEmpty(values) {
   for (const value of values) {
     if (typeof value === 'string' && value.trim()) {
@@ -936,18 +306,3 @@ function pickFirstNonEmpty(values) {
 
   return ''
 }
-
-function maskCode(value) {
-  const text = String(value || '').trim()
-  if (!text) {
-    return ''
-  }
-  if (text.length <= 8) {
-    return `${text.slice(0, 2)}****${text.slice(-2)}`
-  }
-  return `${text.slice(0, 4)}****${text.slice(-4)}`
-}
-
-function getTaskRetryCount(task) {
-  return Number(task?.attempt_count || 0)
-}

apps/backend/src/services/admin/admin-read-service.js

@@ -14,37 +14,41 @@ import { formatFenToAmount, normalizeFen } from '../../utils/money.js'
 import { getTencentBrowserSessionReviewScreenshotPath } from '../session/session.js'
 import { normalizeDateQuery, normalizePage, normalizePageSize, safeParseJson } from './admin-query-utils.js'
 import {
-  buildOrderAgisoAutoDeliverySummary,
-  buildOrderBindingSummary,
   canRegenerateClaimLinkForViewer,
   canViewerConfirmAssistedRole,
   canViewerRedeemAssistedTask,
   createAdminViewerContext,
-  createTaskBindingSummaryFromBindings,
-  getRequiredTask,
-  getTaskBindingSummary,
-  getTaskBindingSummaryMap,
   getTaskPrimaryClaimTokenId,
   getTaskPrimaryInventoryItemId,
   isAssistedClaimTask,
   isManualDispatchTask,
+  mapManualDispatchContext,
+  mapRedeemResolutionContext,
+  parseTaskContext,
+  parseTaskState,
+  resolveAdminTaskScreenshotUrl,
+  resolveDisplayShopName,
+  resolveOrderItemDeliveryMode,
+  resolveOrderItemTitle,
+} from './admin-read-shared-helpers.js'
+import {
   mapAdminInventoryListItem,
   mapAdminOrderListItem,
+  mapAdminWebhookEvent,
+  summarizeOrderItems,
+} from './admin-read-helpers.js'
+import {
+  buildOrderAgisoAutoDeliverySummary,
+  buildOrderBindingSummary,
+  createTaskBindingSummaryFromBindings,
+  getRequiredTask,
+  getTaskBindingSummary,
+  getTaskBindingSummaryMap,
   mapAdminTaskEvent,
   mapAdminTaskInventoryBinding,
   mapAdminTaskListItem,
   mapAdminTaskSummary,
-  mapAdminWebhookEvent,
+} from './admin-task-read-helpers.js'
-  mapManualDispatchContext,
-  parseTaskContext,
-  parseTaskState,
-  mapRedeemResolutionContext,
-  resolveOrderItemDeliveryMode,
-  resolveOrderItemTitle,
-  resolveAdminTaskScreenshotUrl,
-  resolveDisplayShopName,
-  summarizeOrderItems,
-} from './admin-read-helpers.js'
 
 /** @typedef {import('../../types/admin-read-models.js').AdminInventoryListResponse} AdminInventoryListResponse */
 /** @typedef {import('../../types/admin-read-models.js').AdminInventorySkuSuggestionResponse} AdminInventorySkuSuggestionResponse */

apps/backend/src/services/admin/admin-read-shared-helpers.js

@@ -0,0 +1,246 @@
+// @ts-check
+
+import { getAgisoShopConfig } from '../platforms/agiso/shop-config-service.js'
+import { safeParseJson } from './admin-query-utils.js'
+import { normalizeAdminRole } from './admin-auth-service.js'
+
+export function mapManualDispatchContext(value, viewerContext = createAdminViewerContext()) {
+  if (!value || typeof value !== 'object') {
+    return null
+  }
+
+  return {
+    outcome: String(value.outcome || '').trim(),
+    deliveryReference: String(value.deliveryReference || '').trim(),
+    deliveredCredential: viewerContext.canViewSensitiveTaskData ? String(value.deliveredCredential || '').trim() : '',
+    resultMessage: String(value.resultMessage || '').trim(),
+    completedAt: value.completedAt || null,
+    completedBy: value.completedBy && typeof value.completedBy === 'object'
+      ? {
+        userId: Number(value.completedBy.userId || 0) || 0,
+        username: String(value.completedBy.username || '').trim(),
+        role: String(value.completedBy.role || '').trim(),
+      }
+      : null,
+  }
+}
+
+export function mapRedeemResolutionContext(value) {
+  if (!value || typeof value !== 'object') {
+    return null
+  }
+
+  const attempts = Array.isArray(value.attempts)
+    ? value.attempts
+      .map((attempt) => mapRedeemResolutionAttempt(attempt))
+      .filter(Boolean)
+    : []
+
+  return {
+    status: String(value.status || '').trim(),
+    taskStatus: String(value.taskStatus || '').trim(),
+    replacementCount: Math.max(0, Number(value.replacementCount || 0)),
+    finishedAt: value.finishedAt || null,
+    attempts,
+  }
+}
+
+export function getTaskPrimaryInventoryItemId(task) {
+  const value = Number(task?.primary_inventory_item_id || 0)
+  return Number.isFinite(value) && value > 0 ? value : null
+}
+
+export function getTaskPrimaryClaimTokenId(task) {
+  const value = Number(task?.primary_claim_token_id || 0)
+  return Number.isFinite(value) && value > 0 ? value : null
+}
+
+export function createAdminViewerContext(session = null) {
+  const role = normalizeAdminRole(session?.role)
+
+  return {
+    role,
+    canViewSensitiveTaskData: role === 'admin' || role === 'operator',
+    canManageSensitiveInventory: role === 'admin',
+    canManageTaskLifecycle: role === 'admin' || role === 'operator',
+    canOperateAssistedTask: role === 'admin' || role === 'operator' || role === 'support',
+  }
+}
+
+export async function resolveAdminTaskScreenshotUrl(task, viewerContext) {
+  if (viewerContext.role === 'support') {
+    return task.browser_session_id ? `/api/v1/admin/tasks/${task.id}/screenshot` : ''
+  }
+
+  if (task.screenshot_path || task.browser_session_id) {
+    return `/api/v1/admin/tasks/${task.id}/screenshot`
+  }
+
+  return ''
+}
+
+export function resolveDisplayShopName(provider, shopId, shopName) {
+  const normalizedShopName = String(shopName || '').trim()
+  if (normalizedShopName) {
+    return normalizedShopName
+  }
+
+  const normalizedShopId = String(shopId || '').trim()
+  if (!normalizedShopId) {
+    return ''
+  }
+
+  if (String(provider || '').trim().toLowerCase() === 'agiso') {
+    const configuredName = String(getAgisoShopConfig(normalizedShopId)?.shopName || '').trim()
+    if (configuredName) {
+      return configuredName
+    }
+  }
+
+  return normalizedShopId
+}
+
+export function parseTaskContext(task) {
+  const value = task?.context_json
+
+  if (!value) {
+    return {}
+  }
+
+  if (typeof value === 'object') {
+    return value
+  }
+
+  try {
+    return JSON.parse(String(value || '{}'))
+  } catch {
+    return {}
+  }
+}
+
+export function parseTaskState(task) {
+  const value = task?.state_json
+
+  if (!value) {
+    return {}
+  }
+
+  if (typeof value === 'object') {
+    return value
+  }
+
+  try {
+    return JSON.parse(String(value || '{}'))
+  } catch {
+    return {}
+  }
+}
+
+export function resolveOrderItemTitle(item) {
+  if (!item) {
+    return ''
+  }
+
+  const spec = safeParseJson(item.spec_json)
+
+  return pickFirstNonEmpty([
+    spec.title,
+    spec.Title,
+    spec.itemTitle,
+    spec.item_title,
+    spec.goods_name,
+    spec.goodsName,
+    item.sku_name,
+    item.sku_code,
+  ])
+}
+
+export function resolveOrderItemDeliveryMode(tasks, orderItemId) {
+  const task = (Array.isArray(tasks) ? tasks : []).find((item) => item.order_item_id === orderItemId)
+
+  if (!task) {
+    return ''
+  }
+
+  if (String(task.executor_key || '').trim() === 'manual_dispatch') {
+    return 'manual_dispatch'
+  }
+
+  if (task.requires_claim || getTaskPrimaryClaimTokenId(task) || task.primary_claim_token || task.claim_token) {
+    return 'claim_link'
+  }
+
+  return String(task.executor_key || '').trim()
+}
+
+export function isManualDispatchTask(task) {
+  return String(task?.executor_key || '').trim() === 'manual_dispatch'
+}
+
+export function isAssistedClaimTask(task) {
+  return String(task?.executor_key || '').trim() === 'tencent_claim_assisted'
+}
+
+export function canRegenerateClaimLinkForViewer(task, viewerContext) {
+  if (isManualDispatchTask(task)) {
+    return false
+  }
+
+  const baseAllowed = ['link_generated', 'claimed', 'role_confirmed', 'retry_pending', 'manual_review'].includes(task.task_status)
+
+  if (!baseAllowed) {
+    return false
+  }
+
+  if (viewerContext.canManageTaskLifecycle) {
+    return true
+  }
+
+  return viewerContext.canOperateAssistedTask && isAssistedClaimTask(task)
+}
+
+export function canViewerConfirmAssistedRole(task, viewerContext) {
+  if (!viewerContext.canOperateAssistedTask || !isAssistedClaimTask(task)) {
+    return false
+  }
+
+  return String(task?.task_status || '').trim() === 'claimed'
+}
+
+export function canViewerRedeemAssistedTask(task, viewerContext) {
+  if (!viewerContext.canOperateAssistedTask || !isAssistedClaimTask(task)) {
+    return false
+  }
+
+  return ['role_confirmed', 'redeeming'].includes(String(task?.task_status || '').trim())
+}
+
+function mapRedeemResolutionAttempt(value) {
+  if (!value || typeof value !== 'object') {
+    return null
+  }
+
+  return {
+    attempt: Math.max(1, Number(value.attempt || 1)),
+    inventoryItemId: Number(value.inventoryItemId || 0) || null,
+    codeMasked: String(value.codeMasked || '').trim(),
+    credentialType: String(value.credentialType || '').trim(),
+    outcome: String(value.outcome || '').trim(),
+    resultCode: String(value.resultCode || '').trim(),
+    resultMessage: String(value.resultMessage || '').trim(),
+  }
+}
+
+function pickFirstNonEmpty(values) {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim()) {
+      return value.trim()
+    }
+
+    if (typeof value === 'number' && Number.isFinite(value)) {
+      return String(value)
+    }
+  }
+
+  return ''
+}

apps/backend/src/services/admin/admin-service.js

@@ -1,37 +1,45 @@
 // @ts-check
 
+export {
+  getRequiredInventoryItem,
+  mapAdminInventoryListItem,
+  mapAdminOrderListItem,
+  mapAdminWebhookEvent,
+} from './admin-read-helpers.js'
+
 export {
   buildOrderAgisoAutoDeliverySummary,
   buildOrderBindingSummary,
-  canRegenerateClaimLinkForViewer,
-  canViewerConfirmAssistedRole,
-  canViewerRedeemAssistedTask,
-  createAdminViewerContext,
   createEmptyTaskBindingSummary,
   createTaskBindingSummaryFromBindings,
-  getRequiredInventoryItem,
   getRequiredTask,
   getTaskBindingSummary,
   getTaskBindingSummaryMap,
-  getTaskPrimaryClaimTokenId,
-  getTaskPrimaryInventoryItemId,
-  mapAdminInventoryListItem,
-  mapAdminOrderListItem,
   mapAdminTaskEvent,
   mapAdminTaskInventoryBinding,
   mapAdminTaskListItem,
   mapAdminTaskSummary,
-  mapAdminWebhookEvent,
+  mapTaskActionPayload,
+} from './admin-task-read-helpers.js'
+
+export {
+  canRegenerateClaimLinkForViewer,
+  canViewerConfirmAssistedRole,
+  canViewerRedeemAssistedTask,
+  createAdminViewerContext,
+  getTaskPrimaryClaimTokenId,
+  getTaskPrimaryInventoryItemId,
+  isAssistedClaimTask,
+  isManualDispatchTask,
   mapManualDispatchContext,
   mapRedeemResolutionContext,
-  mapTaskActionPayload,
   parseTaskContext,
   parseTaskState,
   resolveOrderItemDeliveryMode,
   resolveOrderItemTitle,
   resolveAdminTaskScreenshotUrl,
   resolveDisplayShopName,
-} from './admin-read-helpers.js'
+} from './admin-read-shared-helpers.js'
 
 export {
   getAdminInventoryItems,

apps/backend/src/services/admin/admin-task-read-helpers.js

@@ -0,0 +1,434 @@
+// @ts-check
+
+import { getTaskById } from '../../repositories/task-repo.js'
+import { listTaskInventoryBindingSummariesByTaskIds } from '../../repositories/task-inventory-binding-repo.js'
+import { createHttpError } from '../../utils/http.js'
+import { safeParseJson } from './admin-query-utils.js'
+import {
+  createAdminViewerContext,
+  getTaskPrimaryClaimTokenId,
+  getTaskPrimaryInventoryItemId,
+  parseTaskContext,
+} from './admin-read-shared-helpers.js'
+
+/** @typedef {import('../../types/admin-read-models.js').AdminTaskBindingSummary} AdminTaskBindingSummary */
+/** @typedef {import('../../types/admin-read-models.js').AdminTaskListItem} AdminTaskListItem */
+/** @typedef {import('../../types/repository-rows.js').TaskEventRow} TaskEventRow */
+/** @typedef {import('../../types/repository-rows.js').TaskInventoryBindingRow} TaskInventoryBindingRow */
+/** @typedef {import('../../types/repository-rows.js').TaskRow} TaskRow */
+
+export function mapAdminTaskSummary(task, bindingSummary = createEmptyTaskBindingSummary()) {
+  const binding = buildTaskBindingState(task)
+  const taskContext = parseTaskContext(task)
+
+  return {
+    taskId: task.id,
+    taskNo: task.task_no,
+    deliveryStatus: task.delivery_status || '',
+    status: task.task_status,
+    systemBindingStatus: binding.systemBindingStatus,
+    userBindingStatus: binding.userBindingStatus,
+    loginType: task.login_type,
+    browserSessionId: task.browser_session_id,
+    claimedAt: task.claimed_at,
+    roleConfirmedAt: task.role_confirmed_at,
+    redeemedAt: task.redeemed_at,
+    lastError: task.last_error,
+    retryCount: getTaskRetryCount(task),
+    bindingSummary,
+    agisoAutoDelivery: mapAgisoAutoDeliveryContext(taskContext.agisoAutoDelivery),
+    createdAt: task.created_at,
+    updatedAt: task.updated_at,
+  }
+}
+
+export function mapTaskActionPayload(task) {
+  const inventoryItemId = getTaskPrimaryInventoryItemId(task)
+  const primaryClaimTokenId = getTaskPrimaryClaimTokenId(task)
+
+  return {
+    taskId: task.id,
+    taskNo: task.task_no,
+    status: task.task_status,
+    deliveryStatus: task.delivery_status,
+    resultCode: task.result_code,
+    resultMessage: task.result_message,
+    inventoryItemId,
+    primaryClaimTokenId,
+    lastError: task.last_error,
+    updatedAt: task.updated_at,
+  }
+}
+
+export async function getRequiredTask(taskId) {
+  const task = await getTaskById(Number(taskId))
+
+  if (!task) {
+    throw createHttpError('任务不存在', {
+      statusCode: 404,
+      errorCode: 'admin_task_not_found',
+    })
+  }
+
+  return task
+}
+
+/**
+ * @param {TaskRow} task
+ * @returns {AdminTaskListItem}
+ */
+export function mapAdminTaskListItem(task, bindingSummary = createEmptyTaskBindingSummary(), viewerContext = createAdminViewerContext()) {
+  const binding = buildTaskBindingState(task)
+  const taskContext = parseTaskContext(task)
+
+  return {
+    taskId: task.id,
+    taskNo: task.task_no,
+    platformOrderId: task.platform_order_id,
+    skuCode: task.sku_code || '',
+    skuName: task.sku_name || '',
+    status: task.task_status,
+    executorKey: task.executor_key || '',
+    deliveryStatus: task.delivery_status || '',
+    resultCode: task.result_code || '',
+    resultMessage: task.result_message || '',
+    systemBindingStatus: binding.systemBindingStatus,
+    userBindingStatus: binding.userBindingStatus,
+    loginType: task.login_type,
+    roleName: task.role_name,
+    roleId: task.role_id,
+    browserSessionId: task.browser_session_id,
+    claimedAt: task.claimed_at,
+    roleConfirmedAt: task.role_confirmed_at,
+    redeemedAt: task.redeemed_at,
+    retryCount: getTaskRetryCount(task),
+    bindingSummary,
+    agisoAutoDelivery: mapAgisoAutoDeliveryContext(taskContext.agisoAutoDelivery),
+    lastError: task.last_error,
+    createdAt: task.created_at,
+    updatedAt: task.updated_at,
+    inventoryDisplayMasked: viewerContext.canViewSensitiveTaskData ? maskCode(task.primary_inventory_display_value) : '',
+    inventoryCredentialType: String(task.primary_inventory_credential_type || '').trim(),
+    claimToken: viewerContext.canViewSensitiveTaskData ? (task.primary_claim_token || task.claim_token || '') : '',
+    screenshotPath: viewerContext.role === 'support' ? '' : (task.screenshot_path || ''),
+  }
+}
+
+/** @param {TaskEventRow} event */
+export function mapAdminTaskEvent(event) {
+  const payload = safeParseJson(event.payload_json)
+
+  return {
+    eventId: event.id,
+    eventType: String(event.event_type || '').trim(),
+    payload: normalizeRecord(payload),
+    createdAt: event.created_at,
+  }
+}
+
+/** @returns {AdminTaskBindingSummary} */
+export function createEmptyTaskBindingSummary() {
+  return {
+    totalBindingCount: 0,
+    reservedBindingCount: 0,
+    consumedBindingCount: 0,
+    releasedBindingCount: 0,
+    roleKeys: [],
+  }
+}
+
+export async function getTaskBindingSummaryMap(taskIds = []) {
+  const rows = await listTaskInventoryBindingSummariesByTaskIds(taskIds)
+  const output = new Map()
+
+  for (const row of rows) {
+    output.set(Number(row.task_id), {
+      totalBindingCount: Number(row.total_binding_count || 0),
+      reservedBindingCount: Number(row.reserved_binding_count || 0),
+      consumedBindingCount: Number(row.consumed_binding_count || 0),
+      releasedBindingCount: Number(row.released_binding_count || 0),
+      roleKeys: Array.isArray(row.role_keys)
+        ? row.role_keys.map((value) => String(value || '').trim()).filter(Boolean)
+        : [],
+    })
+  }
+
+  return output
+}
+
+export function getTaskBindingSummary(summaryMap, taskId) {
+  return summaryMap.get(Number(taskId)) || createEmptyTaskBindingSummary()
+}
+
+export function createTaskBindingSummaryFromBindings(bindings = []) {
+  const normalizedBindings = Array.isArray(bindings) ? bindings : []
+  const roleKeys = Array.from(new Set(normalizedBindings
+    .map((binding) => String(binding?.role_key || '').trim())
+    .filter(Boolean)))
+
+  return {
+    totalBindingCount: normalizedBindings.length,
+    reservedBindingCount: normalizedBindings.filter((binding) => String(binding?.binding_status || '') === 'reserved').length,
+    consumedBindingCount: normalizedBindings.filter((binding) => String(binding?.binding_status || '') === 'consumed').length,
+    releasedBindingCount: normalizedBindings.filter((binding) => String(binding?.binding_status || '') === 'released').length,
+    roleKeys,
+  }
+}
+
+export function mapAdminTaskInventoryBinding(binding, task, viewerContext = createAdminViewerContext()) {
+  const metadata = safeParseJson(binding.metadata_json)
+
+  return {
+    bindingId: binding.id,
+    inventoryItemId: binding.inventory_item_id,
+    roleKey: String(binding.role_key || '').trim(),
+    quantity: Math.max(1, Number(binding.quantity || 1)),
+    bindingStatus: String(binding.binding_status || '').trim(),
+    inventoryStatus: String(binding.inventory_item_status || '').trim(),
+    skuCode: String(binding.sku_code || '').trim(),
+    batchNo: String(binding.batch_no || '').trim(),
+    credentialType: String(binding.credential_type || 'tencent_code').trim() || 'tencent_code',
+    displayValue: viewerContext.canViewSensitiveTaskData ? String(binding.display_value || '').trim() : '',
+    invalidReason: String(binding.invalid_reason || '').trim(),
+    consumedAt: binding.consumed_at || null,
+    releasedAt: binding.released_at || null,
+    createdAt: binding.created_at,
+    updatedAt: binding.updated_at,
+    metadata: normalizeRecord(metadata),
+    isPrimary: Number(binding.inventory_item_id || 0) === getTaskPrimaryInventoryItemId(task),
+    canRelease: viewerContext.canManageSensitiveInventory && canReleaseTaskInventoryBinding(task, binding),
+  }
+}
+
+export function buildOrderBindingSummary(tasks, taskBindingSummaryMap = new Map()) {
+  const normalizedTasks = Array.isArray(tasks) ? tasks : []
+  const totalTaskCount = normalizedTasks.length
+  const taskBindings = normalizedTasks.map((task) => buildTaskBindingState(task))
+  const systemBoundTaskCount = normalizedTasks.filter((task) => isTaskSystemBound(task)).length
+  const completedBindingTaskCount = normalizedTasks.filter((task) => String(task?.task_status || '') === 'redeemed').length
+  const bindingSummaries = normalizedTasks.map((task) => getTaskBindingSummary(taskBindingSummaryMap, task.id))
+  const totalBindingCount = bindingSummaries.reduce((sum, item) => sum + item.totalBindingCount, 0)
+  const reservedBindingCount = bindingSummaries.reduce((sum, item) => sum + item.reservedBindingCount, 0)
+  const consumedBindingCount = bindingSummaries.reduce((sum, item) => sum + item.consumedBindingCount, 0)
+  const releasedBindingCount = bindingSummaries.reduce((sum, item) => sum + item.releasedBindingCount, 0)
+
+  let systemBindingStatus = 'pending_binding'
+  let userBindingStatus = 'not_started'
+
+  if (totalTaskCount === 0) {
+    return {
+      totalTaskCount,
+      systemBoundTaskCount,
+      completedBindingTaskCount,
+      totalBindingCount,
+      reservedBindingCount,
+      consumedBindingCount,
+      releasedBindingCount,
+      systemBindingStatus,
+      userBindingStatus,
+    }
+  }
+
+  if (normalizedTasks.every((task) => String(task.task_status || '') === 'redeemed')) {
+    systemBindingStatus = 'system_bound'
+    userBindingStatus = 'binding_completed'
+  } else if (taskBindings.some((item) => ['binding_in_progress', 'binding_confirmed', 'link_opened'].includes(item.userBindingStatus))) {
+    systemBindingStatus = systemBoundTaskCount > 0 ? 'system_bound' : 'pending_binding'
+    userBindingStatus = 'user_binding'
+  } else if (taskBindings.some((item) => item.userBindingStatus === 'waiting_user_claim')) {
+    systemBindingStatus = systemBoundTaskCount > 0 ? 'system_bound' : 'pending_binding'
+    userBindingStatus = 'waiting_user_claim'
+  } else if (taskBindings.some((item) => item.userBindingStatus === 'binding_exception')) {
+    systemBindingStatus = systemBoundTaskCount > 0 ? 'system_bound' : 'pending_binding'
+    userBindingStatus = 'binding_exception'
+  } else if (systemBoundTaskCount > 0) {
+    systemBindingStatus = 'system_bound'
+  } else if (taskBindings.some((item) => ['manual_review', 'retry_pending', 'waiting_inventory'].includes(item.systemBindingStatus))) {
+    systemBindingStatus = 'binding_exception'
+  }
+
+  return {
+    totalTaskCount,
+    systemBoundTaskCount,
+    completedBindingTaskCount,
+    totalBindingCount,
+    reservedBindingCount,
+    consumedBindingCount,
+    releasedBindingCount,
+    systemBindingStatus,
+    userBindingStatus,
+  }
+}
+
+export function buildOrderAgisoAutoDeliverySummary(order, tasks = []) {
+  if (String(order?.provider || '').trim() !== 'agiso' || String(order?.platform || '').trim() !== 'xianyu') {
+    return null
+  }
+
+  const normalizedTasks = Array.isArray(tasks) ? tasks.filter(Boolean) : []
+  const totalTaskCount = normalizedTasks.length
+  const deliveredTaskCount = normalizedTasks.filter((task) => String(task?.delivery_status || '').trim() === 'delivered').length
+  const latest = normalizedTasks.reduce((best, task) => {
+    const autoDelivery = mapAgisoAutoDeliveryContext(parseTaskContext(task).agisoAutoDelivery)
+
+    if (!autoDelivery) {
+      return best
+    }
+
+    const candidate = {
+      ...autoDelivery,
+      sourceTaskId: Number(task.id || 0) || null,
+      sourceTaskNo: String(task.task_no || '').trim(),
+    }
+    const candidateTime = Date.parse(String(candidate.updatedAt || task.updated_at || ''))
+    const bestTime = Date.parse(String(best?.updatedAt || ''))
+
+    if (!best || (Number.isFinite(candidateTime) && (!Number.isFinite(bestTime) || candidateTime >= bestTime))) {
+      return candidate
+    }
+
+    return best
+  }, null)
+
+  if (latest) {
+    return {
+      ...latest,
+      totalTaskCount,
+      deliveredTaskCount,
+    }
+  }
+
+  return {
+    status: totalTaskCount === 0 ? 'not_started' : deliveredTaskCount >= totalTaskCount ? 'pending' : 'waiting',
+    trigger: '',
+    reason: deliveredTaskCount >= totalTaskCount ? '' : 'waiting_other_tasks',
+    platformOrderId: String(order?.platform_order_id || '').trim(),
+    responseStatus: 0,
+    errorMessage: '',
+    requestId: '',
+    aldsType: null,
+    updatedAt: null,
+    sourceTaskId: null,
+    sourceTaskNo: '',
+    totalTaskCount,
+    deliveredTaskCount,
+  }
+}
+
+function canReleaseTaskInventoryBinding(task, binding) {
+  if (!task || !binding) {
+    return false
+  }
+
+  if (String(binding.binding_status || '').trim() !== 'reserved') {
+    return false
+  }
+
+  return !['redeemed', 'expired'].includes(String(task.task_status || '').trim())
+}
+
+function buildTaskBindingState(task) {
+  const normalizedStatus = String(task?.task_status || '').trim()
+
+  if (!normalizedStatus) {
+    return {
+      systemBindingStatus: 'pending_binding',
+      userBindingStatus: 'not_started',
+    }
+  }
+
+  if (normalizedStatus === 'pending_payment') {
+    return { systemBindingStatus: 'pending_payment', userBindingStatus: 'not_started' }
+  }
+
+  if (normalizedStatus === 'paid') {
+    return { systemBindingStatus: 'pending_binding', userBindingStatus: 'not_started' }
+  }
+
+  if (normalizedStatus === 'waiting_inventory') {
+    return { systemBindingStatus: 'waiting_inventory', userBindingStatus: 'not_started' }
+  }
+
+  if (normalizedStatus === 'manual_review') {
+    return { systemBindingStatus: 'manual_review', userBindingStatus: 'binding_exception' }
+  }
+
+  if (normalizedStatus === 'retry_pending') {
+    return { systemBindingStatus: 'retry_pending', userBindingStatus: 'binding_exception' }
+  }
+
+  if (normalizedStatus === 'closed') {
+    return { systemBindingStatus: 'closed', userBindingStatus: 'closed' }
+  }
+
+  if (normalizedStatus === 'expired') {
+    return { systemBindingStatus: 'expired', userBindingStatus: 'expired' }
+  }
+
+  if (normalizedStatus === 'link_generated') {
+    return { systemBindingStatus: 'system_bound', userBindingStatus: 'waiting_user_claim' }
+  }
+
+  if (normalizedStatus === 'claimed') {
+    return { systemBindingStatus: 'system_bound', userBindingStatus: 'link_opened' }
+  }
+
+  if (normalizedStatus === 'role_confirmed') {
+    return { systemBindingStatus: 'system_bound', userBindingStatus: 'binding_confirmed' }
+  }
+
+  if (normalizedStatus === 'redeeming') {
+    return { systemBindingStatus: 'system_bound', userBindingStatus: 'binding_in_progress' }
+  }
+
+  if (normalizedStatus === 'redeemed') {
+    return { systemBindingStatus: 'system_bound', userBindingStatus: 'binding_completed' }
+  }
+
+  if (isTaskSystemBound(task)) {
+    return { systemBindingStatus: 'system_bound', userBindingStatus: 'waiting_user_claim' }
+  }
+
+  return { systemBindingStatus: 'pending_binding', userBindingStatus: 'not_started' }
+}
+
+function isTaskSystemBound(task) {
+  return Boolean(task && (getTaskPrimaryInventoryItemId(task) || getTaskPrimaryClaimTokenId(task)))
+}
+
+function mapAgisoAutoDeliveryContext(value) {
+  if (!value || typeof value !== 'object') {
+    return null
+  }
+
+  return {
+    status: String(value.status || '').trim(),
+    trigger: String(value.trigger || '').trim(),
+    reason: String(value.reason || '').trim(),
+    platformOrderId: String(value.platformOrderId || '').trim(),
+    responseStatus: Number(value.responseStatus || 0),
+    errorMessage: String(value.errorMessage || '').trim(),
+    requestId: String(value.requestId || '').trim(),
+    aldsType: Number(value.aldsType || 0) || null,
+    updatedAt: value.updatedAt || null,
+  }
+}
+
+function normalizeRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {}
+}
+
+function maskCode(value) {
+  const text = String(value || '').trim()
+  if (!text) {
+    return ''
+  }
+  if (text.length <= 8) {
+    return `${text.slice(0, 2)}****${text.slice(-2)}`
+  }
+  return `${text.slice(0, 4)}****${text.slice(-4)}`
+}
+
+function getTaskRetryCount(task) {
+  return Number(task?.attempt_count || 0)
+}

apps/backend/src/services/admin/admin-write-service.js

@@ -28,16 +28,20 @@ import {
   canViewerConfirmAssistedRole,
   canViewerRedeemAssistedTask,
   createAdminViewerContext,
-  getRequiredInventoryItem,
-  getRequiredTask,
   getTaskPrimaryClaimTokenId,
   getTaskPrimaryInventoryItemId,
   isAssistedClaimTask,
   isManualDispatchTask,
-  mapAdminInventoryListItem,
-  mapTaskActionPayload,
   parseTaskContext,
+} from './admin-read-shared-helpers.js'
+import {
+  getRequiredInventoryItem,
+  mapAdminInventoryListItem,
 } from './admin-read-helpers.js'
+import {
+  getRequiredTask,
+  mapTaskActionPayload,
+} from './admin-task-read-helpers.js'
 
 /** @typedef {import('../../types/admin-read-inputs.js').AdminEntityIdInput} AdminEntityIdInput */
 /** @typedef {import('../../types/admin-read-inputs.js').AdminViewerSessionInput} AdminViewerSessionInput */

apps/backend/src/types/admin-read-inputs.js

@@ -69,6 +69,21 @@ export {}
  * }} AdminWebhookEventListQueryInput
  */
 
+/**
+ * @typedef {{
+ *   page?: number | string
+ *   pageSize?: number | string
+ *   provider?: string
+ *   platform?: string
+ *   status?: string
+ *   shopId?: string
+ *   platformOrderId?: string
+ *   taskNo?: string
+ *   dateFrom?: string
+ *   dateTo?: string
+ * }} AdminMessageDeliveryListQueryInput
+ */
+
 /**
  * @typedef {number | string} AdminEntityIdInput
  */

apps/backend/src/types/admin-route-inputs.js

@@ -0,0 +1,75 @@
+// @ts-check
+
+export {}
+
+/**
+ * @typedef {import('./admin-read-inputs.js').AdminInventoryListQueryInput} AdminInventoryRouteQuery
+ */
+
+/**
+ * @typedef {import('./admin-read-inputs.js').AdminInventorySkuSuggestionQueryInput} AdminInventorySkuSuggestionRouteQuery
+ */
+
+/**
+ * @typedef {import('./admin-read-inputs.js').AdminMessageDeliveryListQueryInput} AdminMessageDeliveryRouteQuery
+ */
+
+/**
+ * @typedef {import('./admin-read-inputs.js').AdminOrderListQueryInput} AdminOrderRouteQuery
+ */
+
+/**
+ * @typedef {import('./admin-read-inputs.js').AdminTaskListQueryInput} AdminTaskRouteQuery
+ */
+
+/**
+ * @typedef {import('./admin-read-inputs.js').AdminViewerSessionInput} AdminRouteAdminSession
+ */
+
+/**
+ * @typedef {import('./admin-read-inputs.js').AdminWebhookEventListQueryInput} AdminWebhookEventRouteQuery
+ */
+
+/**
+ * @typedef {import('./admin-write-inputs.js').AdminAgisoShopConfigSaveInput} AdminAgisoShopConfigRouteBody
+ */
+
+/**
+ * @typedef {import('./admin-write-inputs.js').AdminFulfillmentBindingConfigSaveInput} AdminFulfillmentBindingConfigRouteBody
+ */
+
+/**
+ * @typedef {import('./admin-write-inputs.js').AdminFulfillmentBindingLookupInput} AdminFulfillmentBindingLookupRouteBody
+ */
+
+/**
+ * @typedef {import('./admin-write-inputs.js').AdminInventoryCreateInput} AdminInventoryCreateRouteBody
+ */
+
+/**
+ * @typedef {import('./admin-write-inputs.js').AdminInventoryImportInput} AdminInventoryImportRouteBody
+ */
+
+/**
+ * @typedef {import('./admin-write-inputs.js').AdminInventoryInvalidateInput} AdminInventoryInvalidateRouteBody
+ */
+
+/**
+ * @typedef {import('./admin-write-inputs.js').AdminTaskManualDispatchInput} AdminTaskManualDispatchRouteBody
+ */
+
+/**
+ * @typedef {{ inventoryItemId?: string }} AdminInventoryRouteParams
+ */
+
+/**
+ * @typedef {{ orderId?: string }} AdminOrderRouteParams
+ */
+
+/**
+ * @typedef {{ taskId?: string, bindingId?: string }} AdminTaskRouteParams
+ */
+
+/**
+ * @typedef {{ eventId?: string }} AdminWebhookEventRouteParams
+ */

apps/backend/src/types/admin-write-inputs.js

@@ -49,8 +49,52 @@ export {}
  * }} AdminAgisoShopConfigSaveInput
  */
 
+/**
+ * @typedef {{
+ *   provider?: string
+ *   platform?: string
+ *   shopId?: string
+ *   platformOrderId?: string
+ * }} AdminFulfillmentBindingLookupInput
+ */
+
+/**
+ * @typedef {{
+ *   provider?: string
+ *   platform?: string
+ *   shopId?: string
+ *   skuCode?: string
+ *   skuName?: string
+ *   profileKey?: string
+ *   enabled?: boolean
+ *   priority?: number | string
+ *   config?: Record<string, unknown>
+ *   match?: {
+ *     externalSkuCode?: string
+ *     externalItemId?: string
+ *     externalSkuName?: string
+ *     config?: Record<string, unknown>
+ *   }
+ * }} AdminFulfillmentBindingConfigWriteItemInput
+ */
+
+/**
+ * @typedef {{
+ *   bindings?: AdminFulfillmentBindingConfigWriteItemInput[]
+ * }} AdminFulfillmentBindingConfigSaveInput
+ */
+
 /**
  * @typedef {{
  *   reason?: string
  * }} AdminInventoryInvalidateInput
  */
+
+/**
+ * @typedef {{
+ *   outcome?: string
+ *   resultMessage?: string
+ *   deliveryReference?: string
+ *   deliveredCredential?: string
+ * }} AdminTaskManualDispatchInput
+ */

apps/backend/tsconfig.json

@@ -20,12 +20,22 @@
     "src/repositories/task-repo.js",
     "src/repositories/webhook-event-repo.js",
     "src/services/admin/admin-read-helpers.js",
+    "src/services/admin/admin-read-shared-helpers.js",
+    "src/services/admin/admin-task-read-helpers.js",
     "src/services/admin/admin-dashboard-service.js",
     "src/services/admin/admin-message-delivery-service.js",
     "src/services/admin/admin-platform-config-service.js",
     "src/services/admin/admin-read-service.js",
     "src/services/admin/admin-service.js",
     "src/services/admin/admin-write-service.js",
+    "src/routes/admin/dashboard.js",
+    "src/routes/admin/inventory.js",
+    "src/routes/admin/message-deliveries.js",
+    "src/routes/admin/orders.js",
+    "src/routes/admin/platform-config.js",
+    "src/routes/admin/shared.js",
+    "src/routes/admin/tasks.js",
+    "src/routes/admin/webhook-events.js",
     "src/types/**/*.js"
   ],
   "exclude": [

docs/backend-typescript-migration-plan.md

@@ -173,6 +173,17 @@
 47. `dashboard / message-deliveries` 路由已直接依赖独立 service
 48. `admin-service.js` 已收敛为兼容导出层，不再直接承载后台业务实现
 49. 后台读 / 写 / 平台配置 / 概览 / 消息记录已分散到独立 service 模块
+50. 新增 `src/types/admin-route-inputs.js`，开始承接 `admin` 路由层的 query / body / params 共享输入边界
+51. `dashboard / inventory / orders / tasks / platform-config / message-deliveries / webhook-events` 路由已显式接入 `@ts-check` 与共享路由输入类型
+52. `src/routes/admin/shared.js` 已补齐通用 handler 的请求 / 审计签名，`adminSession` 扩展请求字段进入路由层类型检查
+53. 后台 `admin` 路由层首批已纳入 backend `typecheck` 范围，并验证通过
+54. 新增 `src/services/admin/admin-read-shared-helpers.js`，开始承接 viewer / task context / 权限判定 / 订单展示等跨读写共享 helper
+55. `admin-read-service / admin-write-service / admin-platform-config-service / admin-service` 已改为优先依赖共享 helper 模块，`admin-read-helpers.js` 职责继续收敛
+56. `npm --prefix apps/backend run typecheck` 已在共享 helper 拆分后继续通过
+57. 新增 `src/services/admin/admin-task-read-helpers.js`，开始承接任务映射、binding summary、任务动作 payload 与订单绑定汇总
+58. `admin-read-service / admin-write-service / admin-service` 已将 task 相关 helper 改为直接依赖独立 task helper 模块
+59. `admin-read-helpers.js` 已进一步收敛到 webhook / inventory / order-list 三类能力
+60. `npm --prefix apps/backend run typecheck` 已在 task helper 拆分后继续通过
 
 这一步的设计原则是“只加静态约束，不动运行链路”，所以不会影响：
 
@@ -185,9 +196,10 @@
 第一批继续推进时，建议按这个顺序：
 
 1. 为 `admin` 路由层补请求体 / 查询参数的共享输入类型
-2. 评估是否把部分 `admin-read-helpers.js` 再细拆成按领域 helper 模块
+2. 继续把 `admin-read-helpers.js` 细拆成按领域 helper 模块，下一步优先拆 `webhook` 或 `order-list` helper
-3. 继续补 repository / service 的边界约束，但不急着改 `.ts` 扩展名
+3. 为 `admin` 路由层继续补响应模型与审计 payload 的共享类型，减少 `unknown` 到处就地断言
-4. 为 webhook、库存换码、自动发货补测试
+4. 继续补 repository / service 的边界约束，但不急着改 `.ts` 扩展名
+5. 为 webhook、库存换码、自动发货补测试
 
 ## 执行原则