docs(changelog): #7942 团期看板 keyword 支持按期号「第N期」精确搜索（修复）

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-20 09:42:54 +08:00
@@ -0,0 +1,99 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7942"
+title: "团期看板 keyword 支持按期号「第N期」精确搜索（无字段变更）"
+consumer: "admin"
+author: "jw(GIT)"
+change_type: "修复"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "团期看板三个入口（分页列表 GET /v3/admin/order/group-batch、统计条 /summary、导出 /export）的 keyword 现在支持按期号搜索：输入「第3期」「3期」「第3」都能精确命中 batchLabel=3 那一期；原有的 batchNo / batchName 包含匹配逐字不变，非期号关键词结果与改前一致。没有新增、修改、删除任何端点，请求与响应字段全不变，故 change_type 取「修复」（同 20_7539 先例）。前端不需要改代码即可受益——搜索框本来就标着「期号 / 名称」，此前照着输入恒零命中。后端已合并 dev-v3（915c01df5）并部署 TEST，网关三入口实测通过（工单 #7942）。"
+updated_at: "2026-09-20"
+base: "dev-v3"
+---
+
+# order-v3: 团期看板 keyword 支持按期号「第N期」精确搜索
+
+> **服务**: hl-order-service-v3 (端口 8086)
+> **PR**: [#7950](https://git.1814.love:8443/wx/HL/pulls/7950)
+> **Issue**: [#7942](https://git.1814.love:8443/wx/HL/issues/7942)
+> **日期**: 2026-09-20
+> **影响范围**: 管理后台「团期订单」看板的搜索框（分页列表 / 统计条 / 导出三个入口）
+
+---
+
+## ⚠️ 关键变化
+
+- **本单没有接口结构变化**：没有新增、修改、删除端点，请求参数与响应字段全部不变。
+- **`keyword` 多认一种写法**：界面把班期显示成「第{batchLabel}期」、搜索框标注「期号 / 名称」，此前照着输入「第3期」**恒零命中**；现在能精确命中期号为 3 的那一期。
+- **原有匹配不动**：`batchNo` / `batchName` 的包含匹配逐字不变，非期号关键词（如「10月8日」）结果与改前完全一致。
+- **前端不需要改代码**：搜索框、入参都没变，部署后直接生效。
+
+---
+
+## 一、行为说明
+
+| 输入 | 改前 | 改后 |
+|------|------|------|
+| `第3期` | 0 条 | 命中期号为 3 的那一期 |
+| `3期`、`第3`、` 第 3 期 `（带空格） | 0 条 | 同上 |
+| `第1期` | 0 条 | 只命中第 1 期，**不连带**第 10、11、21 期 |
+| `3` | 按 `batchNo` / `batchName` 包含匹配 | **逐字不变** |
+| `10月8日`、`999490` 等非期号 | 按包含匹配 | **逐字不变** |
+
+期号的识别规则：关键词去空白后，去掉一层前缀「第」和一层后缀「期」，剩下是纯数字（长度 ≤ 9）就当期号；否则按原来的包含匹配走。
+
+**精确匹配而不是模糊匹配**：期号用等值比较，所以「第1期」不会连带命中第 10、11、21 期。
+
+---
+
+## 二、生效范围
+
+三个入口同一套口径（口径写在一处共享件里，避免出现「统计条搜得到、列表搜不到」）：
+
+| 入口 | 路径 |
+|------|------|
+| 团期分页列表 | `GET /v3/admin/order/group-batch` |
+| 团期看板统计条 | `GET /v3/admin/order/group-batch/summary` |
+| 团期列表导出 | `GET /v3/admin/order/group-batch/export` |
+
+带 `productId` 时按界面显示的期号匹配（取产品侧实时期号；产品侧已删的孤儿行回落团期侧快照）；不带 `productId` 时走数据库条件。两条路径结果一致。
+
+---
+
+## 三、边界
+
+- 期号为空的行（`batchLabel` 为 null）不会因为新增条件被排除，非期号关键词下的结果与改前一致。
+- 导出本来就只包含**已建团**的班期，所以搜「第1期」可能出现「统计条 1 条、导出 0 行」——这是导出范围的既有差异，与本次改动无关。
+- 纯数字关键词（如「3」）仍按 `batchNo` 包含匹配，会返回较多无关班期；收紧它会改变既有行为，另行评估（见工单「后续工单」第 2 条）。
+
+---
+
+## 四、测试环境已验证
+
+被测版本：hl-order-service-v3 = dev-v3 `915c01df5`（2026-09-18 17:52 部署，双实例 running）。改前基线在同一批数据上跑过一遍逐项对照。
+
+```
+产品 2100839045562077186（10 期，期号 1~10，仅第 3 期已建团），每个关键词同时打
+分页列表 / 统计条 / 导出 三个入口：
+  第3期 / 3期 / 「 第3期 」 改前 0 → 改后 1（期号 3）            ✓
+  第1期                    改前 0 → 改后 1（期号 1），不连带第 10 期 ✓
+  3 / 1（纯数字）           改前 10 → 改后 10，10 个 batchNo 逐字一致 ✓
+  10月8日 / 999490 等非期号  改前 1 → 改后 1，逐字一致              ✓
+  batchLabel 为 null 的孤儿行  未被新条件排除                       ✓
+  统计条与导出对同一 keyword 同口径                                  ✓
+```
+
+---
+
+## 五、关联 / 联系人
+
+- **Issue**: [#7942](https://git.1814.love:8443/wx/HL/issues/7942)
+- **PR**: [#7950](https://git.1814.love:8443/wx/HL/pulls/7950)
+- **Merge commit**: [915c01df5](https://git.1814.love:8443/wx/HL/commit/915c01df5)
+- **后端负责人**: @jw