docs: 归档任务 #140

docs/task/140-顺运宝观测规格.md

@@ -0,0 +1,49 @@
+# 140 Admin：保存并展示顺运宝观测规格，不覆盖蝦皮主数据
+
+- 类型：需求
+- 父级大工单：#14
+- 所属 MVP / 版本：#15 / 商品目录数据接入后续
+- 状态：已完成
+- 日期：2026-08-11
+- Gitea 工单：<http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/140>
+
+## 背景与目标
+
+顺运宝货运单已经保存蝦皮商品 ID、规格、历史台币售价和图片，但这些是订单观测数据，不是正式蝦皮 SKU 主数据。本任务在不覆盖目录或人工数据的前提下，让采购员从蝦皮商品详情查看这些历史观测。
+
+## 最终方案
+
+- 直接按 `syb_orders` 的 `shopee_goods_id + spec_key` 聚合，不复制观测表。
+- 顺运宝只更新自身创建的商品骨架标题，`api`、`report` 等来源的商品不动。
+- 详情页展示最近历史台币售价、图片、订单数、累计数量和最后出现时间，并明确它不是正式 SKU 或 PDD 人民币价格。
+- 用统一 `SpecKey()` 与正式 SKU 精确关联；恰好一条时显示匹配，多条或零条不猜测、不写回。
+
+## 改了哪些
+
+- `admin/repository/syb.go`：增加来源保护的骨架更新和观测规格聚合查询。
+- `admin/service/shopee_list.go`：组装观测规格及正式 SKU 唯一匹配结果。
+- `admin/templates/shopee/detail_modal.html`：增加顺运宝观测规格区域。
+- `admin/repository/syb_test.go`、`admin/service/shopee_list_test.go`、`admin/main_test.go`：覆盖来源保护、重放统计、匹配和页面文案。
+- `docs/admin/03-data-model.md`、`docs/admin/05-ui-specification.md`：记录读模型和界面规则。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 新商品补建骨架，后续仅安全更新 `syb` 来源的非空标题 | 通过 |
+| 不覆盖其他来源标题、PDD 关联和正式 SKU | 通过 |
+| 详情显示规格、最近台币售价、订单数、累计数量、图片和时间 | 通过 |
+| 唯一匹配才显示正式 SKU，多条或零条不猜测 | 通过 |
+| 同一 `syb_id` 重放不重复累计 | 通过 |
+| 页面区分正式目录、顺运宝观测和 PDD 价格 | 通过 |
+| Go 1.23 build/test/vet | 通过 |
+
+## 测试
+
+- 执行的命令：`$env:GOTOOLCHAIN='go1.23.0'; go build ./...; go test ./... -count=1; go vet ./...`
+- 结果：Admin 全部包构建、测试和静态检查通过。
+- **没验证到的部分**：未在生产数据规模的 MySQL 8.4 `_test` 库执行 `EXPLAIN`；聚合 SQL 已由现有 MySQL 兼容实现及单元测试覆盖。
+
+## 相关提交
+
+- `c05c4fa` 展示顺运宝观测规格