后端迁移库存服务模块

apps/backend/src/services/order/inventory-service.ts

@@ -3,15 +3,49 @@ import {
   findFirstAvailableInventoryItemBySkuCode,
   releaseReservedInventoryItem,
 } from '../../repositories/inventory-repo.js'
+import type { InventoryItemRow } from '../../types/repository-rows.js'
 import { nowIso } from '../../utils/time.js'
 
+type InventoryItemId = number | string | null | undefined
+type InventoryGroupCodesInput = string | string[] | null | undefined
+
+type ReserveInventoryForTaskInput = {
+  skuCode?: string
+  taskId: number | string
+  credentialType?: string
+  roleKey?: string
+  inventoryGroupCodes?: InventoryGroupCodesInput
+}
+
+type ReserveInventoryForTaskDeps = {
+  assignReservedInventoryItem?: (
+    inventoryItemId: number | string,
+    taskId: number | string,
+    updatedAt: string,
+    roleKey?: string,
+  ) => Promise<InventoryItemRow | null>
+  findFirstAvailableInventoryItemBySkuCode?: (
+    skuCode: string,
+    credentialType?: string,
+    inventoryGroupCodes?: InventoryGroupCodesInput,
+  ) => Promise<InventoryItemRow | null>
+  nowIso?: () => string
+}
+
+type ReleaseReservedInventoryItemsDeps = {
+  releaseReservedInventoryItem?: (
+    inventoryItemId: number | string,
+    updatedAt: string,
+  ) => Promise<InventoryItemRow | null>
+}
+
 export async function reserveInventoryForTask({
   skuCode,
   taskId,
   credentialType = 'tencent_code',
   roleKey = 'primary_code',
   inventoryGroupCodes = null,
-}) {
+}: ReserveInventoryForTaskInput): Promise<InventoryItemRow | null> {
   return reserveInventoryForTaskWithDeps(
     { skuCode, taskId, credentialType, roleKey, inventoryGroupCodes },
     {
@@ -29,13 +63,13 @@ export async function reserveInventoryForTaskWithDeps(
     credentialType = 'tencent_code',
     roleKey = 'primary_code',
     inventoryGroupCodes = null,
-  },
+  }: ReserveInventoryForTaskInput,
   {
     assignReservedInventoryItem: assignReserved = assignReservedInventoryItem,
     findFirstAvailableInventoryItemBySkuCode: findAvailable = findFirstAvailableInventoryItemBySkuCode,
     nowIso: getNowIso = nowIso,
-  } = {},
-) {
+  }: ReserveInventoryForTaskDeps = {},
+): Promise<InventoryItemRow | null> {
   if (!skuCode) {
     return null
   }
@@ -53,7 +87,10 @@ export async function reserveInventoryForTaskWithDeps(
   return assignReserved(available.id, taskId, getNowIso(), roleKey)
 }
 
-export async function releaseReservedInventoryItems(inventoryItemIds = [], updatedAt = nowIso()) {
+export async function releaseReservedInventoryItems(
+  inventoryItemIds: InventoryItemId[] = [],
+  updatedAt = nowIso(),
+): Promise<InventoryItemRow[]> {
   return releaseReservedInventoryItemsWithDeps(
     inventoryItemIds,
     updatedAt,
@@ -62,13 +99,13 @@ export async function releaseReservedInventoryItems(inventoryItemIds = [], updat
 }
 
 export async function releaseReservedInventoryItemsWithDeps(
-  inventoryItemIds = [],
+  inventoryItemIds: InventoryItemId[] = [],
   updatedAt = nowIso(),
   {
     releaseReservedInventoryItem: releaseReserved = releaseReservedInventoryItem,
-  } = {},
-) {
-  const released = []
+  }: ReleaseReservedInventoryItemsDeps = {},
+): Promise<InventoryItemRow[]> {
+  const released: InventoryItemRow[] = []
 
   for (const inventoryItemId of inventoryItemIds) {
     if (!inventoryItemId) {

docs/backend-typescript-migration-plan.md

@@ -256,13 +256,21 @@
     - `npm run typecheck`
     - `npm run build`
     - `npm test` 共 125 个用例通过
+25. 服务层首批迁移到 `.ts`：
+    - `src/services/order/inventory-service.ts`
+26. 库存服务的 reserve/release 输入、依赖注入函数、返回库存行已显式类型化
+27. Docker 内验证通过：
+    - `src/services/order/inventory-service.test.js` 共 5 个用例通过
+    - `npm run typecheck`
+    - `npm run build`
+    - `npm test` 共 125 个用例通过
 
 ## 下一步建议
 
 第一批继续推进时，建议按这个顺序：
 
 1. 继续迁移服务层中最核心、最常改的订单 / 履约 / claim 模块
-2. 逐步移除服务层 `@ts-nocheck`，优先处理自动发货、claim session、webhook service
+2. 逐步移除服务层 `@ts-nocheck`，优先处理 claim session、webhook service、自动发货
 
 ## 执行原则