docs: 补充规格文档（specs 01-15）

2026-09-08 13:39:10 +08:00
parent 4ac8f8b472
commit b12acf7793
16 changed files with 1462 additions and 0 deletions
@@ -0,0 +1,94 @@
+# 04 ASIN 数据中心
+
+## 模块职责
+
+将旧后台中与 ASIN、品牌库、最低价和商品类目相关的页面重组为 ASIN 数据中心，保持现有 API 语义，改善筛选、导入、导出、详情抽屉和批量操作流程。
+
+覆盖页面：
+
+- 去重数据汇总：`dedupe-total-data`
+- 品牌数据库/无效 ASIN：`invalid-asin-data`
+- 查询 ASIN：`query-asin`
+- 最低价 ASIN：`skip-price-asin`
+- 商品类目：`product-categories`
+
+## 依赖关系
+
+上游：账号菜单权限、用户和数据权限分组；Java 对应控制器和服务；统一下载/上传/进度适配器。
+
+旧实现文件：
+
+- `backend/web_source/admin.html` 的 `panel-dedupe-total-data`、`panel-invalid-asin-data`、`panel-query-asin`、`panel-skip-price-asin`、`panel-product-categories`。
+- `backend/static/admin.js:loadDedupeTotalData`、`loadInvalidAsinData`、`loadQueryAsin`、`loadSkipPriceAsin`、`loadProductCategories`。
+
+## 核心接口：原实现 → 目标实现
+
+| 领域 | 原接口族 | 目标前端模块 |
+|---|---|---|
+| 去重汇总 | `/api/admin/dedupe-total-data`、`/export`、`/import`、`/delete-import`、进度查询 | `pages/asin/DedupeRegistryPage.vue` |
+| 品牌数据库 | `/api/admin/invalid-asin-data` | `pages/asin/InvalidAsinPage.vue` |
+| 查询 ASIN | `/api/admin/query-asins`、`/query-asin`、`/export`、`/import`、`/delete-import` | `pages/asin/QueryAsinPage.vue` |
+| 最低价 ASIN | `/api/admin/skip-price-asins`、`/skip-price-asin`、导入/删除导入/导出 | `pages/asin/SkipPricePage.vue` |
+| 商品类目 | `/api/admin/product-categories/*`、`/product-category` | `pages/asin/ProductCategoriesPage.vue` |
+
+API 路径保持 `/api/admin/*`，本模块只改变请求编排和页面表现，不改变后端业务规则。
+
+## 内部结构
+
+```text
+AsinCenter
+├── Registry
+│   ├── FilterBar
+│   ├── Import/ExportToolbar
+│   ├── PaginatedTable
+│   └── ImportProgressDialog
+├── InvalidAsin
+│   ├── FilterBar
+│   ├── PaginatedTable
+│   └── EditorDialog
+├── QueryAsin
+│   ├── FilterBar
+│   ├── Import/ExportToolbar
+│   ├── PaginatedTable
+│   └── DetailDrawer
+├── SkipPrice
+│   ├── FilterBar
+│   ├── Import/ExportToolbar
+│   ├── PaginatedTable
+│   └── DetailDrawer
+└── ProductCategories
+    ├── SearchBar
+    ├── CategoryTreeTable
+    └── EditorDialog
+```
+
+共用 composable：
+
+- 分页和查询参数序列化。
+- 文件导入任务轮询。
+- 下载响应头文件名解析。
+- ASIN/国家/店铺选择器。
+- 删除确认。
+- 空结果和错误提示。
+
+## 类型映射
+
+| 原字段 | 目标类型/规则 |
+|---|---|
+| `page`、`page_size` | `PaginationQuery` |
+| `items`、`total`、`total_pages` | `PaginatedResult<T>` |
+| `import_id` | `ImportJobId`，字符串化处理，禁止丢失大整数精度 |
+| `country`/`country_codes` | 国家代码联合类型；展示名称由共享字典转换 |
+| `file_url`、`download_url` | `DownloadDescriptor`，统一空白值判定 |
+| 抽屉详情字段 | `Record<string, unknown>` 经页面 schema 归一化，不直接在模板遍历原始 JSON |
+
+## 迁移/实现注意事项
+
+1. 不把五个页面继续合成一个巨型组件；每个页面独立管理局部筛选、分页和弹窗。
+2. 导入流程必须保留“上传—解析—确认—入队—轮询—终态”的状态语义，不能只根据 HTTP 200 判断成功。
+3. 导出必须通过统一下载适配器处理文件名、空响应、错误响应和大文件等待。
+4. ASIN 详情抽屉只读展示时要做字段白名单和敏感字段脱敏，不能直接 `JSON.stringify` 全量输出。
+5. 查询条件切换时取消或失效旧请求，避免后返回的旧查询覆盖新结果。
+6. 所有删除操作保留二次确认；后端仍是最终鉴权边界。
+7. 商品类目树的展开状态属于页面局部状态，不放进 Pinia。
+8. 本模块不引入新的后端 v2 API；若 Flask 与 Java 字段存在差异，在 Admin API adapter 中完成归一化。