diff --git a/apps/backend/src/services/admin/admin-read-service.js b/apps/backend/src/services/admin/admin-read-service.ts similarity index 83% rename from apps/backend/src/services/admin/admin-read-service.js rename to apps/backend/src/services/admin/admin-read-service.ts index ea8ec21b..7569b79e 100644 --- a/apps/backend/src/services/admin/admin-read-service.js +++ b/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 */ -/** @typedef {import('../../types/admin-read-models.js').AdminInventorySkuSuggestionResponse} AdminInventorySkuSuggestionResponse */ -/** @typedef {import('../../types/admin-read-models.js').AdminOrderListResponse} AdminOrderListResponse */ -/** @typedef {import('../../types/admin-read-models.js').AdminTaskListResponse} AdminTaskListResponse */ -/** @typedef {import('../../types/admin-read-models.js').AdminWebhookEventListResponse} AdminWebhookEventListResponse */ -/** @typedef {import('../../types/admin-read-inputs.js').AdminEntityIdInput} AdminEntityIdInput */ -/** @typedef {import('../../types/admin-read-inputs.js').AdminInventoryListQueryInput} AdminInventoryListQueryInput */ -/** @typedef {import('../../types/admin-read-inputs.js').AdminInventorySkuSuggestionQueryInput} AdminInventorySkuSuggestionQueryInput */ -/** @typedef {import('../../types/admin-read-inputs.js').AdminOrderListQueryInput} AdminOrderListQueryInput */ -/** @typedef {import('../../types/admin-read-inputs.js').AdminTaskListQueryInput} AdminTaskListQueryInput */ -/** @typedef {import('../../types/admin-read-inputs.js').AdminViewerSessionInput} AdminViewerSessionInput */ -/** @typedef {import('../../types/admin-read-inputs.js').AdminWebhookEventListQueryInput} AdminWebhookEventListQueryInput */ +import type { + AdminInventoryListResponse, + AdminInventorySkuSuggestionResponse, + AdminOrderListResponse, + AdminTaskListResponse, + AdminWebhookEventListResponse, +} from '../../types/admin-read-models.js' +import type { + AdminEntityIdInput, + AdminInventoryListQueryInput, + AdminInventorySkuSuggestionQueryInput, + AdminOrderListQueryInput, + AdminTaskListQueryInput, + AdminViewerSessionInput, + AdminWebhookEventListQueryInput, +} from '../../types/admin-read-inputs.js' -/** @returns {Promise} */ -/** @param {AdminOrderListQueryInput} [query] */ -export async function getAdminOrders(query = /** @type {AdminOrderListQueryInput} */ ({})) { +type JsonRecord = Record + +export async function getAdminOrders(query: AdminOrderListQueryInput = {}): Promise { 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) { +export async function getAdminOrderDetail(orderId: AdminEntityIdInput): Promise { const order = await getOrderById(Number(orderId)) if (!order) { @@ -160,13 +161,10 @@ export async function getAdminOrderDetail(orderId) { } } -/** @returns {Promise} */ -/** @param {AdminTaskListQueryInput} [query] */ -/** @param {AdminViewerSessionInput | null} [session] */ export async function getAdminTasks( - query = /** @type {AdminTaskListQueryInput} */ ({}), - session = null, -) { + query: AdminTaskListQueryInput = {}, + session: AdminViewerSessionInput | null = null, +): Promise { 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 */ -/** @param {AdminViewerSessionInput | null} [session] */ -export async function getAdminTaskDetail(taskId, session = null) { +export async function getAdminTaskDetail( + taskId: AdminEntityIdInput, + session: AdminViewerSessionInput | null = null, +): Promise { const task = await getTaskById(Number(taskId)) if (!task) { @@ -313,9 +312,10 @@ export async function getAdminTaskDetail(taskId, session = null) { } } -/** @param {AdminEntityIdInput} taskId */ -/** @param {AdminViewerSessionInput | null} [session] */ -export async function getAdminTaskScreenshotPath(taskId, session = null) { +export async function getAdminTaskScreenshotPath( + taskId: AdminEntityIdInput, + session: AdminViewerSessionInput | null = null, +): Promise { const task = await getRequiredTask(taskId) if (task.screenshot_path) { @@ -332,10 +332,10 @@ export async function getAdminTaskScreenshotPath(taskId, session = null) { }) } -/** @returns {Promise} */ -/** @param {AdminInventoryListQueryInput} [query] */ -/** @param {AdminViewerSessionInput | null} [session] */ -export async function getAdminInventoryItems(query = /** @type {AdminInventoryListQueryInput} */ ({}), session = null) { +export async function getAdminInventoryItems( + query: AdminInventoryListQueryInput = {}, + session: AdminViewerSessionInput | null = null, +): Promise { 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} */ -/** @param {AdminInventorySkuSuggestionQueryInput} [query] */ export async function getAdminInventorySkuSuggestions( - query = /** @type {AdminInventorySkuSuggestionQueryInput} */ ({}), - session = null, -) { + query: AdminInventorySkuSuggestionQueryInput = {}, + session: AdminViewerSessionInput | null = null, +): Promise { 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} */ -/** @param {AdminWebhookEventListQueryInput} [query] */ -export async function getAdminWebhookEvents(query = /** @type {AdminWebhookEventListQueryInput} */ ({})) { +export async function getAdminWebhookEvents( + query: AdminWebhookEventListQueryInput = {}, +): Promise { 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) { +export async function getAdminWebhookEventDetail(eventId: AdminEntityIdInput): Promise { const event = await getWebhookEventById(Number(eventId)) if (!event) { diff --git a/docs/backend-typescript-migration-plan.md b/docs/backend-typescript-migration-plan.md index bbbc4c14..e73ed73a 100644 --- a/docs/backend-typescript-migration-plan.md +++ b/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 个用例通过 ## 下一步建议