cmautobuy/docs/admin/05-ui-specification.md

05 Admin 界面规范

• 文档状态：基线草案，待界面评审
• 技术栈：Go html/template 服务端渲染 + 手写 CSS + 原生 JS / htmx

本文档中 [必须] / [建议] / [待定] 的含义见 文档索引。 没有标注的默认是 [必须]。看不懂的词查 术语表。

1. 设计目标

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

2. 统一的三段式布局

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

┌────────────────────────────────────────────────────────────┐
│ [导航] 蝦皮数据 │ PDD 商品 │ 顺运宝数据 │ 采购任务 │ 客户端 │
├────────────────────────────────────────────────────────────┤
│ 顶部工具条：[操作按钮…] [搜索框] [搜索] [删除]              │
├────────────────────────────────────────────────────────────┤
│ ☐ │ 列1 │ 列2 │ 列3 │ …                                    │
│ ☐ │     │     │     │                                      │
│                    数据表格（占满剩余高度）                  │
│                                                            │
├────────────────────────────────────────────────────────────┤
│ 底部状态条：最近一次操作的结果和关键统计                     │
└────────────────────────────────────────────────────────────┘

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

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

3. 表格通用规则

• [必须] 第一列是勾选框，表头有全选。
• [必须] 行的身份用业务主键（商品規格ID、货运单ID、任务编号、序列号）， 不得用行号——排序和筛选一变行号就错位。
• [必须] 批量删除要二次确认，弹窗里写清删几条、能不能恢复。 硬删写"将删除 N 条，不可恢复"；软删除的（如 PDD 商品）要说明恢复方式和会丢什么， 见 §5.6。含糊其辞和吓唬人一样糟——两种都会让操作员不敢动手。
• [必须] 删除、导入用 POST，不得用 GET。浏览器和插件会预取 GET 链接。
• [建议] 默认按 更新时间 DESC 排序。
• [建议] 一页 50 条，超过分页。搜索走数据库，不要一次查出来在内存里过滤。
• [必须] 长文本（商品标题）截断显示，鼠标悬停给完整内容。
• [必须] 空状态要分情况，文案不能都是"暂无数据"：
  • 从没导入过 → "还没有数据，点左上角『导入』开始"
  • 搜索无结果 → "没有匹配的记录" + 清除条件入口

4. 蝦皮数据页

4.1 工具条

[导入 Excel] [批量采集]   商品ID [________] [搜索]   [删除]

• 导入 Excel：选文件 → POST 上传 → 显示结果统计 （导入 5195 商品 / 6092 SKU，失败 N 行）。 [必须] 失败行要列出行号和原因，不能静默跳过。
• 批量采集：勾选若干行 → 服务端按商品去重后建采集任务。 [必须] 已是"采集中"的商品跳过，并在结果里说明跳过了几个。

4.2 表格列

列	显示规则
☐	勾选
商品 ID
商品名称	截断 + 悬停完整
颜色 / 尺码 / 建议	解析失败的显示为 — 并整行标黄，提示需人工补
PDD 链接	空的显示"未填写"并标红，这是最需要操作员注意的状态
采集状态	未填链接 / 未采集 / 采集中 / 已采集 / 采集失败。数据来自两张表，判断方式见 01 需求 §6.1
更新时间	本地时区

[必须] 状态不能只靠颜色区分，必须有文字。

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

这是从蝦皮商品出发填 PDD 链接、发起采集的入口。

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

┌─────────────────────────────────────────┐
│ 编辑商品 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，[必须] 后续导入不得删除它们。

5. PDD 商品页

页面 objectName 为 pddProductPage，路由 /pdd。

这个页面不依赖蝦皮和顺运宝的任何数据，可以单独跑通整条闭环： 建商品 → 建采集任务 → Client 领走执行 → 提交结果 → 刷新看到"已采集"和规格数。

5.1 工具条

[添加 PDD 商品] [创建采集任务]  采集状态[全部▾] 商品ID/链接[___] [搜索]        [删除]

• 添加 PDD 商品 → 弹窗，只填 PDD 链接。 [必须] 文案要写全，不能简写成「创建」：同一条工具条上还有 「创建采集任务」，两个都以「创建」开头，第一次用的人分不清 哪个是加商品、哪个是发起采集。
• 创建采集任务 → 勾选多行后可用。
• 采集状态筛选 → 全部 / 未采集 / 采集中 / 已采集 / 采集失败。 [必须] 这个筛选是刚需，不是锦上添花：这个页面的主要用途是维护 （找出失败的重采、找出还没采的），只按 ID 搜的话要翻页去找。
• 删除 → 勾选多行后可用。

[必须] 「创建采集任务」和「删除」共用同一个表单（靠按钮上的 formaction 决定提交到哪个地址），表格里的勾选框只挂一份。 为每个操作各复制一套勾选框的话，两套迟早会不同步。

[必须] 搜索框用 class="search-narrow" 收到 30%，让「搜索」按钮紧挨着它。 不要去改 .toolbar input[type="text"] 那条通用规则——五个页面共用它， 改了会把蝦皮 / 顺运宝 / 任务 / 客户端四页的搜索框一起改掉。 搜索表单上的 grow 类要保留，它负责把「删除」按钮顶到最右侧。

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 编辑弹窗（双击行打开）

┌─────────────────────────────────────────────┐
│ 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 来领、去手机上跑，可能几秒也可能几分钟。 点完页面上只有状态从"未采集"变成"采集中"，文案不说清楚操作员会以为没生效。

[必须] 结果在状态条明确提示，跳过了几个也要说：

已创建 3 个采集任务，等待客户端领取（跳过 1 个采集中或已删除的）

静默跳过的话，操作员会以为任务都建上了，等半天没动静也不知道为什么。

5.6 删除

软删除。[必须] 二次确认要写明能不能恢复、恢复后会丢什么：

将删除 3 条记录。删除后重新创建同一链接可恢复，但采集结果会清空。

（复活时清空旧采集结果是既定行为——记录被删过一次，旧数据不该再当有效的用。）

5.7 底部状态条

共 24 条 · 已采集 18 · 未采集 4 · 采集中 1 · 采集失败 1

[必须] 统计的是全部未删除记录，不随筛选变化——状态条是全局概览。 有筛选时在前面加一句 筛选出 N 条 /，免得操作员把筛选后的行数当成全部行数，以为记录被删了。

刚做完写操作时，状态条先显示操作结果，再接统计。

6. 顺运宝数据页

6.1 工具条

[同步] [创建采购任务]   订单号 [________] [搜索]   [删除]

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

6.2 表格列

☐ / 货运单ID / 订单号 / 商品标题 / 蝦皮商品ID / 规格SKU / 数量 / 价格（台币）/ 图片 / 匹配状态 / 更新时间

• 图片显示小缩略图，点击看大图。[必须] 存 URL，不要把图片塞进数据库。
• 匹配状态是算出来的（sku_mappings 里有没有记录），不是存的字段。
• 完整货运单 JSON 不作为列显示，在详情里看。

6.3 规格匹配弹窗（双击行打开）

┌──────────────────────────────────────────────────┐
│ 规格匹配 · 订单 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 需求 §5）。

[必须] 校验不过的不要静默跳过，要列出来告诉操作员缺什么：

成功创建 3 个任务。以下 2 条未创建：
  · SO-...-007  该商品未填写 PDD 链接
  · SO-...-009  规格未匹配

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

7. 采购任务页

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

表格列：☐ / 订单号 / 商品标题 / 颜色 / 尺码 / 数量 / 价格上限 / 蝦皮ID / 分配客户端 / 状态 / 更新时间

• [必须] 颜色尺码显示的是 PDD 侧的规格（实际要买的），不是蝦皮的。
• [必须] 价格上限显示成 ¥42.00（分转元），底层存的是整数分。
• [建议] 提供"改派"操作，把任务分给别的客户端—— 没有心跳，客户端挂了要靠人工改派。
• 状态含义见 01 需求 §6.2。

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

8. 客户端列表页

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

表格列：☐ / 名称 / 序列号 / 状态 / 最近活动 / 更新时间

• [必须] 状态是算出来的：最近活动 在 N 分钟内为"在线"，否则"离线"。 [建议] N 默认 10 分钟。
• [必须] 名称可以人工改成好记的（"办公室-01"）。改过之后 客户端上报的名称不再覆盖它。
• [建议] 界面上说明一句："客户端执行长任务期间可能显示为离线，属正常现象。" 因为没有心跳，这是已知且接受的取舍（见 04 §3）。

9. 反馈方式

场景	怎么反馈
搜索、翻页	直接刷新表格，不弹任何东西
导入完成	底部状态条 + 结果统计（成功 N / 失败 M + 失败行号）
保存成功	关闭弹窗，刷新行，状态条提示一句
校验不通过	保留用户输入，焦点移到第一个错误字段，就近显示错误
批量操作部分失败	列出失败项和原因，不要只说"部分失败"
删除	二次确认框，写明"将删除 N 条，不可恢复"

[必须] 报错要说清哪一步失败、下一步做什么，不要把 Go 的错误堆栈贴到页面上。 堆栈写日志。

10. 可访问性与细节

• [必须] 表单控件有可见 <label>，占位符不能当标签用。
• [必须] 状态不能只靠颜色，必须有文字。
• [建议] 搜索框支持回车提交。
• [建议] 主要操作支持键盘 Tab 到达。
• [必须] 金额显示带币种符号，台币和人民币要能一眼分清（NT$ / ¥）。