把 task 的 helper独立出来了

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,
-        taskNo: data.task.taskNo,
-        inventoryItemId: data.task.inventoryItemId,
+        taskId: result.task.taskId,
+        taskNo: result.task.taskNo,
+        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,
-        taskNo: data.task.taskNo,
-        bindingId: data.bindingId,
-        inventoryItemId: data.inventoryItemId,
+        taskId: result.task.taskId,
+        taskNo: result.task.taskNo,
+        bindingId: result.bindingId,
+        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,
-        taskNo: data.task.taskNo,
-        primaryClaimTokenId: data.task.primaryClaimTokenId,
+        taskId: result.task.taskId,
+        taskNo: result.task.taskNo,
+        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,
-        taskNo: data.task.taskNo,
-        status: data.task.status,
+        taskId: result.task.taskId,
+        taskNo: result.task.taskNo,
+        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,
-        taskNo: data.task.taskNo,
-        status: data.task.status,
-        deliveryStatus: data.task.deliveryStatus,
+        taskId: result.task.taskId,
+        taskNo: result.task.taskNo,
+        status: result.task.status,
+        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,
-        taskNo: data.task.taskNo,
-        status: data.task.status,
+        taskId: result.task.taskId,
+        taskNo: result.task.taskNo,
+        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,
-        taskNo: data.task.taskNo,
-        status: data.task.status,
+        taskId: result.task.taskId,
+        taskNo: result.task.taskNo,
+        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,
-        taskNo: data.task.taskNo,
-        outcome: data.outcome,
-        deliveryStatus: data.task.deliveryStatus,
-        resultCode: data.task.resultCode,
+        taskId: result.task.taskId,
+        taskNo: result.task.taskNo,
+        outcome: result.outcome,
+        deliveryStatus: result.task.deliveryStatus,
+        resultCode: result.task.resultCode,
       },
-    }),
+      }
+    },
   },
 ))