feat: 支持人工修改蝦皮规格 (#215)

2026-08-13 12:14:02 +08:00
parent 5b7d92289e
commit 4752fef54f
16 changed files with 403 additions and 34 deletions
@@ -88,8 +88,8 @@ PDD 商品之所以单独一个模块，是因为它在数据上就是**独立
 ### 4.1 蝦皮数据模块

 **顶部工具条：** 导入记录按钮、批量创建 PDD 采集任务按钮、状态筛选
-（全部 / 待补规格 / 未填 PDD 链接 / 已填链接）、店铺与图片筛选、商品 ID 和店铺名称
-搜索、搜索按钮；管理员另有正常/已删除范围筛选以及删除/恢复按钮。
+（全部 / 待补规格 / 未填 PDD 链接 / 已填链接）、分类（商品 ID / 商品名称 / 店铺名）、
+关键词和搜索按钮；管理员另有回收站入口以及删除/恢复按钮。

 `[必须]` 状态筛选是**刚需**，不是锦上添花（工单 #43）：本页的主要用途是维护
 （找出需要补规格的商品、找出还没关联 PDD 链接的商品），只靠商品 ID 搜索的话，
@@ -97,21 +97,23 @@ PDD 商品之所以单独一个模块，是因为它在数据上就是**独立
 实测样本 5195 个商品里只有 6 个待补规格，只做分页要翻 260 页才能找全，等于找不到。
 界面细节和筛选条件的 SQL 见 [05 界面规范](05-ui-specification.md) §4.1。

-**中间表格**（按 SKU 展开显示，数据来自商品表和 SKU 表联查）：
+**中间表格**（一个商品一行，SKU 数据聚合显示）：

 | 列 | 说明 |
 |---|---|
 | 勾选 | 支持批量删除、批量创建 PDD 采集任务 |
 | 商品 ID | 蝦皮商品编号 |
 | 商品名称 | |
-| 颜色 / 尺码 / 建议 | 从规格原文解析，解析不出来留空并标记 |
-| PDD 链接 | 人工填写，空的要显眼 |
+| 颜色 / 尺码 / SKU / 待补 | 聚合计数，待补大于 0 时整行提示 |
+| PDD 商品 ID | 已关联时显示商品 ID，完整链接放在悬停提示和详情；空的要显眼 |
 | 采集状态 | 见 §6 |
 | 更新时间 | |

 **双击行打开编辑弹窗**，这是**从蝦皮商品出发**填 PDD 链接、发起采集的入口：

- 可编辑当前 PDD 商品链接；规格表继续只读展示；
+- 可编辑当前 PDD 商品链接；规格表摘要只读，每条现有 SKU 可展开修改颜色、尺码和建议说明；
+- 人工修改只写字段级来源，不修改规格原文、规格键、真实 SKU ID 或 `is_manual`；后续
+  目录导入和 SYB 低优先级补全不得覆盖人工字段，主动清空的建议说明也按人工值保护；
 - 保存链接时从完整链接解析 `goods_id`，在同一事务内复用或复活 PDD 商品档案并更新当前关联；
 - 更换成不同 `goods_id` 时必须明确勾选确认，旧规格映射保留但不会被当前关联查询误用；
 - 弹窗内提供【创建采集任务】按钮，复用 PDD 商品模块的幂等与超时重试规则；
@@ -470,7 +470,9 @@ MySQL schema v8 将 `shopee_skus.sku_id` 保留为系统内部记录主键（兼
 `source_observed_at` 用于限制同来源更新，`is_manual=1` 始终优先保护。
 `field_sources` 与 `field_observed_at` 是只含颜色、尺码、建议和 SKU 编码的 JSON
 来源表；`fill_missing` 补字段时分别登记，`overwrite_same_source` 只更新来源属于本次
-调用方且观测时间不旧的字段，避免不同脚本各补一部分后互相覆盖。
+调用方且观测时间不旧的字段，避免不同脚本各补一部分后互相覆盖。详情页人工修改
+颜色、尺码和建议时，把对应字段来源写为 `manual`；即使人工主动清空建议，补空策略
+也不得重新填入。人工编辑现有行不把 `is_manual` 改成 1，后者只表示人工新增整条 SKU。

 MySQL schema v9 为 `shopee_products` 增加 `image_url` 和 `shopee_shop_name`。两者分别
 使用 `image_source/image_observed_at/image_is_manual` 与
@@ -182,7 +182,7 @@
 | 商品名称 | 固定约 120px，截断 + 悬停完整 |
 | 店铺 | 导入或同步得到的蝦皮店铺名称；为空显示 `—` |
 | 数据来源 | 蝦皮报表 / 顺运宝补建；不只靠颜色区分 |
-| 颜色 / 尺码 / 建议 | 解析失败的显示为 `—` 并**整行标黄**，提示需人工补 |
+| 颜色 / 尺码 / SKU / 待补 | 商品级聚合计数；待补大于 0 时**整行标黄** |
 | PDD 商品 ID | 正文显示 goods_id，悬停显示完整 URL；空的显示"**未填写**"并标红 |
 | 采集状态 | 未填链接 / 未采集 / 采集中 / 已采集 / 采集失败。**数据来自两张表**，判断方式见 [01 需求](01-requirements.md) §6.1 |
 | 更新时间 | 本地时区 |
@@ -201,11 +201,8 @@
 │ 编辑商品 40653075144                    │
 ├─────────────────────────────────────────┤
 │ 商品名称  【台灣現貨隔日達】西裝外套…   │  ← 只读
-│ 规格原文  黑色,M【建議40-50公斤】       │  ← 只读，永远显示
-│                                         │
-│ 颜色      [黑色___________]             │
-│ 尺码      [M_______________]            │
-│ 建议      [40-50公斤_______]            │
+│ 规格表：原文 / 颜色 / 尺码 / 建议 / 状态 │  ← 摘要只读
+│   [编辑] → 颜色、尺码、建议的行内折叠表单 │
 │                                         │
 │ PDD 链接  [___________________________]  │  ← ★
 │ 采集状态  已采集（2026-08-06 15:20）    │
@@ -218,6 +215,11 @@

 - **创建采集任务只在这个弹窗里出现**，不要放到表格每一行或工具条，确保操作员看得到当前关联商品。
 - **规格原文只读且永远显示**。操作员靠它判断颜色尺码该怎么填。
+- 只允许编辑已有 SKU 的颜色、尺码和建议说明；颜色、尺码必填，建议可清空。真实
+  Shopee SKU ID、内部记录 ID、规格键和原文不可编辑，也不在页面冒充彼此。
+- 保存后颜色、尺码和建议写入字段级 `manual` 来源并标记为已解析；目录接口的补空和
+  同来源覆盖均不得覆盖这些字段。主动清空建议同样是明确的人工值。
+- 本功能不新增或删除 SKU，不修改顺运宝原始规格、既有规格映射或采购任务。
 - 保存链接时展示当前解析出的 PDD 商品 ID；新链接指向其他商品时必须勾选明确确认。
 - 无法解析 `goods_id` 的链接整体不写入；同一商品复用档案，软删除档案可复活。
 - PDD 链接为空时**采集按钮置灰**，旁边提示"请先填写 PDD 链接"。
@@ -21,7 +21,8 @@
 `[必须]` 覆盖：

 - **商品目录批次**：鉴权、原子写入、幂等重放、关联冲突和旧观测时间保护；
- **upsert 不覆盖人工字段**：先填 PDD 链接，再通过目录接口导入，断言链接还在；
+- **upsert 不覆盖人工字段**：先填 PDD 链接和人工修改 SKU 颜色/尺码/建议，再分别用
+  `fill_missing`、`overwrite_same_source` 导入，断言链接和人工字段（含清空建议）仍在；
 - **PDD 链接批量导入**：空工作表、正确/错误表头、两个允许域名、短链/非 PDD
  链接、空行、5000 条边界、文件内重复、新建/复用/复活分类和重复导入不覆盖采集结果；
 - 任务创建校验：商品、采集结果、有效映射、数量、人民币价格上限、客户端可见范围逐条覆盖；