docs: 归档任务 #151

docs/task/151-顺运宝店铺列和搜索.md

@@ -0,0 +1,63 @@
+# 151 Admin：顺运宝数据增加店铺列和店铺搜索
+
+- 类型：需求
+- 父级大工单：#14
+- 所属 MVP / 版本：#15 / 顺运宝数据处理后续
+- 状态：已完成
+- 日期：2026-08-11
+- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/151
+
+## 背景与目标
+
+顺运宝接口已在货运单原始数据中返回 `shopName`，但 Admin 仅保存原始 JSON，
+列表没有独立店铺列，也不能按店铺查询。采购员因此难以按来源店铺定位和核对货运单。
+本任务把店铺提升为可查询字段，回填历史数据，并在顺运宝列表中展示和搜索。
+
+## 最终方案
+
+新增 SQLite v9 和 MySQL v11 迁移，为 `syb_orders` 增加可空 `shop_name` 字段，
+并从 `syb_data.stock.shopName` 回填仍为空的历史记录。迁移先判断列是否存在，
+回填只处理空值；无效 JSON 和空白店铺保持 NULL，因此迁移中断后可以安全重放。
+
+后续同步从顺运宝合并后的货运单原始数据读取并去除店铺名首尾空白，写入独立字段。
+列表的统一 SQL 条件增加店铺名模糊查询，并与订单号/标题关键词、处理阶段共同生效；
+列表和 COUNT 共用同一条件，避免分页总数不一致。
+
+页面在订单号搜索框左侧增加“店铺”输入框，在订单号后增加“店铺”列。长店铺名截断，
+鼠标悬停可查看完整名称；空值显示破折号。分页、详情、同步、登录、删除、创建采购任务
+以及同步记录刷新均保留店铺筛选条件。
+
+## 改了哪些
+
+- `admin/model/model.go`、`admin/repository/syb.go`：增加店铺字段、持久化、读取和组合筛选。
+- `admin/repository/db.go`、`admin/repository/mysql_db.go`、`admin/repository/sqlite_to_mysql.go`：增加 SQLite v9、MySQL v11、历史回填、自检和 SQLite 到 MySQL 字段迁移。
+- `admin/service/syb.go`：同步提取店铺，列表视图和高级阶段筛选透传店铺条件。
+- `admin/handler/web/others.go`：读取店铺参数，并在分页、弹窗、同步记录及写操作返回中保留页面状态。
+- `admin/templates/syb/list.html`、`admin/templates/syb/detail_modal.html`：增加店铺搜索、店铺列和隐藏状态字段。
+- `admin/**/*_test.go`：覆盖迁移回填与重放、同步写入、组合筛选、分页及表单状态保持。
+- `docs/admin/03-data-model.md`、`docs/admin/05-ui-specification.md`：记录数据版本、字段来源和页面交互。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| SQLite v9 和 MySQL v11 可增加店铺列并回填有效历史数据 | 通过 |
+| 无效 JSON、缺失字段和空白店铺不会导致迁移失败 | 通过 |
+| 迁移可重放，已有非空店铺不会被历史回填覆盖 | 通过 |
+| 新同步记录把 `shopName` 写入独立字段 | 通过 |
+| 店铺支持参数化模糊查询，并可与关键词、阶段组合 | 通过 |
+| 列表和 COUNT 共用筛选条件，分页总数一致 | 通过 |
+| 页面显示店铺列，长文本截断且可查看完整值 | 通过 |
+| 分页、弹窗、同步记录及写操作返回保留店铺条件 | 通过 |
+| 生产 6,358 条历史记录完成回填，服务和公网登录页正常 | 通过 |
+
+## 测试
+
+- 执行的命令：在 `admin/` 使用 `GOTOOLCHAIN=go1.23.0` 执行 `go test ./... -count=1`、`go vet ./...`、`go build ./...`；另在独立 MySQL 8.4 测试库执行 `go test ./repository -run 'V11' -count=1 -v`。
+- 结果：全部通过；`git diff --check` 通过。MySQL v11 历史回填与重放测试通过，临时测试库及其临时授权已清理。
+- 生产部署：以提交 `9d4d6fc` 构建 Linux amd64 二进制，SHA-256 为 `98ed1eba286aa86644e0a65ebb2a096863f3c03742e44ffe0b6e426c158df6b2`。部署前备份位于 `/opt/cmautobuy/backups/autobuy-before-151-20260811-144048.sql.gz`，gzip 校验通过且权限为 `600`。服务已切换至 `/opt/cmautobuy/releases/9d4d6fc/`；systemd 为 active/enabled，MySQL schema 为 v11，6,358 条顺运宝记录均有店铺，共 39 个店铺，本机和公网 HTTPS 登录页均返回 200。
+- **没验证到的部分**：未使用生产账号登录后，在真实浏览器人工核对店铺列内容、组合筛选结果和窄窗口布局；模板、URL 状态和查询行为已由自动化测试覆盖。
+
+## 相关提交
+
+- `9d4d6fc` 增加顺运宝店铺筛选