后端迁移后台管理读服务入口

apps/backend/src/services/admin/admin-read-service.ts

@@ -1,5 +1,3 @@
-// @ts-check
-
 import { buildClaimUrl } from '../claim/claim-service.js'
 import { getClaimTokenById } from '../../repositories/claim-token-repo.js'
 import {
@@ -53,22 +51,26 @@ import {
   mapAdminTaskSummary,
 } from './admin-task-read-helpers.js'
 
-/** @typedef {import('../../types/admin-read-models.js').AdminInventoryListResponse} AdminInventoryListResponse */
+import type {
-/** @typedef {import('../../types/admin-read-models.js').AdminInventorySkuSuggestionResponse} AdminInventorySkuSuggestionResponse */
+  AdminInventoryListResponse,
-/** @typedef {import('../../types/admin-read-models.js').AdminOrderListResponse} AdminOrderListResponse */
+  AdminInventorySkuSuggestionResponse,
-/** @typedef {import('../../types/admin-read-models.js').AdminTaskListResponse} AdminTaskListResponse */
+  AdminOrderListResponse,
-/** @typedef {import('../../types/admin-read-models.js').AdminWebhookEventListResponse} AdminWebhookEventListResponse */
+  AdminTaskListResponse,
-/** @typedef {import('../../types/admin-read-inputs.js').AdminEntityIdInput} AdminEntityIdInput */
+  AdminWebhookEventListResponse,
-/** @typedef {import('../../types/admin-read-inputs.js').AdminInventoryListQueryInput} AdminInventoryListQueryInput */
+} from '../../types/admin-read-models.js'
-/** @typedef {import('../../types/admin-read-inputs.js').AdminInventorySkuSuggestionQueryInput} AdminInventorySkuSuggestionQueryInput */
+import type {
-/** @typedef {import('../../types/admin-read-inputs.js').AdminOrderListQueryInput} AdminOrderListQueryInput */
+  AdminEntityIdInput,
-/** @typedef {import('../../types/admin-read-inputs.js').AdminTaskListQueryInput} AdminTaskListQueryInput */
+  AdminInventoryListQueryInput,
-/** @typedef {import('../../types/admin-read-inputs.js').AdminViewerSessionInput} AdminViewerSessionInput */
+  AdminInventorySkuSuggestionQueryInput,
-/** @typedef {import('../../types/admin-read-inputs.js').AdminWebhookEventListQueryInput} AdminWebhookEventListQueryInput */
+  AdminOrderListQueryInput,
+  AdminTaskListQueryInput,
+  AdminViewerSessionInput,
+  AdminWebhookEventListQueryInput,
+} from '../../types/admin-read-inputs.js'
 
-/** @returns {Promise<AdminOrderListResponse>} */
+type JsonRecord = Record<string, any>
-/** @param {AdminOrderListQueryInput} [query] */
+
-export async function getAdminOrders(query = /** @type {AdminOrderListQueryInput} */ ({})) {
+export async function getAdminOrders(query: AdminOrderListQueryInput = {}): Promise<AdminOrderListResponse> {
   const page = normalizePage(query.page)
   const pageSize = normalizePageSize(query.pageSize)
   const { items, total } = await listOrders({
@@ -87,8 +89,7 @@ export async function getAdminOrders(query = /** @type {AdminOrderListQueryInput
   }
 }
 
-/** @param {AdminEntityIdInput} orderId */
+export async function getAdminOrderDetail(orderId: AdminEntityIdInput): Promise<JsonRecord> {
-export async function getAdminOrderDetail(orderId) {
   const order = await getOrderById(Number(orderId))
 
   if (!order) {
@@ -160,13 +161,10 @@ export async function getAdminOrderDetail(orderId) {
   }
 }
 
-/** @returns {Promise<AdminTaskListResponse>} */
-/** @param {AdminTaskListQueryInput} [query] */
-/** @param {AdminViewerSessionInput | null} [session] */
 export async function getAdminTasks(
-  query = /** @type {AdminTaskListQueryInput} */ ({}),
+  query: AdminTaskListQueryInput = {},
-  session = null,
+  session: AdminViewerSessionInput | null = null,
-) {
+): Promise<AdminTaskListResponse> {
   const page = normalizePage(query.page)
   const pageSize = normalizePageSize(query.pageSize)
   const { items, total } = await listTasks({
@@ -193,9 +191,10 @@ export async function getAdminTasks(
   }
 }
 
-/** @param {AdminEntityIdInput} taskId */
+export async function getAdminTaskDetail(
-/** @param {AdminViewerSessionInput | null} [session] */
+  taskId: AdminEntityIdInput,
-export async function getAdminTaskDetail(taskId, session = null) {
+  session: AdminViewerSessionInput | null = null,
+): Promise<JsonRecord> {
   const task = await getTaskById(Number(taskId))
 
   if (!task) {
@@ -313,9 +312,10 @@ export async function getAdminTaskDetail(taskId, session = null) {
   }
 }
 
-/** @param {AdminEntityIdInput} taskId */
+export async function getAdminTaskScreenshotPath(
-/** @param {AdminViewerSessionInput | null} [session] */
+  taskId: AdminEntityIdInput,
-export async function getAdminTaskScreenshotPath(taskId, session = null) {
+  session: AdminViewerSessionInput | null = null,
+): Promise<string> {
   const task = await getRequiredTask(taskId)
 
   if (task.screenshot_path) {
@@ -332,10 +332,10 @@ export async function getAdminTaskScreenshotPath(taskId, session = null) {
   })
 }
 
-/** @returns {Promise<AdminInventoryListResponse>} */
+export async function getAdminInventoryItems(
-/** @param {AdminInventoryListQueryInput} [query] */
+  query: AdminInventoryListQueryInput = {},
-/** @param {AdminViewerSessionInput | null} [session] */
+  session: AdminViewerSessionInput | null = null,
-export async function getAdminInventoryItems(query = /** @type {AdminInventoryListQueryInput} */ ({}), session = null) {
+): Promise<AdminInventoryListResponse> {
   const page = normalizePage(query.page)
   const pageSize = normalizePageSize(query.pageSize)
   const viewerContext = createAdminViewerContext(session)
@@ -356,12 +356,10 @@ export async function getAdminInventoryItems(query = /** @type {AdminInventoryLi
   }
 }
 
-/** @returns {Promise<AdminInventorySkuSuggestionResponse>} */
-/** @param {AdminInventorySkuSuggestionQueryInput} [query] */
 export async function getAdminInventorySkuSuggestions(
-  query = /** @type {AdminInventorySkuSuggestionQueryInput} */ ({}),
+  query: AdminInventorySkuSuggestionQueryInput = {},
-  session = null,
+  session: AdminViewerSessionInput | null = null,
-) {
+): Promise<AdminInventorySkuSuggestionResponse> {
   const viewerContext = createAdminViewerContext(session)
   const credentialType = String(query.credentialType || '').trim()
   const keyword = String(query.keyword || '').trim()
@@ -390,9 +388,9 @@ export async function getAdminInventorySkuSuggestions(
   }
 }
 
-/** @returns {Promise<AdminWebhookEventListResponse>} */
+export async function getAdminWebhookEvents(
-/** @param {AdminWebhookEventListQueryInput} [query] */
+  query: AdminWebhookEventListQueryInput = {},
-export async function getAdminWebhookEvents(query = /** @type {AdminWebhookEventListQueryInput} */ ({})) {
+): Promise<AdminWebhookEventListResponse> {
   const page = normalizePage(query.page)
   const pageSize = normalizePageSize(query.pageSize)
   const { items, total } = await listWebhookEvents({
@@ -414,8 +412,7 @@ export async function getAdminWebhookEvents(query = /** @type {AdminWebhookEvent
   }
 }
 
-/** @param {AdminEntityIdInput} eventId */
+export async function getAdminWebhookEventDetail(eventId: AdminEntityIdInput): Promise<JsonRecord> {
-export async function getAdminWebhookEventDetail(eventId) {
   const event = await getWebhookEventById(Number(eventId))
 
   if (!event) {

docs/backend-typescript-migration-plan.md

@@ -760,6 +760,14 @@
     - `npm run typecheck`
     - `npm run build`
     - `npm test` 共 139 个用例通过
+192. 后台 Admin 读服务聚合入口迁移到 `.ts`：
+    - `src/services/admin/admin-read-service.ts`
+193. Admin 订单列表 / 详情、任务列表 / 详情 / 截图、库存列表 / SKU 建议、Webhook 列表 / 详情聚合入口已进入 TS 编译链路；列表 query、viewer session、entity id、分页响应模型与详情动态聚合对象补齐类型
+194. Docker 内验证通过：
+    - `src/services/admin/*.test.js` 共 8 个用例通过
+    - `npm run typecheck`
+    - `npm run build`
+    - `npm test` 共 139 个用例通过
 
 ## 下一步建议