# 05 Admin 界面规范 - 文档状态：基线草案，待界面评审 - 技术栈：Go `html/template` 服务端渲染 + 手写 CSS + 原生 JS / htmx 本文档中 `[必须]` / `[建议]` / `[待定]` 的含义见 [文档索引](../README.md#文档标注说明)。 没有标注的默认是 `[必须]`。看不懂的词查 [术语表](00-glossary.md)。 ## 1. 设计目标 - 五个模块**长得一样**，写完第一个，其余四个照抄结构改字段； - 操作员一眼看出"这条数据卡在哪一步、下一步该点什么"； - 不引入前端框架和构建流程； - 破坏性操作（删除、导入）必须有确认，不能手滑。 ## 2. 统一的三段式布局 `[必须]` 五个模块全部用这个结构，**不要给某个模块搞特殊**： ```text ┌────────────────────────────────────────────────────────────┐ │ [导航] 蝦皮数据 │ PDD 商品 │ 顺运宝数据 │ 采集采购 │ 客户端 │ ├────────────────────────────────────────────────────────────┤ │ 顶部工具条：[操作按钮…] [搜索框] [搜索] [删除] │ ├────────────────────────────────────────────────────────────┤ │ ☐ │ 列1 │ 列2 │ 列3 │ … │ │ ☐ │ │ │ │ │ │ 数据表格（占满剩余高度） │ │ │ ├────────────────────────────────────────────────────────────┤ │ 底部状态条：最近一次操作的结果和关键统计 │ └────────────────────────────────────────────────────────────┘ ``` `[必须]` 三段做成 `templates/partials/` 里的公共片段复用， **不要每个页面复制一份**——改一次样式要改五处，必然改漏。 `[必须]` 页面在 1366×768 上可用。列多了让表格**横向滚动**，不要压缩列宽把字挤成两行。 ## 3. 表格通用规则 - `[必须]` 第一列是勾选框，表头有全选。 - `[必须]` 行的身份用**业务主键**（商品規格ID、货运单ID、任务编号、序列号）， **不得用行号**——排序和筛选一变行号就错位。 - `[必须]` 批量删除要二次确认，弹窗里写清**删几条、能不能恢复**。 硬删写"将删除 N 条，不可恢复"；软删除的（如 PDD 商品）要说明恢复方式和会丢什么， 见 §5.6。含糊其辞和吓唬人一样糟——两种都会让操作员不敢动手。 - `[必须]` 删除、导入用 **POST**，不得用 GET。浏览器和插件会预取 GET 链接。 - `[建议]` 默认按 `更新时间 DESC` 排序。 - `[必须]` 每页 **20** 条，超过分页，见 §3.2。搜索走数据库，不要一次查出来在内存里过滤。 - `[必须]` 长文本（商品标题）截断显示，鼠标悬停给完整内容。 - `[必须]` 空状态要分情况，文案不能都是"暂无数据"： - 从没导入过 → "还没有数据，点左上角『导入』开始" - 搜索无结果 → "没有匹配的记录" + 清除条件入口 ### 3.1 搜索框宽度 `[必须]` 搜索框加 `class="search-narrow"` 收到 30%，让「搜索」按钮紧挨着它。 目前 **PDD 商品页、顺运宝数据页、采集采购页**在用； 蝦皮数据页和客户端列表页仍是撑满的（暂未统一）。 `[必须]` **不要去改 `.toolbar input[type="text"]` 那条通用规则**—— 五个页面共用它，改了会把没打算改的页面一起改掉。 `[必须]` 搜索表单上的 `grow` 类**要保留**，它负责把「删除」按钮顶到最右侧。 去掉的话删除按钮会跑到搜索按钮旁边。 `[必须]` **不要额外加对齐样式**（`margin-right: auto`、`justify-content` 之类）。 输入框不再伸展之后，多余空间自然留在按钮之后，按钮就贴着输入框了； 额外加会和 `grow` 叠加出难预料的结果。 `[建议]` placeholder 要短。收到 30% 之后长文案显示不全—— 真装不下就缩短文案，**不要把宽度调回去**。 ### 3.2 分页 `[必须]` 五个模块**统一每页 20 条**（原来这里写的是"建议一页 50 条"， 已按工单 #43 改为 20 并升级为 `[必须]`）——20 行在 1366×768 上正好一屏， 不用滚动就能看完；50 条要滚动，操作员容易漏看最下面几行。 蝦皮数据页（§4）是全项目第一个做分页的页面，本节是它定下的通用规则， **其余四个页面照抄**，不要各写一套： - `[必须]` 分页用 SQL 的 `LIMIT ? OFFSET ?`，**不得**把全量查出来在 Go 里 切片——这正是蝦皮数据页改之前一次吐 3.4MB HTML 的成因（实测 5195 行）。 - `[必须]` 总数用**单独的 `COUNT(*)`** 查询，并且和列表查询**共用同一套 筛选条件拼装函数**。分开写两份 `WHERE` 迟早会漏改一处，页码跟着算错， 而且不会报错、不容易发现（#19 已经踩过一次）。 - `[必须]` 页码参数是 `?page=N`，从 **1** 开始，不是 0——给操作员看的东西 不要 0-based。 - `[必须]` 越界要兜住： - `page` 非数字、`0`、负数 → 当作第 1 页； - `page` 超过总页数 → 显示**最后一页**（有数据的那页），不是空表格； - 总数为 0 → 显示"第 1/1 页"，不出现"第 1/0 页"。 - `[必须]` 底部状态条显示**全量总数**（当前筛选条件下的总数），不是本页 行数——"共 20 个商品"会让操作员以为总共就 20 个。筛选后显示筛选结果的 总数，例如"待补规格：6 个商品 · 第 1/1 页"，不是本页凑出来的数字。 - `[必须]` 翻页时**保留当前筛选和关键词**——用查询参数原样带过去， 丢了的话操作员翻到第二页筛选就没了，会以为数据变了。 - `[必须]` 分页控件用 ``，**不要用 JS**。这是纯 GET 导航， 浏览器的前进后退和书签都该正常工作。 - `[必须]` 第一页时"首页 / 上一页"禁用，最后一页时"下一页 / 末页"禁用； 禁用要有**视觉 + 语义**区分（不可点的元素不要还是 ``），不能只靠颜色。 - `[建议]` 不做 `1 2 3 … N` 这种页码列表。页数一多列出来没有意义， 操作员应该靠筛选定位，不是靠翻页数页码。 公共实现放在 `admin/service/pagination.go`（`PageSize` 常量、 `ParsePage` / `ClampPage` / `TotalPages` / `NewPaginationView`）和 `admin/templates/partials/footer.html`（分页控件，`Pagination` 字段 为空时不渲染，不影响还没做分页的页面），后面四个页面直接复用， 不要各写一份。 ## 4. 蝦皮数据页 ### 4.1 工具条 ```text [导入 Excel] [批量采集] 状态[全部▾] 商品ID [________] [搜索] [删除] ``` - **导入 Excel**：选文件 → POST 上传 → 显示结果统计 （导入 5195 商品 / 6092 SKU，失败 N 行）。 `[必须]` 失败行要列出行号和原因，不能静默跳过。 - **批量采集**：勾选若干行 → 服务端**按商品去重**后建采集任务。 `[必须]` 已是"采集中"的商品跳过，并在结果里说明跳过了几个。 - **状态筛选**（`[必须]`，工单 #43）：全部 / 待补规格 / 未填 PDD 链接 / 已填链接。 这个筛选是**刚需**，不是锦上添花——本页主要用途是维护 （找出需要补规格的商品、找出还没关联 PDD 链接的商品），只靠商品 ID 搜索的话，操作员得先知道 ID 才能搜，而"哪些商品需要处理"恰恰是 不知道 ID 的时候才要问的。实测样本 5195 个商品里只有 6 个待补规格， 只做分页（260 页）翻不出来。 - 「待补规格」：`EXISTS (SELECT 1 FROM shopee_skus WHERE goods_id = 该商品 AND parse_ok = 0)`。 `[必须]` 用 `EXISTS`，不用 `JOIN` + `DISTINCT`——一个商品有多个失败 SKU 时 `JOIN` 会出重复行，`DISTINCT` 又会让分页的 `LIMIT/OFFSET` 行为难推理。 - 「未填 PDD 链接」：`pdd_goods_url IS NULL OR pdd_goods_url = ''`。 - 「已填链接」：`pdd_goods_url IS NOT NULL AND pdd_goods_url <> ''`。 - `[必须]` 筛选参数认不出来的一律当"全部"，不报错——地址栏是用户可以 随便改的。 - `[必须]` 筛选与关键词搜索可以叠加，翻页时都要保留，见 §3.2。 ### 4.2 表格列 | 列 | 显示规则 | |---|---| | ☐ | 勾选 | | 商品 ID | | | 商品名称 | 截断 + 悬停完整 | | 颜色 / 尺码 / 建议 | 解析失败的显示为 `—` 并**整行标黄**，提示需人工补 | | PDD 链接 | 空的显示"**未填写**"并标红，这是最需要操作员注意的状态 | | 采集状态 | 未填链接 / 未采集 / 采集中 / 已采集 / 采集失败。**数据来自两张表**，判断方式见 [01 需求](01-requirements.md) §6.1 | | 更新时间 | 本地时区 | `[必须]` 状态不能只靠颜色区分，必须有文字。 ### 4.3 编辑弹窗（双击行打开） 这是**从蝦皮商品出发**填 PDD 链接、发起采集的入口。 > `[注意]` PDD 商品页（[§5](#5-pdd-商品页)）也能录入链接和发起采集， > 两处并存。本页的入口目前**还是骨架**（点了返回 501）， > 两者要不要合并、以哪个为准，属于「蝦皮↔PDD 关联入口」的范围， > 由那张工单统一决定，不要在本页单独改。 ```text ┌─────────────────────────────────────────┐ │ 编辑商品 40653075144 │ ├─────────────────────────────────────────┤ │ 商品名称 【台灣現貨隔日達】西裝外套… │ ← 只读 │ 规格原文 黑色,M【建議40-50公斤】 │ ← 只读，永远显示 │ │ │ 颜色 [黑色___________] │ │ 尺码 [M_______________] │ │ 建议 [40-50公斤_______] │ │ │ │ PDD 链接 [___________________] [采集] │ ← ★ │ 采集状态 已采集（2026-08-06 15:20） │ ├─────────────────────────────────────────┤ │ [取消] [保存] │ └─────────────────────────────────────────┘ ``` `[必须]` 几条硬规则： - **本页的采集按钮只在这个弹窗里出现**，不要放到表格每一行。一个商品有 N 个 SKU 行， 放行上就是 N 个按钮干同一件事，还会建出 N 个重复任务。 - **规格原文只读且永远显示**。操作员靠它判断颜色尺码该怎么填。 - PDD 链接为空时**采集按钮置灰**，旁边提示"请先填写 PDD 链接"。 - 采集状态是"采集中"时按钮置灰，提示"已在采集中"。 - 采集失败时显示错误原因，按钮变成"重新采集"。 ### 4.4 手动新增 `[必须]` 必须提供"新增 SKU"入口。 原因：蝦皮报表只包含**有销售成绩的** SKU（样本里平均每个商品仅 1.17 个）， 订单来了查无此 SKU 是常态。没有这个入口整条链路就断了。 新增的行 `is_manual = 1`，`[必须]` 后续导入**不得删除**它们。 ### 4.5 底部状态条 ```text 共 5195 个商品 · 第 1/260 页 [首页] [上一页] [下一页] [末页] ``` 筛选后（例如状态选了"待补规格"）： ```text 待补规格：6 个商品 · 第 1/1 页 [首页] [上一页] [下一页] [末页] ``` `[必须]` 分页与状态条的通用规则见 §3.2，不在这里重复。这里只强调 蝦皮页特有的一点：导入完成后状态条**显示导入结果**（"导入完成：N 个商品 / M 个 SKU，K 行解析失败"），覆盖掉正常的统计文案，并且回到第 1 页、清空筛选—— 刚导入的数据从第一页就能看到，沿用旧筛选反而可能让人以为导入没生效。 ## 5. PDD 商品页 页面 `objectName` 为 `pddProductPage`，路由 `/pdd`。 这个页面**不依赖蝦皮和顺运宝的任何数据**，可以单独跑通整条闭环： 建商品 → 建采集任务 → Client 领走执行 → 提交结果 → 刷新看到"已采集"和规格数。 ### 5.1 工具条 ```text [添加 PDD 商品] [创建采集任务] 采集状态[全部▾] 商品ID/链接[___] [搜索] [删除] ``` - **添加 PDD 商品** → 弹窗，只填 PDD 链接。 `[必须]` 文案要写全，**不能简写成「创建」**：同一条工具条上还有 「创建采集任务」，两个都以「创建」开头，第一次用的人分不清 哪个是加商品、哪个是发起采集。 - **创建采集任务** → 勾选多行后可用。 - **采集状态筛选** → 全部 / 未采集 / 采集中 / 已采集 / 采集失败。 `[必须]` 这个筛选是**刚需**，不是锦上添花：这个页面的主要用途是维护 （找出失败的重采、找出还没采的），只按 ID 搜的话要翻页去找。 - **删除** → 勾选多行后可用。 `[必须]` 「创建采集任务」和「删除」共用**同一个表单**（靠按钮上的 `formaction` 决定提交到哪个地址），表格里的勾选框只挂一份。 为每个操作各复制一套勾选框的话，两套迟早会不同步。 `[必须]` 搜索框用 `class="search-narrow"` 收到 30%，见 [§3.1](#31-搜索框宽度)。 ### 5.2 表格列 | 列 | 显示规则 | |---|---| | 勾选 | 值是 `goods_id`，支持批量删除、批量建采集任务 | | 商品 ID | `goods_id` | | 标题 | 采集回来的；未采集时显示"（未采集，采集后自动回填）" | | 店铺 | 采集回来的 `shop_name`；未采到显示 `—`，截断处可查看完整文字 | | PDD 链接 | 截断显示，可点开（`target="_blank"` 要带 `rel="noopener noreferrer"`） | | 采集状态 | 中文文字，**不能只靠颜色**；失败时在下面补一行原因；`collecting` 超过 15 分钟没动静显示「**采集中（超时）**」，见下 | | 规格数 | 从 `skus_json` 算 | | 采集时间 | 本地时区；未采集显示 `—` | | 更新时间 | 本地时区 | `[必须]` **规格数这一列不能省。** 采到 1 个和采到 20 个差别很大—— 只采到 1 个通常意味着客户端没点开规格面板，是采集有问题。 `[必须]` **未采集显示 `—`，采到 0 个要如实显示 `0`。** 这两种是不同的情况： 前者是还没采，后者是采集出了问题（商品下架、页面改版、解析器没认出来）， 都显示成 `—` 就看不出区别了。 `[建议]` 规格数用 SQLite 的 `json_array_length(skus_json, '$.skus')` 直接算， 不要把整个 JSON 读进 Go 再数。`[必须]` 外面要包一层 `json_valid`—— `skus_json` 万一存进了坏数据，`json_array_length` 会让**整条查询报错**，页面直接打不开。 `[必须]` 空状态分两种文案：从没创建过 → 引导去点「创建」；筛选无结果 → 给"查看全部"的入口。 `[必须]` **`collecting` 超过 15 分钟没有更新，显示「采集中（超时）」，不是「采集中」。** 客户端离线、崩溃、任务被删都是常态，不是异常——一旦发生，操作员盯着「采集中」 不知道它已经死了，会一直傻等；显示超时他才知道可以重新点「创建采集任务」。 判定在**读取列表的这一刻现算**，不依赖任何后台任务，见 [03 数据模型](03-data-model.md) §4「采集超时」。 `[必须]` 状态照旧**不能只靠颜色区分**，必须有文字——超时也是文字的一部分， 不能只是把这一行的底色改深。 `[建议]` 筛选下拉里**不新增**「已超时」这个选项。它不是数据库里真实存在的 一种 `collect_status` 取值，只是「采集中」在读取那一刻的一种呈现； 加进筛选会让下拉框的取值和 `collect_status` 对不上。 ### 5.3 创建弹窗 `[必须]` **只填 PDD 链接**，其余字段全靠采集回填。 `[必须]` **链接必须能解析出 `goods_id`，解析不出来直接报错并且不写库。** 不接受短链接（`p.pinduoduo.com/xxxx`）——`goods_id` 上有 UNIQUE 约束， 防重全靠它，拿不到就没法查重，同一个商品会存成好几行。 `[必须]` 报错要说清**下一步怎么办**，例如"请在拼多多 App 的商品页点 「分享」→「复制链接」，拿到带 `goods_id=` 的完整链接"。光说"链接无效"操作员不知道改什么。 ### 5.4 编辑弹窗（双击行打开） ```text ┌─────────────────────────────────────────────┐ │ PDD 商品 737116531267 │ ├─────────────────────────────────────────────┤ │ 商品 ID 737116531267 （只读） │ │ PDD 链接 [___________________]（可编辑） │ │ 标题 西装外套三件套 （只读） │ │ 店铺 XX旗舰店 （只读） │ │ 采集状态 已采集 │ │ 失败原因 — │ │ 采集时间 2026-08-07 15:20 │ ├─────────────────────────────────────────────┤ │ 规格（3 个） │ │ 颜色分类 尺码 价格 价格来源 有货 │ │ 黑色 M ¥12.56 ✓ 实测 是 │ │ 黑色 L ¥12.56 推断 是 │ ├─────────────────────────────────────────────┤ │ [重新采集] [取消] [保存] │ └─────────────────────────────────────────────┘ ``` `[必须]` **规格和价格必须显示。** 这是采集结果的全部价值所在—— 不显示的话操作员没法确认"采得对不对、是不是我要的那个商品"。 `[必须]` 维度列的顺序按 `skus_json` 里的 `dimensions` 排，表头用 `name`。 Go 的 map 是无序的，不靠它定顺序的话，同一个商品每次刷新页面列的先后都可能变。 `[必须]` 价格显示成 `¥12.56`，底层存的是**整数分**。 `price_cent` 为 `null` 时显示"未采到"，**不得显示成 ¥0.00**—— 0 元和采不到价格是两回事，而这个数要参与价格保护比对（会花钱）。 `[必须]` `price_granularity == "color"` 时，规格表上方显示： “价格按颜色采样，同一颜色下各尺码显示同一价格。标 ✓ 的是实测价，其余为推断值。” 规格表增加“价格来源”列；`options` 与 `price_observed_at` 完全相同的行显示 “✓ 实测”，其余显示“推断”。状态不能只靠颜色表达。 `[必须]` 三种"没有规格"要分开显示，处理方式不一样： | 情况 | 显示 | |---|---| | 还没采过 | "尚未采集"，并说明怎么发起采集 | | 采完了但一个规格都没有 | 提示可能已下架或没点开规格面板，建议重采 | | `skus_json` 解析不了 | 明说数据坏了需要重新采集，**不要装作"没有规格"** | `[必须]` 编辑链接时，新链接必须还是**同一个商品**，否则拒绝并提示改用「创建」。 这一行上挂着采集结果和 SKU 映射，`goods_id` 一换那些数据就全指到错的商品上了， 之后按它下单就是买错东西。 `[必须]` 弹窗内容由**服务端渲染**（`GET /pdd/detail?id=…` 返回 HTML 片段）， 前端只负责取回来、放进壳子、显示隐藏。维度顺序、价格格式、`null` 的处理都是业务规则， 散到前端就没人维护得住了。 ### 5.5 创建采集任务 `[必须]` **不指定客户端**（`assigned_client` 为 `NULL`，`status` 为 `pending`）， 谁领到就在领取时标记谁。采集是纯读取操作，哪台机器跑都一样， 指定了反而会在那台机器关着的时候干等。 - 勾选多行 → 按 `goods_id` 去重 → 建任务； - `collect_status` 是 `collecting` 且**没超时**（15 分钟内）的**跳过**； 已超时的当作可以重建，不再跳过——这是 #24 修的死锁， 见 [03 数据模型](03-data-model.md) §4「采集超时」； - 已经是 `collected` 的**跳过**（本来就不需要重新采集）； - 建成功后把状态置为 `collecting`； - 任务的 `pdd_goods_url` 和 `pdd_goods_id` 必须填（Client 契约要求 `goods_url` 必填）。 `[必须]` 按钮文案用「**创建采集任务**」，不要用「采集」。它做的是建一个任务， 不是立刻去采——真正的采集要等 Client 来领、去手机上跑，可能几秒也可能几分钟。 点完页面上只有状态从"未采集"变成"采集中"，文案不说清楚操作员会以为没生效。 `[必须]` 结果在状态条明确提示，**跳过原因要分开说**，不能只给一句笼统的 "跳过 N 个"——那样操作员不知道该等还是该做点什么： ```text 已创建 2 个采集任务，等待客户端领取（跳过 1 个正在采集的、1 个已删除的） ``` `[必须]` **一个都没建成时不要只说「已创建 0 个」**，要让操作员知道下一步该干嘛， 比如还要等多久： ```text 没有创建任何任务：1 个正在采集中（还需等待约 12 分钟才可重试） ``` 静默跳过的话，操作员会以为任务都建上了，等半天没动静也不知道为什么。 ### 5.6 删除 软删除。`[必须]` 二次确认要写明能不能恢复、恢复后会丢什么： > 将删除 3 条记录。删除后重新创建同一链接可恢复，**但采集结果会清空**。 （复活时清空旧采集结果是既定行为——记录被删过一次，旧数据不该再当有效的用。） ### 5.7 底部状态条 ```text 共 24 条 · 已采集 18 · 未采集 4 · 采集中 1 · 采集失败 1 ``` `[必须]` 统计的是**全部未删除记录**，不随筛选变化——状态条是全局概览。 有筛选时在前面加一句 `筛选出 N 条 /`，免得操作员把筛选后的行数当成全部行数，以为记录被删了。 刚做完写操作时，状态条**先显示操作结果**，再接统计。 ## 6. 顺运宝数据页 ### 6.1 工具条 ```text [同步] [创建采购任务] 订单号 [___] [搜索] [删除] ``` `[必须]` 「同步」按工单 #46 实现： ```text 点「同步」 ├─ 本地缓存的会话未过期 ──→ 后台开始同步，立即跳回列表页， │ 状态条显示"同步已开始，请稍后刷新页面查看结果" └─ 没有缓存会话/已过期 ───→ 弹出登录弹窗（不是报错）： 账号（config.yaml 带出，只读，不显示密码） 验证码图片 [点图/换一张 可刷新] 验证码文字输入框 [登录并同步] ``` 同步是长任务，不阻塞 HTTP 请求线程——点完立即跳转，结果异步写进内存态的 "最近一次同步报告"，下次刷新页面时状态条会显示： ```text 同步完成：日期范围 2026-08-09 ~ 2026-08-09，货运单 12 张，商品明细 27 条 （新增 20，更新 7，跳过 0） ``` 有跳过/失败会在后面列出具体原因，不是只给个数字。同步中再次点「同步」会提示 "已经有一个同步任务在跑"，不会并发跑两个。 `[必须]` 搜索框宽度见 [§3.1](#31-搜索框宽度)。 ### 6.2 表格列 ☐ / 货运单明细ID / 订单号 / 商品标题 / 规格 / 蝦皮商品ID / 规格SKU / 数量 / 价格（台币）/ 图片 / **匹配状态** / 更新时间 - 一行对应顺运宝一张货运单的**一个商品明细**，不是一张货运单——一张货运单 可以有多个商品，各占一行。 - 图片显示小缩略图。`[必须]` 存 URL，不要把图片塞进数据库。 - 匹配状态是**算出来的**（`shopee_sku_id` 是否非空），不是存的字段。 本工单（#46）不做规格匹配功能，待匹配的行整行标黄，但不提供匹配入口。 - 完整货运单 JSON 不作为列显示，落在 `syb_data` 里，供后续排查用。 ### 6.3 规格匹配弹窗（双击行打开）—— 未实现，见下方说明 `[不做]` 工单 #46（顺运宝货运单同步）明确不做这一节描述的匹配弹窗， `shopee_sku_id` 由同步留空，本节描述的是**规格匹配**这个后续工单要实现的目标 界面，先记录在这里，不代表当前已经能用。 ```text ┌──────────────────────────────────────────────────┐ │ 规格匹配 · 订单 SO-20260806-001 │ ├────────────────────────┬─────────────────────────┤ │ 蝦皮 │ 拼多多 │ │ │ │ │ 颜色 黑色 │ 颜色 [黑色 ▾] │ │ 尺码 M │ 尺码 [M码 ▾] │ │ 建议 40-50公斤 │ │ │ 原文 黑色,M【建議40…】 │ 单价 ¥39.90 │ ├────────────────────────┴─────────────────────────┤ │ ⓘ 已有匹配记录，已自动带出，确认无误后保存 │ │ [取消] [保存] │ └──────────────────────────────────────────────────┘ ``` `[必须]` 几条硬规则： - 右侧下拉的选项来自该商品 `pdd_data` 里的 `dimensions`， **不要写死"颜色/尺码"两个维度**——PDD 商品可能有第三个维度。 - **打开时先查 `sku_mappings`**，有记录就自动带出并提示"已自动带出"。 这是省人工的关键：同一个蝦皮 SKU 只需人工匹配一次。 - 该商品**还没采集**（`pdd_data` 为空）时，不要显示一个空下拉让人困惑， 直接提示："该商品尚未采集 PDD 数据，请先到『蝦皮数据』填写链接并采集"， 并给一个跳转链接。 - 保存写的是 `sku_mappings`（可复用），**不是这一张订单的临时数据**。 ### 6.4 创建采购任务 勾选若干行 → 点按钮 → 逐条校验（见 [01 需求](01-requirements.md) §5）。 `[必须]` 校验不过的**不要静默跳过**，要列出来告诉操作员缺什么： ```text 成功创建 3 个任务。以下 2 条未创建： · SO-...-007 该商品未填写 PDD 链接 · SO-...-009 规格未匹配 ``` `[必须]` 创建前弹出确认框，让操作员选**分配给哪个客户端**，并确认价格上限。 价格上限默认从 `pdd_data` 带出，可改，**不允许为空**。 ## 7. 采集采购页 `tasks` 一张表用 `task_type` 区分采集和采购，本页把两种任务放在同一个 列表里显示，靠「目标」一列概括各自不同的业务信息，见 [01 需求](01-requirements.md) §4.4。 `[必须]` 导航文字和页面标题都是「**采集采购**」，不是「任务」或「采购任务」。 ### 7.1 工具条 ```text [类型▾ 全部] [状态▾ 全部] 关键词[___] [搜索] [删除] ``` - **类型**：全部 / 采集 / 采购。 - **状态**：全部 + 7 个状态，见 [01 需求](01-requirements.md) §6.2。 - **关键词**：同时匹配任务编号、订单号、PDD 商品 ID。 `[必须]` 搜索框宽度见 [§3.1](#31-搜索框宽度)。 placeholder 写「任务编号 / 订单号 / 商品 ID」，**不要写全「PDD 商品 ID」**—— 收到 30% 之后装不下，会被截断成看不出意思的半截文字。 ### 7.2 表格列 ☐ / 任务编号 / 类型 / **目标** / 状态 / 客户端 / 更新时间 ```text ☐ │ 任务编号 │ 类型 │ 目标 │ 状态 │ 客户端 │ 更新时间 ☐ │ PDD-20260807-01 │ 采集 │ PDD 737116531267 │ 已领取 │ 办公室-01 │ 15:20 ☐ │ PDD-20260807-02 │ 采购 │ SO-001 · 黑色/M · 2件 · ≤¥42.00 │ 待领取 │ — │ 15:22 ``` - `[必须]` **目标列**：采集显示 `PDD `（能 join 到未删除商品 的标题时追加显示）；采购显示 ` · <颜色/尺码> · <数量>件 · ≤<价格上限>`。 拼接逻辑在 service 层组装成一个字符串，模板只负责显示。 - `[必须]` 价格上限显示成 `¥42.00`（分转元），底层存的是整数分。 - `[必须]` **客户端列**：无主任务显示 `—`，不是空白或 ``——#17 之后 采集任务默认无主，这一列会大量为空。 - `[必须]` 类型和状态都是文字，不能只靠颜色区分。 ### 7.3 详情弹窗（双击行打开） `[必须]` **只读**。没有改派 / 重试 / 取消入口，那些是后续工单的范围。 弹窗内容： ```text ┌──────────────────────────────────────────────┐ │ 任务 PDD-20260807-01 │ ├──────────────────────────────────────────────┤ │ 类型 采集 │ │ 状态 已领取 │ │ 分配客户端 办公室-01 │ │ 领取时间 2026-08-07 15:20:31 │ │ 完成时间 — │ ├──────────────────────────────────────────────┤ │ 执行参数 │ │ PDD 链接 https://mobile.yangkeduo.com/... │ │ 目标规格 黑色 / M （采购任务才有） │ │ 数量 2 （采购任务才有） │ │ 价格上限 ¥42.00 （采购任务才有） │ ├──────────────────────────────────────────────┤ │ 错误 │ │ 错误码 PDD_PAGE_TIMEOUT │ │ 错误说明 商品页加载超时 │ ├──────────────────────────────────────────────┤ │ [关闭] │ └──────────────────────────────────────────────┘ ``` - `[必须]` 采购专有字段（数量、价格上限、目标规格）在采集任务的弹窗里 **整段隐藏**，不显示空行。 - 错误段没有错误码/说明时整段不显示。 - `[建议]` `result_data`（Client 提交的完整结果）默认折叠，展开查看； 过长时截断显示。 ### 7.4 删除 `[必须]` 批量删除要二次确认，写明"将删除 N 条，不可恢复"——`tasks` 表 没有软删除列，删了就是真删了。 ### 7.5 底部状态条 ```text 共 42 条 · 待分配 3 · 待领取 5 · 已领取 2 · 成功 30 · 需人工 1 · 失败 1 · 已取消 0 ``` `[必须]` 统计要**跟随当前筛选**：筛了「采集」就只统计采集任务， 筛了某个状态统计也随之变化，否则数字和表格对不上，操作员会以为 页面出错。这一点跟 PDD 商品页不同——那边的统计是全局概览， 不受筛选影响；本页反过来是有意的，见 [01 需求](01-requirements.md) §4.4。 ## 8. 客户端列表页 工具条：`名称 [____] [搜索] [删除]` 表格列：☐ / 名称 / 序列号 / 状态 / 最近活动 / 更新时间 - `[必须]` **状态是算出来的**：`最近活动` 在 N 分钟内为"在线"，否则"离线"。 `[建议]` N 默认 10 分钟。 - `[必须]` 名称可以人工改成好记的（"办公室-01"）。改过之后 **客户端上报的名称不再覆盖它**。 - `[建议]` 界面上说明一句："客户端执行长任务期间可能显示为离线，属正常现象。" 因为没有心跳，这是已知且接受的取舍（见 [04](04-client-api.md) §3）。 ## 9. 反馈方式 | 场景 | 怎么反馈 | |---|---| | 搜索、翻页 | 直接刷新表格，不弹任何东西 | | 导入完成 | 底部状态条 + 结果统计（成功 N / 失败 M + 失败行号） | | 保存成功 | 关闭弹窗，刷新行，状态条提示一句 | | 校验不通过 | 保留用户输入，**焦点移到第一个错误字段**，就近显示错误 | | 批量操作部分失败 | 列出失败项和原因，不要只说"部分失败" | | 删除 | 二次确认框，写明"将删除 N 条，不可恢复" | `[必须]` 报错要说清**哪一步失败、下一步做什么**，不要把 Go 的错误堆栈贴到页面上。 堆栈写日志。 ## 10. 可访问性与细节 - `[必须]` 表单控件有可见 `