feat: 展示蝦皮主图和店铺 (#142)

docs/admin/10-商品目录接入接口.md

@@ -21,7 +21,7 @@ Token 通过 `CMAUTOBUY_CATALOG_TOKEN` 或未提交的 `config.yaml` 配置。
   "observed_at": "2026-08-11T10:00:00+08:00",
   "update_policy": "fill_missing",
   "shopee_products": [
-    {"goods_id": "S-1", "title": "蝦皮上衣", "status": "NORMAL", "main_sku_code": "A01"}
+    {"goods_id": "S-1", "title": "蝦皮上衣", "status": "NORMAL", "main_sku_code": "A01", "image_url": "https://img.example.com/S-1.jpg", "shop_name": "蝦皮示例店铺"}
   ],
   "shopee_skus": [
     {"sku_id": null, "goods_id": "S-1", "spec_raw": "黑色,M", "color": "黑色", "size": "M", "parse_ok": true, "sku_code": "A01-B-M"}
@@ -47,6 +47,10 @@ Token 通过 `CMAUTOBUY_CATALOG_TOKEN` 或未提交的 `config.yaml` 配置。
 不得自行生成。系统用内部主键和 `goods_id + spec_key` 保持记录身份，后续取得真实 ID
 会补到原记录，不会重复新增。
 
+`image_url` 和 `shop_name` 可选。图片只接受不含用户信息和明显凭据参数的完整
+HTTP/HTTPS URL，最长 2048 字节；店铺名最长 500 个字符。Admin 只保存地址并由浏览器
+懒加载，不会在服务端下载或代理图片。
+
 ## 3. 写入与幂等规则
 
 - 整个批次在一个事务中写入：实体、SKU、关联任一步失败就全部回滚。
@@ -57,6 +61,8 @@ Token 通过 `CMAUTOBUY_CATALOG_TOKEN` 或未提交的 `config.yaml` 配置。
   - `overwrite_same_source`：只有来源相同且 `observed_at` 更新时才覆盖来源字段。
 - 较旧的 `observed_at` 不覆盖较新的接口数据，任何策略都不能覆盖 `is_manual=1`。
 - `spec_raw` 和由它生成的规格身份不被更新；同商品同规格出现不同真实 SKU ID 返回 409。
+- 蝦皮主图和店铺名也遵循本批次策略，但各自独立记录来源、观测时间和人工保护；
+  空值永不清除现有值。顺运宝观测图片不参与蝦皮主图更新。
 - 蝦皮 upsert 不覆盖采购员维护的 PDD 链接；SKU 的 `is_manual` 不被接口改写。
 - 空关联可以建立、相同关联不重复写；已有不同 PDD 关联返回 409，绝不静默替换。
 - 批次缺少某条记录不表示删除，接口没有“全量覆盖”语义。
@@ -83,7 +89,7 @@ Token 通过 `CMAUTOBUY_CATALOG_TOKEN` 或未提交的 `config.yaml` 配置。
 
 ## 5. schema v8 发布与回退
 
-发布前先备份生产库，并在 MySQL 8.4、库名以 `_test` 结尾的测试库演练 v7→v8。
+发布前先备份生产库，并在 MySQL 8.4、库名以 `_test` 结尾的测试库演练 v7→v8→v9。
 迁移只增加列和唯一索引，既有 `sku_id` 继续作为内部主键，因此历史引用不变；若检测
 到同商品重复 `spec_key`，迁移会停止且不记录 v8，必须人工确认，不能自动合并。