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

docs/admin/03-data-model.md

@@ -209,79 +209,17 @@ CREATE INDEX idx_shopee_skus_goods ON shopee_skus(goods_id);
 CREATE INDEX idx_shopee_skus_parse ON shopee_skus(parse_ok);
 ```
 
-### 3.3 Excel 导入规则
+### 3.3 商品目录接口导入规则
 
-`[必须]` 这一节的每一条都要照做，写错会丢数据。
+蝦皮页面不再上传或解析固定格式 Excel。第三方脚本负责把不同来源文件归一化，
+再按 [商品目录接口契约](10-商品目录接入接口.md) 提交结构化商品、SKU、PDD 和关联。
 
-**第一步：分行**
-
-| 行类型 | 判断方法 | 样本条数 | 导入到 |
-|---|---|---|---|
-| 商品汇总行 | `商品規格ID` 是 `-` 或空 | 5195 | `shopee_products` |
-| SKU 行 | `商品規格ID` 是数字 | 6092 | `shopee_skus` |
-
-拿参考样本（11287 行）导入应得到 **5195 商品 + 6092 SKU**，数字对不上就是解析有问题。
-
-> 样本文件含商业数据，**不在仓库里**，找项目负责人要，放 `raw_data/` 下。
-> 自动化测试用 `admin/testdata/` 里的小样本，别读大文件。
-
-**第二步：按列名找索引，不要写死列号**
-
-报表有 40 列，蝦皮改一次导出格式列号就变。启动时按表头文字定位：
-
-```go
-idx := map[string]int{}
-for i, name := range header {
-    idx[strings.TrimSpace(name)] = i
-}
-goodsID := row[idx["商品ID"]]
-```
-
-找不到必需列时**直接报错停止**，不要用默认值蒙混过去。
-
-**第三步：解析规格原文**
-
-`商品規格` 这一列格式**不统一**，实测两种各占一半：
-
-| 格式 | 占比 | 样例 |
-|---|---|---|
-| 有【】 | 53.4% | `黑色,M【建議40-50公斤】` |
-| 无括号、空格分隔 | 46.6% | `卡其色拼黑色,L 建議50-57.5kg` |
-
-好消息：**逗号数恒为 1**（6092 条无例外），所以"颜色,尺码"这个二分结构是稳的。
-
-规则：
-
-1. 按第一个逗号切开 → 左边是颜色，右边是"尺码 + 可能的建议"；
-2. 右边尝试提取建议：先找 `【建議...】`，再找 ` 建議...`；
-3. 剩下的就是尺码；
-4. `[必须]` 任何一步失败都**不要猜**，把 `parse_ok` 置 0，颜色尺码留空，
-   `spec_raw` 照常保存。界面上把这些行标出来让人工补。
-
-**第四步：upsert，绝不清空**
-
-```sql
-INSERT INTO shopee_products (goods_id, title, shopee_status, main_sku_code,
-                             created_at, updated_at)
-VALUES (?, ?, ?, ?, ?, ?)
-ON CONFLICT(goods_id) DO UPDATE SET
-    title         = excluded.title,
-    shopee_status = excluded.shopee_status,
-    main_sku_code = excluded.main_sku_code,
-    updated_at    = excluded.updated_at;
-    -- 注意：pdd_goods_url / pdd_data / collect_status 一个都不在这里
-```
-
-| 别这么做 | 后果 |
-|---|---|
-| `DELETE FROM shopee_products` 再导入 | **人工填的 PDD 链接、采集结果全没了** |
-| `DO UPDATE SET` 里写 `pdd_goods_url = excluded.pdd_goods_url` | 报表里没这列，会被更新成空 |
-| 删掉报表里没出现的 SKU | 人工新增的（`is_manual=1`）会被误删 |
-
-**第五步：返回统计**
-
-导入结束返回 `{商品数, SKU数, 解析失败行号列表}`，页面上显示出来。
-**不要静默跳过失败行。**
+- `[必须]` 整批只做 upsert，不清空表，也不删除批次中缺席的数据。
+- `[必须]` `spec_raw` 原样保留；解析失败由上游明确提交 `parse_ok=false`，Admin 不猜。
+- `[必须]` 商品更新不覆盖 `pdd_goods_url` / `pdd_goods_id`，SKU 更新不覆盖 `is_manual`。
+- `[必须]` 较旧 `observed_at` 不覆盖较新接口数据。
+- 空 PDD 关联可以建立；相同关联幂等；不同关联返回冲突，不静默换品。
+- 一个批次在单事务中写入并返回新增、更新、未变化和失败统计。
 
 ## 4. `pdd_products` 拼多多商品