把 task 的 helper独立出来了

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,
-        skuCode: data.inventoryItem?.skuCode,
-        displayValue: data.inventoryItem?.displayValue,
+        inventoryItemId: result.inventoryItem?.inventoryItemId,
+        skuCode: result.inventoryItem?.skuCode,
+        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,
-        skuCode: data.inventoryItem?.skuCode,
-        invalidReason: data.inventoryItem?.invalidReason,
+        inventoryItemId: result.inventoryItem?.inventoryItemId,
+        skuCode: result.inventoryItem?.skuCode,
+        invalidReason: result.inventoryItem?.invalidReason,
       },
-    }),
+      }
+    },
   },
 ))