新增订单标签筛选项接口 tag-options（PR #4068，Issue #4065）

新增 GET /v3/admin/order/tag-options，返回所有订单已挂标签的去重升序列表，供订单列表标签筛选下拉使用（替代 /tag-library 避免选到无订单的标签）。同步说明 tagNames 多选为 OR 语义及传参方式。
2026-06-19 16:41:10 +08:00 · 2026-06-19 16:41:10 +08:00 · 82080d7c4a
--- a/changelogs-v2/2026-06/19_4065_订单标签筛选项接口tag-options-新增接口-管理后台.md
+++ b/changelogs-v2/2026-06/19_4065_订单标签筛选项接口tag-options-新增接口-管理后台.md
@ -0,0 +1,197 @@
+# 订单标签筛选项接口 tag-options — 新增接口 — 管理后台
+
+> 变更类型：✨ 新增接口
+> 端类型：管理后台
+> 日期：2026-06-19
+> 服务：hl-order-service-v3
+> PR：https://git.1814.love:8443/wx/HL/pulls/4068
+
+---
+
+## 1. 接口背景
+
+**功能页面**：管理后台「订单列表」页的**筛选栏 — "标签"下拉框**。
+
+**用在哪**：订单列表顶部筛选区域，用户点"标签"下拉时渲染可选标签列表，选中后把选中的标签名传给列表接口 `tagNames` 参数过滤。
+
+**为什么新增**：之前前端如果要填充标签下拉，只能调用 `/v3/admin/tag-library`（标签库全集），但标签库里含从未挂到任何订单上的标签——选了这些标签筛选结果永远为空，体验差且误导。
+
+本接口只返回**已挂到订单上的标签去重集合**，前端用此接口填充订单列表标签筛选下拉，选什么都能筛出真实结果。
+
+---
+
+## 2. 变更清单
+
+| 变更类型 | 接口 | 说明 |
+|---|---|---|
+| ✨ 新增 | `GET /v3/admin/order/tag-options` | 返回所有订单已挂标签的去重升序列表（`List<String>`），供订单列表标签筛选下拉使用 |
+| 📝 注释修正 | `GET /v3/admin/order`（订单列表） | 入参 `tagNames` 字段注释原误写"多标签为 AND"，现已修正为"OR（任一命中）"；**过滤行为一直是 OR，未变** |
+
+---
+
+## 3. 接口详情
+
+- **方法 + 路径**：`GET /v3/admin/order/tag-options`
+- **接口名**：订单标签筛选项（下拉数据源）
+- **认证**：需要 JWT（管理后台登录 token，Gateway 注入 `X-Admin-Id`）
+- **幂等性**：查询接口，天然幂等
+- **限流**：无独立限流规则
+- **说明**：路径为字面量，Spring 路由优先于 `/{id}` 动态路径，不会冲突
+
+---
+
+## 4. 接口入参
+
+无入参（无路径参数、无 Query 参数、无请求体）。
+
+---
+
+## 5. 出参字段
+
+返回类型：`Result<List<String>>`
+
+| 字段 | 类型 | 说明 | 示例 |
+|---|---|---|---|
+| `data` | `List<String>` | 标签名数组，去重后升序排列 | `["VIP客户","亲子","老客户"]` |
+
+**数据来源**：`order_tag` 表 `DISTINCT tag_name`，租户内可见，含已取消订单上挂的标签。
+
+---
+
+## 6. 枚举 / 数据字典
+
+本接口出参为字符串数组，无枚举依赖。标签名由业务自由定义（通过标签库管理），不存在固定枚举值。
+
+---
+
+## 7. 错误码
+
+| code | 含义 |
+|---|---|
+| `200` | 成功（data 为标签名数组，无订单标签时为空数组 `[]`） |
+| `401` | 未登录 / token 过期 |
+
+---
+
+## 8. 示例
+
+### 8.1 典型成功
+
+```http
+GET /v3/admin/order/tag-options
+Authorization: Bearer <token>
+```
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": ["QA_SYS_001", "VIP客户", "亲子", "老客户", "高端定制"],
+  "success": true
+}
+```
+
+### 8.2 边界——系统内尚无任何订单挂标签
+
+```http
+GET /v3/admin/order/tag-options
+Authorization: Bearer <token>
+```
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": [],
+  "success": true
+}
+```
+
+`data` 返回空数组，前端下拉应显示"暂无标签"提示，不报错。
+
+### 8.3 业务失败——未登录
+
+```http
+GET /v3/admin/order/tag-options
+```
+
+```json
+{
+  "code": 401,
+  "message": "未登录或 token 已过期"
+}
+```
+
+---
+
+## 9. 业务边界
+
+**适用**：
+- 管理后台订单列表「标签」筛选下拉的选项渲染。
+- 选中标签后，把选中值作为 `tagNames` 参数传给 `GET /v3/admin/order`（可多选，见下方注意事项）。
+
+**不适用**：
+- 不适用于标签库管理页的全量标签展示（标签库用 `/v3/admin/tag-library`）。
+- 不适用于小程序端。
+
+**特殊边界**：
+- 已取消订单上挂的标签也会出现在选项中（因为 `order_tag` 表含已取消订单的记录），这是预期行为——筛选时会返回含该标签的已取消订单。
+- 标签名升序排列，前端无需客户端排序。
+
+---
+
+## 10. 修改前后对比
+
+新增接口，无"前"状态。关联注释修正见下：
+
+| 内容 | 修改前 | 修改后 |
+|---|---|---|
+| 订单列表接口 `tagNames` 字段注释 | "多标签为 AND（交集）" | "多标签为 OR（任一命中）" |
+| 过滤行为（实际代码逻辑） | OR（未变） | OR（未变） |
+
+注释修正**不影响任何接口行为**，过滤语义一直是 OR。
+
+---
+
+## 11. 影响评估 / 回滚
+
+**破坏兼容**：无（纯新增接口 + 仅注释修正）。
+
+**前端同步上线**：
+- 建议把订单列表标签筛选下拉的数据源从 `/v3/admin/tag-library` 切换为本接口，避免出现选了筛不出结果的标签选项。
+- 切换前后功能完全兼容，前端自选节奏上线。
+
+**回滚方案**：如需回滚，前端切回 `/v3/admin/tag-library` 作数据源即可；后端接口保留不影响其他功能。
+
+---
+
+## 12. 注意事项
+
+### 标签筛选多选用法（重要）
+
+订单列表接口 `GET /v3/admin/order` 的 `tagNames` 支持多选，传法如下：
+
+```
+GET /v3/admin/order?tagNames=VIP客户&tagNames=亲子&pageNo=1&pageSize=20
+```
+
+**重复查询参数**（GET 请求，非 body），每个标签名单独一个 `tagNames=xxx`。
+
+**多选语义为 OR**：含其中任一标签的订单都会返回。
+
+- 示例：`?tagNames=VIP客户&tagNames=亲子` → 返回含"VIP客户"**或**含"亲子"的订单（二者并集）
+- 实测：VIP客户=12 单，亲子=16 单，两者 OR = 27 单（并集去重）
+
+### 数据源切换建议
+
+- 订单列表标签筛选下拉：改用 `GET /v3/admin/order/tag-options`
+- 标签库管理页全量标签：仍用 `GET /v3/admin/tag-library`（不变）
+
+---
+
+## 13. 关联 / 联系人
+
+- Issue：https://git.1814.love:8443/wx/HL/issues/4065
+- PR：https://git.1814.love:8443/wx/HL/pulls/4068
+- Commit：https://git.1814.love:8443/wx/HL/commit/59adc0acd
+- 后端负责人：腰苏图