feat: 建立商品目录接入基础 (#132)

docs/admin/03-data-model.md

@@ -142,6 +142,11 @@ MySQL 迁移 v6（工单 #127）为 `tasks` 追加可空的 `created_by_user_id`
 索引。存量记录不回填，NULL 明确表示“历史任务”；新建采集和采购任务必须写当前
 网页登录用户。迁移与自检可重放，历史 SQLite migrations 保持冻结。
 
+MySQL 迁移 v7（工单 #132）新增 `catalog_import_runs` 批次摘要表，并为蝦皮商品、
+蝦皮 SKU 和 PDD 商品补充来源观测时间。`shopee_products.source` 新增 `api` 取值，
+`pdd_products` 新增可空来源字段。迁移不改写既有业务数据，每条 DDL 可重放，所有
+字段和约束自检通过后才记录 v7。
+
 ## 3. 蝦皮数据
 
 蝦皮报表**一个文件里混了两层数据**，所以拆成两张表。
@@ -154,7 +159,8 @@ CREATE TABLE shopee_products (
     title           TEXT NOT NULL,             -- 蝦皮「商品名稱」
     shopee_status   TEXT,                      -- 蝦皮「商品當前狀態」
     main_sku_code   TEXT,                      -- 蝦皮「主商品貨號」
-    source          VARCHAR(16) COLLATE utf8mb4_bin NOT NULL DEFAULT 'report', -- report / syb
+    source          VARCHAR(16) COLLATE utf8mb4_bin NOT NULL DEFAULT 'report', -- report / syb / api
+    source_observed_at VARCHAR(35),              -- 外部来源观测时间，UTC ISO 8601
 
     -- 下面两个是我们自己维护的，报表里没有，导入时绝不能覆盖
     pdd_goods_url   TEXT,                      -- ★ 人工填写的 PDD 链接原文
@@ -165,14 +171,15 @@ CREATE TABLE shopee_products (
 );
 
 ALTER TABLE shopee_products ADD CONSTRAINT chk_shopee_products_source
-    CHECK (source IN ('report', 'syb'));
+    CHECK (source IN ('report', 'syb', 'api'));
 
 CREATE INDEX idx_shopee_products_pdd ON shopee_products(pdd_goods_id);
 ```
 
 `[必须]` **采集结果和采集状态不在这张表里**，它们属于 PDD 商品，见 §4。
 
-`source='syb'` 表示顺运宝先到、蝦皮报表尚未导入时创建的最小商品骨架。
+`source='syb'` 表示顺运宝先到、蝦皮报表尚未导入时创建的最小商品骨架；
+`source='api'` 表示由商品目录批量接口写入。
 后续 Excel 导入同一 `goods_id` 时必须补全商品信息并把来源提升为 `report`；
 导入不得覆盖人工维护的 PDD 关联。
 
@@ -192,6 +199,7 @@ CREATE TABLE shopee_skus (
     parse_ok      INTEGER NOT NULL DEFAULT 0,  -- 0=解析失败，界面上要标出来
     sku_code      TEXT,                        -- 蝦皮「商品選項貨號」
     is_manual     INTEGER NOT NULL DEFAULT 0,  -- 1=人工新增的，导入不得删
+    source_observed_at VARCHAR(35),            -- 外部来源观测时间，UTC ISO 8601
     created_at    TEXT NOT NULL,
     updated_at    TEXT NOT NULL,
     FOREIGN KEY (goods_id) REFERENCES shopee_products(goods_id) ON DELETE CASCADE
@@ -875,3 +883,13 @@ CREATE UNIQUE INDEX idx_client_assignment_current
 - `client_id` 故意不设指向 `clients` 的外键：客户端清单允许删除后由同一稳定编号
   重新登记，归属和审计历史不能随临时清单记录丢失。
 - 归属记录不参与 Client API 的登记和领取判断，也不更新 `tasks.assigned_client`。
+
+## 14. `catalog_import_runs` 商品目录批次摘要（MySQL v7）
+
+`catalog_import_runs` 以 `(source, batch_id)` 为主键，保存请求哈希、处理状态、
+新增/更新/冲突计数和错误摘要。它不保存 Bearer Token，也不保存完整请求体。
+
+- 相同来源、批次号和请求哈希只处理一次；重复提交返回首次结果。
+- 相同来源和批次号携带不同请求哈希时记录冲突并返回 HTTP 409。
+- `response_body` 只保存可安全重放的结果摘要，不得包含凭据或原始商品数据。
+- `source_observed_at` 用于拒绝较旧数据覆盖较新数据；缺席记录绝不代表删除。