docs: 归档任务 #217

docs/task/217-顺运宝多订单号搜索.md

@@ -0,0 +1,72 @@
+# 217 Admin：支持顺运宝多订单号精确搜索
+
+- 类型：需求
+- 父级大工单：#14
+- 所属 MVP / 版本：#15 / Admin MVP 后续优化
+- 状态：已完成
+- 日期：2026-08-13
+- Gitea 工单：<http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/217>
+
+## 背景与目标
+
+顺运宝页面原来只把整段输入作为一个模糊关键词，同时匹配订单号和商品标题。采购员从
+Excel 粘贴多个订单号时无法逐条查询，订单号前导模糊匹配也不能有效复用现有索引。
+
+本工单把该条件收敛为多订单号精确搜索：支持常见分隔符和 Excel 单列粘贴，并明确显示
+输入、命中、明细及未命中数量，方便采购员核对批量查询是否完整。
+
+## 最终方案
+
+- Service 统一解析订单号：支持中英文逗号、分号、空格、Tab 和换行，去除空白并按首次
+  出现顺序去重；限制为最多 100 个不同订单号、原始输入 4000 字符、单号 191 字符。
+- Repository 使用参数化 `IN (?,...)` 精确查询，继续与店铺、普通处理阶段及 Service
+  推导的高级处理阶段组合；不修改数据库结构，复用 `idx_syb_orders_order`。
+- 列表结果分别统计命中的不同订单数和商品明细数，并按输入顺序返回未命中订单号。
+- 页面使用紧凑的单行高度文本区，确保 Excel 多行粘贴不会丢失分隔符。Enter 提交搜索，
+  Shift+Enter 可换行。合法输入规范化为逗号分隔后继续传给分页和列表写操作。
+- 超限输入返回字段校验错误并在订单号输入附近显示，HTTP 页面仍正常返回，不把用户输入
+  错误报告成服务器故障。
+- 原“订单号或商品标题”模糊搜索已按确认方案移除；本工单不增加跨页选择或对全部结果
+  批量操作。
+
+最终实现与建单方案一致。为可靠支持 Excel 多行粘贴，页面控件从单行 `input` 调整为外观
+紧凑的 `textarea`，并补充 Enter 键提交守卫。
+
+## 改了哪些
+
+- `admin/service/syb.go`：订单号解析、限制、规范化、普通与高级阶段命中/未命中统计。
+- `admin/repository/syb.go`：订单号集合筛选、参数化精确 `IN` 和命中订单号查询。
+- `admin/handler/web/others.go`：可展示校验错误、筛选状态保留和批量命中反馈。
+- `admin/templates/syb/list.html`：多订单号文本区、帮助说明、错误及未命中反馈。
+- `admin/static/css/app.css`、`admin/static/js/app.js`：紧凑文本区样式和键盘提交行为。
+- `admin/main_test.go`、`admin/syb_interaction_template_test.go`：页面反馈、错误和键盘静态守卫。
+- `admin/repository/syb_test.go`、`admin/service/syb_workflow_test.go`、
+  `admin/service/purchase_workflow_test.go`：精确匹配、分隔符、限制、组合阶段和统计回归。
+- `docs/admin/01-requirements.md`、`docs/admin/05-ui-specification.md`：同步需求和界面基线。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 单个订单号精确查询，不再匹配商品标题或相似订单号 | 通过 |
+| 支持六类分隔符并按首次出现顺序去重 | 通过 |
+| 参数化多值查询可与店铺、普通阶段和高级阶段组合 | 通过 |
+| 页面显示输入、命中、明细和未命中订单号 | 通过 |
+| 三类输入上限就地提示，不返回 500 | 通过 |
+| 分页和列表写操作保留规范化后的查询条件 | 通过 |
+| 无数据库迁移并复用现有订单号索引 | 通过 |
+| Go 1.23.0 的 build、test、vet 全部通过 | 通过 |
+
+## 测试
+
+- 执行的命令：
+  - `go test . -run Syb -count=1 -v`
+  - `$env:GOTOOLCHAIN='go1.23.0'; go build ./...; go test ./... -count=1; go vet ./...`
+- 结果：顺运宝模板、键盘守卫、Repository、Service 及完整 Admin 回归全部通过。
+- **没验证到的部分**：未设置 `CMAUTOBUY_MYSQL_TEST=1`，因此依赖真实 MySQL 8 的
+  `TestMainPagesReturnOK` 路由集成用例按项目规则跳过；未在真实浏览器手工粘贴 Excel，
+  未部署生产环境。
+
+## 相关提交
+
+- `8f2b3f7` feat: 支持顺运宝多订单号搜索 (#217)