feat: PDD 商品页面 (#18)

打通 Client↔Admin 闭环的一环：录入 PDD 链接 → 创建采集任务 → 客户端领走去采 → 规格和价格显示在页面上。#16 写的 MarkCollecting 和 SoftDeletePddProduct 至此才有生产调用方。链接解析严格、不做容错兜底：goods_id 上有 UNIQUE 约束，防重全靠它。猜一个的话同一商品会存成好几行、采好几遍，规格映射还说不清指向哪一行。短链一律拒绝，卡域名是为了拦"粘了淘宝链接"这种失误。创建采集任务先占状态再建任务：MarkCollecting 只在 pending/failed 时成功，同时充当"有没有人已经在采"的判断，与建任务在同一事务里，所以并发点多次只会建出一个任务（实测 4 并发 → 1 条）。 submit.go 的 collectedData 增加 Dimensions —— 没有它就只能按 Go 的 map 遍历，而 map 无序，同一商品每次刷新"颜色/尺码"的先后都可能变。顺带修 #16 一处缺陷：EnsurePddProduct 复活分支清空了 skus_json 却漏了 title，导致复活后状态显示"未采集"但标题还留着旧值。审查打回一次：清理"PDD 链接唯一的录入口"这一过期说法（全库 5 处），以及 shopee.go 里"空 → no_link"的过期 TODO —— no_link 已在 #16 从 CHECK 约束删除，照写会直接撞约束。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-07 11:27:06 +08:00
parent fab20cfd2f
commit eb8d357f5a
16 changed files with 2333 additions and 72 deletions
@@ -8,18 +8,18 @@

 ## 1. 设计目标

- 四个模块**长得一样**，写完第一个，其余三个照抄结构改字段；
+- 五个模块**长得一样**，写完第一个，其余四个照抄结构改字段；
 - 操作员一眼看出"这条数据卡在哪一步、下一步该点什么"；
 - 不引入前端框架和构建流程；
 - 破坏性操作（删除、导入）必须有确认，不能手滑。

 ## 2. 统一的三段式布局

-`[必须]` 四个模块全部用这个结构，**不要给某个模块搞特殊**：
+`[必须]` 五个模块全部用这个结构，**不要给某个模块搞特殊**：

 ```text
 ┌────────────────────────────────────────────────────────────┐
-│ [导航] 蝦皮数据 │ 顺运宝数据 │ 采购任务 │ 客户端列表        │
+│ [导航] 蝦皮数据 │ PDD 商品 │ 顺运宝数据 │ 采购任务 │ 客户端 │
 ├────────────────────────────────────────────────────────────┤
 │ 顶部工具条：[操作按钮…] [搜索框] [搜索] [删除]              │
 ├────────────────────────────────────────────────────────────┤
@@ -33,7 +33,7 @@
 ```

 `[必须]` 三段做成 `templates/partials/` 里的公共片段复用，
-**不要每个页面复制一份**——改一次样式要改四处，必然改漏。
+**不要每个页面复制一份**——改一次样式要改五处，必然改漏。

 `[必须]` 页面在 1366×768 上可用。列多了让表格**横向滚动**，不要压缩列宽把字挤成两行。

@@ -42,7 +42,9 @@
 - `[必须]` 第一列是勾选框，表头有全选。
 - `[必须]` 行的身份用**业务主键**（商品規格ID、货运单ID、任务编号、序列号），
  **不得用行号**——排序和筛选一变行号就错位。
- `[必须]` 批量删除要二次确认，弹窗里写清"**将删除 N 条，不可恢复**"。
+- `[必须]` 批量删除要二次确认，弹窗里写清**删几条、能不能恢复**。
+  硬删写"将删除 N 条，不可恢复"；软删除的（如 PDD 商品）要说明恢复方式和会丢什么，
+  见 §5.6。含糊其辞和吓唬人一样糟——两种都会让操作员不敢动手。
 - `[必须]` 删除、导入用 **POST**，不得用 GET。浏览器和插件会预取 GET 链接。
 - `[建议]` 默认按 `更新时间 DESC` 排序。
 - `[建议]` 一页 50 条，超过分页。搜索走数据库，不要一次查出来在内存里过滤。
@@ -81,7 +83,12 @@

 ### 4.3 编辑弹窗（双击行打开）

-这是 **PDD 链接唯一的录入口**，也是采集的唯一发起点。
+这是**从蝦皮商品出发**填 PDD 链接、发起采集的入口。
+
+> `[注意]` PDD 商品页（[§5](#5-pdd-商品页)）也能录入链接和发起采集，
+> 两处并存。本页的入口目前**还是骨架**（点了返回 501），
+> 两者要不要合并、以哪个为准，属于「蝦皮↔PDD 关联入口」的范围，
+> 由那张工单统一决定，不要在本页单独改。

 ```text
 ┌─────────────────────────────────────────┐
@@ -103,7 +110,7 @@

 `[必须]` 几条硬规则：

- **采集按钮只在这里出现**，不要放到表格每一行。一个商品有 N 个 SKU 行，
+- **本页的采集按钮只在这个弹窗里出现**，不要放到表格每一行。一个商品有 N 个 SKU 行，
  放行上就是 N 个按钮干同一件事，还会建出 N 个重复任务。
 - **规格原文只读且永远显示**。操作员靠它判断颜色尺码该怎么填。
 - PDD 链接为空时**采集按钮置灰**，旁边提示"请先填写 PDD 链接"。
@@ -119,17 +126,169 @@

 新增的行 `is_manual = 1`，`[必须]` 后续导入**不得删除**它们。

-## 5. 顺运宝数据页
+## 5. PDD 商品页
+
+页面 `objectName` 为 `pddProductPage`，路由 `/pdd`。
+
+这个页面**不依赖蝦皮和顺运宝的任何数据**，可以单独跑通整条闭环：
+建商品 → 建采集任务 → Client 领走执行 → 提交结果 → 刷新看到"已采集"和规格数。

 ### 5.1 工具条

+```text
+[创建] [创建采集任务]  采集状态[全部▾] 商品ID/链接[______] [搜索]  [删除]
+```
+
+- **创建** → 弹窗，只填 PDD 链接。
+- **创建采集任务** → 勾选多行后可用。
+- **采集状态筛选** → 全部 / 未采集 / 采集中 / 已采集 / 采集失败。
+  `[必须]` 这个筛选是**刚需**，不是锦上添花：这个页面的主要用途是维护
+  （找出失败的重采、找出还没采的），只按 ID 搜的话要翻页去找。
+- **删除** → 勾选多行后可用。
+
+`[必须]` 「创建采集任务」和「删除」共用**同一个表单**（靠按钮上的 `formaction`
+决定提交到哪个地址），表格里的勾选框只挂一份。
+为每个操作各复制一套勾选框的话，两套迟早会不同步。
+
+### 5.2 表格列
+
+| 列 | 显示规则 |
+|---|---|
+| 勾选 | 值是 `goods_id`，支持批量删除、批量建采集任务 |
+| 商品 ID | `goods_id` |
+| 标题 | 采集回来的；未采集时显示"（未采集，采集后自动回填）" |
+| PDD 链接 | 截断显示，可点开（`target="_blank"` 要带 `rel="noopener noreferrer"`） |
+| 采集状态 | 中文文字，**不能只靠颜色**；失败时在下面补一行原因 |
+| 规格数 | 从 `skus_json` 算 |
+| 采集时间 | 本地时区；未采集显示 `—` |
+| 更新时间 | 本地时区 |
+
+`[必须]` **规格数这一列不能省。** 采到 1 个和采到 20 个差别很大——
+只采到 1 个通常意味着客户端没点开规格面板，是采集有问题。
+
+`[必须]` **未采集显示 `—`，采到 0 个要如实显示 `0`。** 这两种是不同的情况：
+前者是还没采，后者是采集出了问题（商品下架、页面改版、解析器没认出来），
+都显示成 `—` 就看不出区别了。
+
+`[建议]` 规格数用 SQLite 的 `json_array_length(skus_json, '$.skus')` 直接算，
+不要把整个 JSON 读进 Go 再数。`[必须]` 外面要包一层 `json_valid`——
+`skus_json` 万一存进了坏数据，`json_array_length` 会让**整条查询报错**，页面直接打不开。
+
+`[必须]` 空状态分两种文案：从没创建过 → 引导去点「创建」；筛选无结果 → 给"查看全部"的入口。
+
+### 5.3 创建弹窗
+
+`[必须]` **只填 PDD 链接**，其余字段全靠采集回填。
+
+`[必须]` **链接必须能解析出 `goods_id`，解析不出来直接报错并且不写库。**
+不接受短链接（`p.pinduoduo.com/xxxx`）——`goods_id` 上有 UNIQUE 约束，
+防重全靠它，拿不到就没法查重，同一个商品会存成好几行。
+
+`[必须]` 报错要说清**下一步怎么办**，例如"请在拼多多 App 的商品页点
+「分享」→「复制链接」，拿到带 `goods_id=` 的完整链接"。光说"链接无效"操作员不知道改什么。
+
+### 5.4 编辑弹窗（双击行打开）
+
+```text
+┌─────────────────────────────────────────────┐
+│ PDD 商品 737116531267                       │
+├─────────────────────────────────────────────┤
+│ 商品 ID    737116531267          （只读）    │
+│ PDD 链接   [___________________]（可编辑）   │
+│ 标题       西装外套三件套        （只读）    │
+│ 采集状态   已采集                            │
+│ 失败原因   —                                 │
+│ 采集时间   2026-08-07 15:20                  │
+├─────────────────────────────────────────────┤
+│ 规格（3 个）                                 │
+│ 颜色分类  尺码   价格      有货              │
+│ 黑色      M     ¥12.56     是                │
+│ 白色      M     ¥12.56     否                │
+│ 红色      L     未采到     是                │
+├─────────────────────────────────────────────┤
+│ [重新采集]              [取消] [保存]        │
+└─────────────────────────────────────────────┘
+```
+
+`[必须]` **规格和价格必须显示。** 这是采集结果的全部价值所在——
+不显示的话操作员没法确认"采得对不对、是不是我要的那个商品"。
+
+`[必须]` 维度列的顺序按 `skus_json` 里的 `dimensions` 排，表头用 `name`。
+Go 的 map 是无序的，不靠它定顺序的话，同一个商品每次刷新页面列的先后都可能变。
+
+`[必须]` 价格显示成 `¥12.56`，底层存的是**整数分**。
+`price_cent` 为 `null` 时显示"未采到"，**不得显示成 ¥0.00**——
+0 元和采不到价格是两回事，而这个数要参与价格保护比对（会花钱）。
+
+`[必须]` 三种"没有规格"要分开显示，处理方式不一样：
+
+| 情况 | 显示 |
+|---|---|
+| 还没采过 | "尚未采集"，并说明怎么发起采集 |
+| 采完了但一个规格都没有 | 提示可能已下架或没点开规格面板，建议重采 |
+| `skus_json` 解析不了 | 明说数据坏了需要重新采集，**不要装作"没有规格"** |
+
+`[必须]` 编辑链接时，新链接必须还是**同一个商品**，否则拒绝并提示改用「创建」。
+这一行上挂着采集结果和 SKU 映射，`goods_id` 一换那些数据就全指到错的商品上了，
+之后按它下单就是买错东西。
+
+`[必须]` 弹窗内容由**服务端渲染**（`GET /pdd/detail?id=…` 返回 HTML 片段），
+前端只负责取回来、放进壳子、显示隐藏。维度顺序、价格格式、`null` 的处理都是业务规则，
+散到前端就没人维护得住了。
+
+### 5.5 创建采集任务
+
+`[必须]` **不指定客户端**（`assigned_client` 为 `NULL`，`status` 为 `pending`），
+谁领到就在领取时标记谁。采集是纯读取操作，哪台机器跑都一样，
+指定了反而会在那台机器关着的时候干等。
+
+- 勾选多行 → 按 `goods_id` 去重 → 建任务；
+- `collect_status` 已是 `collecting` 的**跳过**；
+- 建成功后把状态置为 `collecting`；
+- 任务的 `pdd_goods_url` 和 `pdd_goods_id` 必须填（Client 契约要求 `goods_url` 必填）。
+
+`[必须]` 按钮文案用「**创建采集任务**」，不要用「采集」。它做的是建一个任务，
+不是立刻去采——真正的采集要等 Client 来领、去手机上跑，可能几秒也可能几分钟。
+点完页面上只有状态从"未采集"变成"采集中"，文案不说清楚操作员会以为没生效。
+
+`[必须]` 结果在状态条明确提示，**跳过了几个也要说**：
+
+```text
+已创建 3 个采集任务，等待客户端领取（跳过 1 个采集中或已删除的）
+```
+
+静默跳过的话，操作员会以为任务都建上了，等半天没动静也不知道为什么。
+
+### 5.6 删除
+
+软删除。`[必须]` 二次确认要写明能不能恢复、恢复后会丢什么：
+
+> 将删除 3 条记录。删除后重新创建同一链接可恢复，**但采集结果会清空**。
+
+（复活时清空旧采集结果是既定行为——记录被删过一次，旧数据不该再当有效的用。）
+
+### 5.7 底部状态条
+
+```text
+共 24 条 · 已采集 18 · 未采集 4 · 采集中 1 · 采集失败 1
+```
+
+`[必须]` 统计的是**全部未删除记录**，不随筛选变化——状态条是全局概览。
+有筛选时在前面加一句 `筛选出 N 条 /`，免得操作员把筛选后的行数当成全部行数，以为记录被删了。
+
+刚做完写操作时，状态条**先显示操作结果**，再接统计。
+
+## 6. 顺运宝数据页
+
+### 6.1 工具条
+
 ```text
 [同步] [创建采购任务]   订单号 [________] [搜索]   [删除]
 ```

 `[待定]` MVP 阶段**同步按钮只做占位**：点击提示"同步功能待接入"，不发请求。

-### 5.2 表格列
+### 6.2 表格列

 ☐ / 货运单ID / 订单号 / 商品标题 / 蝦皮商品ID / 规格SKU / 数量 /
 价格（台币）/ 图片 / **匹配状态** / 更新时间
@@ -138,7 +297,7 @@
 - 匹配状态是**算出来的**（`sku_mappings` 里有没有记录），不是存的字段。
 - 完整货运单 JSON 不作为列显示，在详情里看。

-### 5.3 规格匹配弹窗（双击行打开）
+### 6.3 规格匹配弹窗（双击行打开）

 ```text
 ┌──────────────────────────────────────────────────┐
@@ -167,7 +326,7 @@
  并给一个跳转链接。
 - 保存写的是 `sku_mappings`（可复用），**不是这一张订单的临时数据**。

-### 5.4 创建采购任务
+### 6.4 创建采购任务

 勾选若干行 → 点按钮 → 逐条校验（见 [01 需求](01-requirements.md) §5）。

@@ -182,7 +341,7 @@
 `[必须]` 创建前弹出确认框，让操作员选**分配给哪个客户端**，并确认价格上限。
 价格上限默认从 `pdd_data` 带出，可改，**不允许为空**。

-## 6. 采购任务页
+## 7. 采购任务页

 工具条：`订单号 [____] [搜索]  [删除]`

@@ -197,7 +356,7 @@

 底部状态条显示各状态的条数统计。

-## 7. 客户端列表页
+## 8. 客户端列表页

 工具条：`名称 [____] [搜索]  [删除]`

@@ -210,7 +369,7 @@
 - `[建议]` 界面上说明一句："客户端执行长任务期间可能显示为离线，属正常现象。"
  因为没有心跳，这是已知且接受的取舍（见 [04](04-client-api.md) §3）。

-## 8. 反馈方式
+## 9. 反馈方式

 | 场景 | 怎么反馈 |
 |---|---|
@@ -224,7 +383,7 @@
 `[必须]` 报错要说清**哪一步失败、下一步做什么**，不要把 Go 的错误堆栈贴到页面上。
 堆栈写日志。

-## 9. 可访问性与细节
+## 10. 可访问性与细节

 - `[必须]` 表单控件有可见 `<label>`，占位符不能当标签用。
 - `[必须]` 状态不能只靠颜色，必须有文字。