task-72(ASIN 数据中心): 实现查询 ASIN 导入与轮询

POST /api/admin/query-asins/import(file+可选groupId) 启动导入添加, GET
/import/{importId} 轮询进度(QueryAsinImportProgressVo 含 deletedCount),
11 个纯逻辑契约测试覆盖启动/轮询/终态/文案。

admin-frontend-vue/src/pages/asin/query-asin-import-api.ts

@@ -0,0 +1,26 @@
+/** 查询 ASIN 导入添加适配（任务 72）：multipart POST /import(file[+groupId]) → importId，及进度轮询。 */
+import { http } from '@/api/http'
+import {
+  parseQueryAsinImportProgress,
+  parseQueryAsinImportStart,
+  type QueryAsinImportProgress,
+} from './query-asin-import-model'
+
+export const QUERY_ASIN_IMPORT_ENDPOINT = '/api/admin/query-asins/import'
+
+/** 启动导入添加；groupId 为 Excel 未提供分组时的兜底，可选（>=1 才下发）。 */
+export async function startQueryAsinImport(file: File, groupId?: number): Promise<string> {
+  const form = new FormData()
+  form.append('file', file, file.name)
+  if (typeof groupId === 'number' && Number.isFinite(groupId) && groupId >= 1) {
+    form.append('groupId', String(Math.floor(groupId)))
+  }
+  const { data } = await http.post<unknown>(QUERY_ASIN_IMPORT_ENDPOINT, form)
+  return parseQueryAsinImportStart(data)
+}
+
+/** 查询导入添加进度：GET /import/{importId}。 */
+export async function fetchQueryAsinImportProgress(importId: string): Promise<QueryAsinImportProgress> {
+  const { data } = await http.get<unknown>(`${QUERY_ASIN_IMPORT_ENDPOINT}/${importId}`)
+  return parseQueryAsinImportProgress(data)
+}

admin-frontend-vue/src/pages/asin/query-asin-import-model.ts

@@ -0,0 +1,86 @@
+/** 查询 ASIN 导入模型（任务 72）：启动结果解析 + xlsx 校验 + 进度归一(含 deletedCount)，纯逻辑。 */
+import { unwrap } from '../../api/envelope.ts'
+
+export const QUERY_ASIN_IMPORT_ALLOWED_EXT = /\.(xlsx|xls)$/i
+
+/** 是否为允许导入的 Excel 文件。 */
+export function isAllowedQueryAsinImportFile(fileName: unknown): boolean {
+  return typeof fileName === 'string' && QUERY_ASIN_IMPORT_ALLOWED_EXT.test(fileName.trim())
+}
+
+/** 解包导入启动结果并取回 importId；缺省抛可读错误。 */
+export function parseQueryAsinImportStart(payload: unknown): string {
+  const data = unwrap<unknown>(payload)
+  const record = data && typeof data === 'object' ? (data as Record<string, unknown>) : null
+  const importId = typeof record?.importId === 'string' ? record.importId.trim() : ''
+  if (!importId) throw new Error('导入任务响应异常：缺少任务 ID')
+  return importId
+}
+
+export type QueryAsinImportStatus = 'pending' | 'running' | 'success' | 'failed'
+
+export interface QueryAsinImportProgress {
+  status: QueryAsinImportStatus
+  totalRows: number
+  processedRows: number
+  asinCount: number
+  insertedCount: number
+  deletedCount: number
+  skippedCount: number
+  errorMessage?: string
+}
+
+function intOrZero(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) ? Math.floor(value) : 0
+}
+
+/** 归一化导入进度负载；缺省按未开始(pending)处理，未知状态不改。 */
+export function parseQueryAsinImportProgress(payload: unknown): QueryAsinImportProgress {
+  const data = unwrap<unknown>(payload)
+  const record = data && typeof data === 'object' ? (data as Record<string, unknown>) : null
+  const rawStatus = typeof record?.status === 'string' ? record.status.trim().toLowerCase() : ''
+  const status: QueryAsinImportStatus =
+    rawStatus === 'running' || rawStatus === 'success' || rawStatus === 'failed' || rawStatus === 'pending'
+      ? rawStatus
+      : 'pending'
+  const progress: QueryAsinImportProgress = {
+    status,
+    totalRows: intOrZero(record?.totalRows),
+    processedRows: intOrZero(record?.processedRows),
+    asinCount: intOrZero(record?.asinCount),
+    insertedCount: intOrZero(record?.insertedCount),
+    deletedCount: intOrZero(record?.deletedCount),
+    skippedCount: intOrZero(record?.skippedCount),
+  }
+  const errorMessage =
+    typeof record?.errorMessage === 'string' && record.errorMessage.trim()
+      ? record.errorMessage.trim()
+      : undefined
+  if (errorMessage) progress.errorMessage = errorMessage
+  return progress
+}
+
+/** 是否到达终态(success/failed)。 */
+export function queryAsinImportFinished(progress: Pick<QueryAsinImportProgress, 'status'>): boolean {
+  return progress.status === 'success' || progress.status === 'failed'
+}
+
+/** 是否成功完成。 */
+export function queryAsinImportSucceeded(progress: Pick<QueryAsinImportProgress, 'status'>): boolean {
+  return progress.status === 'success'
+}
+
+/** 结果文案：pending/running/success/failed 分别给等待、进度、完成/失败可读行。 */
+export function queryAsinImportOutcomeText(progress: QueryAsinImportProgress): string {
+  switch (progress.status) {
+    case 'running':
+      return `导入处理中：已处理 ${progress.processedRows}/${progress.totalRows} 行`
+    case 'success':
+      return `导入完成：处理 ${progress.insertedCount} 条，跳过 ${progress.skippedCount} 条`
+    case 'failed':
+      return progress.errorMessage ? `导入失败：${progress.errorMessage}` : '导入失败，请重试'
+    case 'pending':
+    default:
+      return '等待导入任务开始…'
+  }
+}

admin-frontend-vue/tests/task-72.test.ts

@@ -0,0 +1,121 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { readSource } from './helpers.ts'
+import {
+  isAllowedQueryAsinImportFile,
+  parseQueryAsinImportStart,
+  parseQueryAsinImportProgress,
+  queryAsinImportFinished,
+  queryAsinImportSucceeded,
+  queryAsinImportOutcomeText,
+} from '../src/pages/asin/query-asin-import-model.ts'
+
+test('test_task_072_query_asin_import_start_normal_primary_path', () => {
+  // 正常主路径：导入启动结果 {importId} 解析出任务 id。
+  assert.equal(
+    parseQueryAsinImportStart({ success: true, data: { importId: 'job_qas_a1' } }),
+    'job_qas_a1',
+  )
+})
+
+test('test_task_072_query_asin_import_start_normal_variant_input', () => {
+  // 正常变体：已解包对象直传同样解析。
+  assert.equal(parseQueryAsinImportStart({ importId: 'job_qas_b2' }), 'job_qas_b2')
+})
+
+test('test_task_072_query_asin_import_start_normal_repeated_operation_is_idempotent', () => {
+  // 正常重复：解析纯函数稳定。
+  const payload = { success: true, data: { importId: 'job_qas_abc' } }
+  assert.equal(parseQueryAsinImportStart(payload), parseQueryAsinImportStart(payload))
+})
+
+test('test_task_072_query_asin_import_start_boundary_empty_input', () => {
+  // 边界空值：缺 importId → 可读错误。
+  assert.throws(() => parseQueryAsinImportStart({ success: true, data: {} }), /任务/)
+  assert.throws(() => parseQueryAsinImportStart({}), /任务/)
+})
+
+test('test_task_072_query_asin_import_start_boundary_single_item', () => {
+  // 边界单元素：.xlsx 文件名合法（xls 亦允许）。
+  assert.equal(isAllowedQueryAsinImportFile('query-asin.xlsx'), true)
+  assert.equal(isAllowedQueryAsinImportFile('query-asin.xls'), true)
+})
+
+test('test_task_072_query_asin_import_start_boundary_limit_or_missing_field', () => {
+  // 边界上限/缺字段：非 Excel 被拒、空文件名被拒。
+  assert.equal(isAllowedQueryAsinImportFile('data.csv'), false)
+  assert.equal(isAllowedQueryAsinImportFile(''), false)
+  assert.equal(isAllowedQueryAsinImportFile(undefined as never), false)
+})
+
+test('test_task_072_query_asin_import_start_invalid_input_rejected', () => {
+  // 异常输入：success=false 抛后端 message。
+  assert.throws(
+    () => parseQueryAsinImportStart({ success: false, message: '仅支持 .xlsx 或 .xls 文件' }),
+    /仅支持/,
+  )
+})
+
+test('test_task_072_query_asin_import_poll_normal_running_and_terminal', () => {
+  // 正常主路径：running 进度各计数可读；success 终态判定成功不再轮询。
+  const running = parseQueryAsinImportProgress({
+    success: true,
+    data: {
+      status: 'running',
+      totalRows: 120,
+      processedRows: 60,
+      asinCount: 58,
+      insertedCount: 40,
+      deletedCount: 0,
+      skippedCount: 18,
+    },
+  })
+  assert.equal(running.status, 'running')
+  assert.equal(running.processedRows, 60)
+  assert.equal(running.insertedCount, 40)
+  assert.equal(running.deletedCount, 0)
+  assert.equal(queryAsinImportFinished(running), false)
+
+  const done = parseQueryAsinImportProgress({ success: true, data: { status: 'success', insertedCount: 9 } })
+  assert.equal(done.insertedCount, 9)
+  assert.equal(queryAsinImportSucceeded(done), true)
+  assert.equal(queryAsinImportFinished(done), true)
+})
+
+test('test_task_072_query_asin_import_poll_boundary_and_failed', () => {
+  // 边界：空负载按 pending 不崩溃；failed 终态完成但未成功且错误可读。
+  const empty = parseQueryAsinImportProgress({})
+  assert.equal(empty.status, 'pending')
+  assert.equal(queryAsinImportFinished(empty), false)
+  assert.equal(queryAsinImportSucceeded(empty), false)
+
+  const failed = parseQueryAsinImportProgress({
+    success: true,
+    data: { status: 'failed', errorMessage: 'Excel 缺少店铺名列' },
+  })
+  assert.equal(queryAsinImportFinished(failed), true)
+  assert.equal(queryAsinImportSucceeded(failed), false)
+  assert.match(failed.errorMessage || '', /店铺名/)
+})
+
+test('test_task_072_query_asin_import_outcome_text_normal', () => {
+  // 结果文案：running/success/failed/pending 各给可读行。
+  assert.match(queryAsinImportOutcomeText({ status: 'running', processedRows: 3, totalRows: 9 }), /3\/9/)
+  const ok = queryAsinImportOutcomeText({ status: 'success', insertedCount: 4, skippedCount: 1 })
+  assert.match(ok, /4/)
+  assert.match(queryAsinImportOutcomeText({ status: 'failed', errorMessage: '解析失败' }), /解析失败/)
+  assert.match(queryAsinImportOutcomeText({ status: 'pending' }), /等待/)
+})
+
+test('test_task_072_query_asin_import_dependency_failure_returns_actionable_message', () => {
+  // 依赖失败/轮询走 adapter：multipart POST /import + GET /import/{importId}，页面不内联。
+  const api = readSource('src/pages/asin/query-asin-import-api.ts')
+  assert.match(api, /query-asins\/import/)
+  assert.match(api, /http\.post/)
+  assert.match(api, /http\.get/)
+  assert.match(api, /FormData/)
+  assert.match(api, /startQueryAsinImport/)
+  assert.match(api, /fetchQueryAsinImportProgress/)
+  const mod = readSource('src/pages/asin/query-asin-import-model.ts')
+  assert.equal(/axios|http\./.test(mod), false, '查询 ASIN 导入模型保持纯逻辑')
+})