refactor: 切换蝦皮数据到目录接口 (#135)

docs/admin/02-architecture.md

@@ -90,7 +90,7 @@ admin/
 │   └── api/                给 Client 的接口
 │       └── client_api.go
 ├── service/
-│   ├── shopee_import.go    Excel 解析与 upsert
+│   ├── catalog_import.go   商品目录批次校验、幂等与 upsert
 │   ├── collect.go          创建采集任务
 │   ├── mapping.go          SKU 映射复用
 │   ├── purchase.go         创建采购任务与校验
@@ -217,28 +217,27 @@ func DataDir() (string, error) {
 
 ## 7. 请求流程示例
 
-以"导入蝦皮 Excel"为例，看清各层职责：
+以“第三方脚本导入商品目录”为例，看清各层职责：
 
 ```text
-浏览器 POST /shopee/import （multipart 文件）
+第三方脚本 POST /api/v1/integrations/catalog/batches（JSON）
    ↓
-handler/web/shopee.go
-   - 校验文件大小和扩展名
-   - 存到 data/uploads/
-   - 调 service.ImportShopeeExcel(path)
+handler/integration/catalog_api.go
+   - 独立 Bearer 鉴权
+   - 限制请求体并解析 JSON
+   - 调 service.ImportCatalogBatch(...)
    ↓
-service/shopee_import.go
-   - 用 excelize 逐行读
-   - 按 商品規格ID 是否为 "-" 分成商品行/SKU 行
-   - 解析规格原文 → 颜色/尺码/建议（失败留空）
+service/catalog_import.go
+   - 校验批次、商品、SKU、金额和关联
+   - 开单事务并处理幂等/冲突
    - 调 repository 做 upsert
-   - 返回 {商品数, SKU数, 失败行号列表}
+   - 返回各类新增、更新和关联计数
    ↓
-repository/shopee.go
-   - INSERT ... ON CONFLICT(...) DO UPDATE
-   - 只更新报表来的字段，人工填的 pdd_goods_url 不动
+repository/catalog_import.go
+   - 按来源观测时间更新
+   - 人工 pdd_goods_url / pdd_goods_id 和 is_manual 不动
    ↓
-handler 渲染结果页：导入 5195 商品 / 6092 SKU，失败 0 行
+handler 返回批次 JSON；管理员在统一导入记录页查看摘要
 ```
 
 `[必须]` 注意最后一步：**upsert 时不得覆盖人工维护的字段**。