后端迁移后台任务路由

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

@@ -1,5 +1,3 @@
-// @ts-check
-
 import { Router } from 'express'
 
 import {
@@ -23,22 +21,33 @@ import {
   getAdminTasks,
 } 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').AdminTaskKuaishouCloudDispatchRouteBody} AdminTaskKuaishouCloudDispatchRouteBody */
-/** @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 */
+import type { AdminExpressRequest } from './shared.js'
+import type {
+  AdminTaskKuaishouCloudDispatchRouteBody,
+  AdminTaskManualDispatchRouteBody,
+  AdminTaskRouteParams,
+  AdminTaskRouteQuery,
+} from '../../types/admin-route-inputs.js'
+import type {
+  AdminTaskActionResponse,
+  AdminTaskBindingReleaseResponse,
+  AdminTaskManualDispatchResponse,
+} from '../../types/admin-write-models.js'
 
 const router = Router()
 
+function getTaskId(req: AdminExpressRequest): string | undefined {
+  return (req.params as AdminTaskRouteParams).taskId
+}
+
+function getBindingId(req: AdminExpressRequest): string | undefined {
+  return (req.params as AdminTaskRouteParams).bindingId
+}
+
 router.get('/tasks', createJsonHandler(
   (req) => getAdminTasks(
-    /** @type {AdminTaskRouteQuery} */ (req.query),
-    /** @type {AdminRouteAdminSession | null} */ (req.adminSession),
+    req.query as AdminTaskRouteQuery,
+    req.adminSession || null,
   ),
   {
     successMessage: 'ok',
@@ -49,8 +58,8 @@ router.get('/tasks', createJsonHandler(
 
 router.get('/tasks/:taskId', createJsonHandler(
   (req) => getAdminTaskDetail(
-    (/** @type {AdminTaskRouteParams} */ (req.params)).taskId,
-    /** @type {AdminRouteAdminSession | null} */ (req.adminSession),
+    getTaskId(req),
+    req.adminSession || null,
   ),
   {
     successMessage: 'ok',
@@ -61,8 +70,8 @@ router.get('/tasks/:taskId', createJsonHandler(
 
 router.get('/tasks/:taskId/screenshot', createFileHandler(
   (req) => getAdminTaskScreenshotPath(
-    (/** @type {AdminTaskRouteParams} */ (req.params)).taskId,
-    /** @type {AdminRouteAdminSession | null} */ (req.adminSession),
+    getTaskId(req),
+    req.adminSession || null,
   ),
   {
     errorMessage: '读取任务截图失败',
@@ -71,7 +80,7 @@ router.get('/tasks/:taskId/screenshot', createFileHandler(
 ))
 
 router.post('/tasks/:taskId/retry', requireAdminRoles(['admin', 'operator']), createJsonHandler(
-  (req) => retryAdminTask((/** @type {AdminTaskRouteParams} */ (req.params)).taskId),
+  (req) => retryAdminTask(getTaskId(req)),
   {
     successMessage: '任务已重试',
     errorMessage: '重试任务失败',
@@ -80,22 +89,22 @@ router.post('/tasks/:taskId/retry', requireAdminRoles(['admin', 'operator']), cr
 ))
 
 router.post('/tasks/:taskId/release-inventory', requireAdminRoles(['admin']), createJsonHandler(
-  (req) => releaseAdminTaskInventory((/** @type {AdminTaskRouteParams} */ (req.params)).taskId),
+  (req) => releaseAdminTaskInventory(getTaskId(req)),
   {
     successMessage: '库存凭据已释放',
     errorMessage: '释放库存凭据失败',
     scope: '[admin/tasks/:taskId/release-inventory]',
     audit: (req, data) => {
-      const result = /** @type {AdminTaskActionResponse} */ (data)
+      const result = data as AdminTaskActionResponse
       return {
-      action: 'task_release_inventory',
-      targetType: 'task',
-      targetId: String((/** @type {AdminTaskRouteParams} */ (req.params)).taskId),
-      data: {
-        taskId: result.task.taskId,
-        taskNo: result.task.taskNo,
-        inventoryItemId: result.task.inventoryItemId,
-      },
+        action: 'task_release_inventory',
+        targetType: 'task',
+        targetId: String(getTaskId(req)),
+        data: {
+          taskId: result.task.taskId,
+          taskNo: result.task.taskNo,
+          inventoryItemId: result.task.inventoryItemId,
+        },
       }
     },
   },
@@ -103,25 +112,25 @@ router.post('/tasks/:taskId/release-inventory', requireAdminRoles(['admin']), cr
 
 router.post('/tasks/:taskId/inventory-bindings/:bindingId/release', requireAdminRoles(['admin']), createJsonHandler(
   (req) => releaseAdminTaskInventoryBinding(
-    (/** @type {AdminTaskRouteParams} */ (req.params)).taskId,
-    (/** @type {AdminTaskRouteParams} */ (req.params)).bindingId,
+    getTaskId(req),
+    getBindingId(req),
   ),
   {
     successMessage: '库存绑定已释放',
     errorMessage: '释放库存绑定失败',
     scope: '[admin/tasks/:taskId/inventory-bindings/:bindingId/release]',
     audit: (req, data) => {
-      const result = /** @type {AdminTaskBindingReleaseResponse} */ (data)
+      const result = data as AdminTaskBindingReleaseResponse
       return {
-      action: 'task_release_inventory_binding',
-      targetType: 'task_inventory_binding',
-      targetId: String((/** @type {AdminTaskRouteParams} */ (req.params)).bindingId),
-      data: {
-        taskId: result.task.taskId,
-        taskNo: result.task.taskNo,
-        bindingId: result.bindingId,
-        inventoryItemId: result.inventoryItemId,
-      },
+        action: 'task_release_inventory_binding',
+        targetType: 'task_inventory_binding',
+        targetId: String(getBindingId(req)),
+        data: {
+          taskId: result.task.taskId,
+          taskNo: result.task.taskNo,
+          bindingId: result.bindingId,
+          inventoryItemId: result.inventoryItemId,
+        },
       }
     },
   },
@@ -129,24 +138,24 @@ router.post('/tasks/:taskId/inventory-bindings/:bindingId/release', requireAdmin
 
 router.post('/tasks/:taskId/regenerate-claim-link', requireAdminRoles(['admin', 'operator', 'support']), createJsonHandler(
   (req) => regenerateAdminTaskClaimLink(
-    (/** @type {AdminTaskRouteParams} */ (req.params)).taskId,
-    /** @type {AdminRouteAdminSession | null} */ (req.adminSession),
+    getTaskId(req),
+    req.adminSession || null,
   ),
   {
     successMessage: '领取链接已重新生成',
     errorMessage: '重新生成领取链接失败',
     scope: '[admin/tasks/:taskId/regenerate-claim-link]',
     audit: (req, data) => {
-      const result = /** @type {AdminTaskActionResponse} */ (data)
+      const result = data as AdminTaskActionResponse
       return {
-      action: 'task_regenerate_claim_link',
-      targetType: 'task',
-      targetId: String((/** @type {AdminTaskRouteParams} */ (req.params)).taskId),
-      data: {
-        taskId: result.task.taskId,
-        taskNo: result.task.taskNo,
-        primaryClaimTokenId: result.task.primaryClaimTokenId,
-      },
+        action: 'task_regenerate_claim_link',
+        targetType: 'task',
+        targetId: String(getTaskId(req)),
+        data: {
+          taskId: result.task.taskId,
+          taskNo: result.task.taskNo,
+          primaryClaimTokenId: result.task.primaryClaimTokenId,
+        },
       }
     },
   },
@@ -154,24 +163,24 @@ router.post('/tasks/:taskId/regenerate-claim-link', requireAdminRoles(['admin',
 
 router.post('/tasks/:taskId/support-confirm-role', requireAdminRoles(['admin', 'operator', 'support']), createJsonHandler(
   (req) => confirmAdminTaskAssistedRole(
-    (/** @type {AdminTaskRouteParams} */ (req.params)).taskId,
-    /** @type {AdminRouteAdminSession | null} */ (req.adminSession),
+    getTaskId(req),
+    req.adminSession || null,
   ),
   {
     successMessage: '角色已确认',
     errorMessage: '客服确认角色失败',
     scope: '[admin/tasks/:taskId/support-confirm-role]',
     audit: (req, data) => {
-      const result = /** @type {AdminTaskActionResponse} */ (data)
+      const result = data as AdminTaskActionResponse
       return {
-      action: 'task_support_confirm_role',
-      targetType: 'task',
-      targetId: String((/** @type {AdminTaskRouteParams} */ (req.params)).taskId),
-      data: {
-        taskId: result.task.taskId,
-        taskNo: result.task.taskNo,
-        status: result.task.status,
-      },
+        action: 'task_support_confirm_role',
+        targetType: 'task',
+        targetId: String(getTaskId(req)),
+        data: {
+          taskId: result.task.taskId,
+          taskNo: result.task.taskNo,
+          status: result.task.status,
+        },
       }
     },
   },
@@ -179,69 +188,69 @@ router.post('/tasks/:taskId/support-confirm-role', requireAdminRoles(['admin', '
 
 router.post('/tasks/:taskId/support-redeem', requireAdminRoles(['admin', 'operator', 'support']), createJsonHandler(
   (req) => redeemAdminTaskAssisted(
-    (/** @type {AdminTaskRouteParams} */ (req.params)).taskId,
-    /** @type {AdminRouteAdminSession | null} */ (req.adminSession),
+    getTaskId(req),
+    req.adminSession || null,
   ),
   {
     successMessage: '兑换任务已启动',
     errorMessage: '客服发起兑换失败',
     scope: '[admin/tasks/:taskId/support-redeem]',
     audit: (req, data) => {
-      const result = /** @type {AdminTaskActionResponse} */ (data)
+      const result = data as AdminTaskActionResponse
       return {
-      action: 'task_support_redeem',
-      targetType: 'task',
-      targetId: String((/** @type {AdminTaskRouteParams} */ (req.params)).taskId),
-      data: {
-        taskId: result.task.taskId,
-        taskNo: result.task.taskNo,
-        status: result.task.status,
-        deliveryStatus: result.task.deliveryStatus,
-      },
+        action: 'task_support_redeem',
+        targetType: 'task',
+        targetId: String(getTaskId(req)),
+        data: {
+          taskId: result.task.taskId,
+          taskNo: result.task.taskNo,
+          status: result.task.status,
+          deliveryStatus: result.task.deliveryStatus,
+        },
       }
     },
   },
 ))
 
 router.post('/tasks/:taskId/close', requireAdminRoles(['admin', 'operator', 'support']), createJsonHandler(
-  (req) => closeAdminTask((/** @type {AdminTaskRouteParams} */ (req.params)).taskId),
+  (req) => closeAdminTask(getTaskId(req)),
   {
     successMessage: '任务已关闭',
     errorMessage: '关闭任务失败',
     scope: '[admin/tasks/:taskId/close]',
     audit: (req, data) => {
-      const result = /** @type {AdminTaskActionResponse} */ (data)
+      const result = data as AdminTaskActionResponse
       return {
-      action: 'task_closed',
-      targetType: 'task',
-      targetId: String((/** @type {AdminTaskRouteParams} */ (req.params)).taskId),
-      data: {
-        taskId: result.task.taskId,
-        taskNo: result.task.taskNo,
-        status: result.task.status,
-      },
+        action: 'task_closed',
+        targetType: 'task',
+        targetId: String(getTaskId(req)),
+        data: {
+          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((/** @type {AdminTaskRouteParams} */ (req.params)).taskId),
+  (req) => markAdminTaskManualReview(getTaskId(req)),
   {
     successMessage: '任务已转人工处理',
     errorMessage: '标记人工处理失败',
     scope: '[admin/tasks/:taskId/mark-manual-review]',
     audit: (req, data) => {
-      const result = /** @type {AdminTaskActionResponse} */ (data)
+      const result = data as AdminTaskActionResponse
       return {
-      action: 'task_mark_manual_review',
-      targetType: 'task',
-      targetId: String((/** @type {AdminTaskRouteParams} */ (req.params)).taskId),
-      data: {
-        taskId: result.task.taskId,
-        taskNo: result.task.taskNo,
-        status: result.task.status,
-      },
+        action: 'task_mark_manual_review',
+        targetType: 'task',
+        targetId: String(getTaskId(req)),
+        data: {
+          taskId: result.task.taskId,
+          taskNo: result.task.taskNo,
+          status: result.task.status,
+        },
       }
     },
   },
@@ -249,27 +258,27 @@ router.post('/tasks/:taskId/mark-manual-review', requireAdminRoles(['admin', 'op
 
 router.post('/tasks/:taskId/complete-manual-dispatch', requireAdminRoles(['admin', 'operator']), createJsonHandler(
   (req) => completeAdminTaskManualDispatch(
-    (/** @type {AdminTaskRouteParams} */ (req.params)).taskId,
-    /** @type {AdminTaskManualDispatchRouteBody} */ (req.body),
-    /** @type {AdminRouteAdminSession | null} */ (req.adminSession),
+    getTaskId(req),
+    req.body as AdminTaskManualDispatchRouteBody,
+    req.adminSession || null,
   ),
   {
     successMessage: '人工履约结果已回写',
     errorMessage: '回写人工履约结果失败',
     scope: '[admin/tasks/:taskId/complete-manual-dispatch]',
     audit: (req, data) => {
-      const result = /** @type {AdminTaskManualDispatchResponse} */ (data)
+      const result = data as AdminTaskManualDispatchResponse
       return {
-      action: 'task_complete_manual_dispatch',
-      targetType: 'task',
-      targetId: String((/** @type {AdminTaskRouteParams} */ (req.params)).taskId),
-      data: {
-        taskId: result.task.taskId,
-        taskNo: result.task.taskNo,
-        outcome: result.outcome,
-        deliveryStatus: result.task.deliveryStatus,
-        resultCode: result.task.resultCode,
-      },
+        action: 'task_complete_manual_dispatch',
+        targetType: 'task',
+        targetId: String(getTaskId(req)),
+        data: {
+          taskId: result.task.taskId,
+          taskNo: result.task.taskNo,
+          outcome: result.outcome,
+          deliveryStatus: result.task.deliveryStatus,
+          resultCode: result.task.resultCode,
+        },
       }
     },
   },
@@ -277,19 +286,19 @@ router.post('/tasks/:taskId/complete-manual-dispatch', requireAdminRoles(['admin
 
 router.post('/tasks/:taskId/kuaishou-cloud/prepare', requireAdminRoles(['admin', 'operator']), createJsonHandler(
   (req) => prepareAdminTaskKuaishouCloudFulfillment(
-    (/** @type {AdminTaskRouteParams} */ (req.params)).taskId,
-    /** @type {AdminRouteAdminSession | null} */ (req.adminSession),
+    getTaskId(req),
+    req.adminSession || null,
   ),
   {
     successMessage: '绑定资源已准备完成',
     errorMessage: '准备绑定资源失败',
     scope: '[admin/tasks/:taskId/kuaishou-cloud/prepare]',
     audit: (req, data) => {
-      const result = /** @type {AdminTaskActionResponse} */ (data)
+      const result = data as AdminTaskActionResponse
       return {
         action: 'task_kuaishou_cloud_prepare',
         targetType: 'task',
-        targetId: String((/** @type {AdminTaskRouteParams} */ (req.params)).taskId),
+        targetId: String(getTaskId(req)),
         data: {
           taskId: result.task.taskId,
           taskNo: result.task.taskNo,
@@ -302,19 +311,19 @@ router.post('/tasks/:taskId/kuaishou-cloud/prepare', requireAdminRoles(['admin',
 
 router.post('/tasks/:taskId/kuaishou-cloud/refresh-role-info', requireAdminRoles(['admin', 'operator', 'support']), createJsonHandler(
   (req) => refreshAdminTaskKuaishouCloudRoleInfo(
-    (/** @type {AdminTaskRouteParams} */ (req.params)).taskId,
-    /** @type {AdminRouteAdminSession | null} */ (req.adminSession),
+    getTaskId(req),
+    req.adminSession || null,
   ),
   {
     successMessage: '角色信息已刷新',
     errorMessage: '刷新角色信息失败',
     scope: '[admin/tasks/:taskId/kuaishou-cloud/refresh-role-info]',
     audit: (req, data) => {
-      const result = /** @type {AdminTaskActionResponse} */ (data)
+      const result = data as AdminTaskActionResponse
       return {
         action: 'task_kuaishou_cloud_role_info_refreshed',
         targetType: 'task',
-        targetId: String((/** @type {AdminTaskRouteParams} */ (req.params)).taskId),
+        targetId: String(getTaskId(req)),
         data: {
           taskId: result.task.taskId,
           taskNo: result.task.taskNo,
@@ -327,21 +336,21 @@ router.post('/tasks/:taskId/kuaishou-cloud/refresh-role-info', requireAdminRoles
 
 router.post('/tasks/:taskId/kuaishou-cloud/dispatch', requireAdminRoles(['admin', 'operator']), createJsonHandler(
   (req) => dispatchAdminTaskKuaishouCloudFulfillment(
-    (/** @type {AdminTaskRouteParams} */ (req.params)).taskId,
-    /** @type {AdminTaskKuaishouCloudDispatchRouteBody} */ (req.body),
-    /** @type {AdminRouteAdminSession | null} */ (req.adminSession),
+    getTaskId(req),
+    req.body as AdminTaskKuaishouCloudDispatchRouteBody,
+    req.adminSession || null,
   ),
   {
     successMessage: '已完成绑定确认并发货',
     errorMessage: '执行发货失败',
     scope: '[admin/tasks/:taskId/kuaishou-cloud/dispatch]',
     audit: (req, data) => {
-      const result = /** @type {AdminTaskActionResponse} */ (data)
-      const body = /** @type {AdminTaskKuaishouCloudDispatchRouteBody} */ (req.body)
+      const result = data as AdminTaskActionResponse
+      const body = req.body as AdminTaskKuaishouCloudDispatchRouteBody
       return {
         action: 'task_kuaishou_cloud_dispatch',
         targetType: 'task',
-        targetId: String((/** @type {AdminTaskRouteParams} */ (req.params)).taskId),
+        targetId: String(getTaskId(req)),
         data: {
           taskId: result.task.taskId,
           taskNo: result.task.taskNo,
@@ -356,19 +365,19 @@ router.post('/tasks/:taskId/kuaishou-cloud/dispatch', requireAdminRoles(['admin'
 
 router.post('/tasks/:taskId/kuaishou-cloud/return-number', requireAdminRoles(['admin', 'operator']), createJsonHandler(
   (req) => returnNumberAdminTaskKuaishouCloudFulfillment(
-    (/** @type {AdminTaskRouteParams} */ (req.params)).taskId,
-    /** @type {AdminRouteAdminSession | null} */ (req.adminSession),
+    getTaskId(req),
+    req.adminSession || null,
   ),
   {
     successMessage: '号码已退还',
     errorMessage: '退还号码失败',
     scope: '[admin/tasks/:taskId/kuaishou-cloud/return-number]',
     audit: (req, data) => {
-      const result = /** @type {AdminTaskActionResponse} */ (data)
+      const result = data as AdminTaskActionResponse
       return {
         action: 'task_kuaishou_cloud_return_number',
         targetType: 'task',
-        targetId: String((/** @type {AdminTaskRouteParams} */ (req.params)).taskId),
+        targetId: String(getTaskId(req)),
         data: {
           taskId: result.task.taskId,
           taskNo: result.task.taskNo,