# 订单标签筛选项接口 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
- 后端负责人：腰苏图
