From 5bf67647a4ec4d7d1ff9338defb42f8894be006a Mon Sep 17 00:00:00 2001 From: chengma Date: Thu, 13 Aug 2026 14:58:55 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BD=92=E6=A1=A3=E4=BB=BB=E5=8A=A1=20?= =?UTF-8?q?#217?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/task/217-顺运宝多订单号搜索.md | 72 +++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 docs/task/217-顺运宝多订单号搜索.md diff --git a/docs/task/217-顺运宝多订单号搜索.md b/docs/task/217-顺运宝多订单号搜索.md new file mode 100644 index 0000000..35347cd --- /dev/null +++ b/docs/task/217-顺运宝多订单号搜索.md @@ -0,0 +1,72 @@ +# 217 Admin：支持顺运宝多订单号精确搜索 + +- 类型：需求 +- 父级大工单：#14 +- 所属 MVP / 版本：#15 / Admin MVP 后续优化 +- 状态：已完成 +- 日期：2026-08-13 +- Gitea 工单： + +## 背景与目标 + +顺运宝页面原来只把整段输入作为一个模糊关键词，同时匹配订单号和商品标题。采购员从 +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)