From ab3a8caa9fc45edc5e94bb0bc26558abf94baf81 Mon Sep 17 00:00:00 2001
From: yml <yml@yml.com>
Date: Thu, 21 May 2026 14:17:14 +0800
Subject: [PATCH] =?UTF-8?q?=E5=90=8E=E7=AB=AF=E8=BF=81=E7=A7=BB=E5=BA=93?=
 =?UTF-8?q?=E5=AD=98=E6=9C=8D=E5=8A=A1=E6=A8=A1=E5=9D=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...entory-service.js => inventory-service.ts} | 55 ++++++++++++++++---
 docs/backend-typescript-migration-plan.md     | 10 +++-
 2 files changed, 55 insertions(+), 10 deletions(-)
 rename apps/backend/src/services/order/{inventory-service.js => inventory-service.ts} (55%)

diff --git a/apps/backend/src/services/order/inventory-service.js b/apps/backend/src/services/order/inventory-service.ts
similarity index 55%
rename from apps/backend/src/services/order/inventory-service.js
rename to apps/backend/src/services/order/inventory-service.ts
index e9533fa0..e9c59aff 100644
--- a/apps/backend/src/services/order/inventory-service.js
+++ b/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) {
diff --git a/docs/backend-typescript-migration-plan.md b/docs/backend-typescript-migration-plan.md
index c3acf22e..153c8f96 100644
--- a/docs/backend-typescript-migration-plan.md
+++ b/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、自动发货
 
 ## 执行原则