# 标签库新增分页列表接口

## 1. 接口背景

订单标签库目前只有不分页的全量列表接口 `GET /v3/admin/tag-library`，供打标签弹窗下拉候选使用。
新增 `GET /v3/admin/tag-library/page` 分页版，满足标签库管理页面场景（分页浏览、关键字搜索、仅看置顶）。
两个接口并存，不影响现有不分页接口的使用。

## 2. 变更清单

| 类型 | 接口 | 说明 |
|---|---|---|
| ✨ 新增接口 | `GET /v3/admin/tag-library/page` | 分页查询当前管理员可见的标签库列表 |

## 3. 接口详情

- **方法 + 路径**：`GET /v3/admin/tag-library/page`
- **接口名**：标签库分页列表
- **描述**：分页查询当前管理员可见的标签库列表，数据范围为系统标签（SYSTEM）并集本人个人标签（PERSONAL），数据范围、过滤口径、排序规则与不分页接口 `GET /v3/admin/tag-library` 完全一致。
- **认证**：管理后台登录态（JWT），`userId` 从请求头 `X-Admin-Id` 自动派生，前端无需手动传。
- **幂等性**：GET 只读，天然幂等。
- **限流**：无特殊限流配置，走网关全局限流。

## 4. 接口入参

### 4.1 Query 参数

| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| page | int | 否 | 1 | 页码，从 1 开始 |
| pageSize | int | 否 | 20 | 每页条数 |
| keyword | string | 否 | - | 标签名模糊匹配（LIKE %keyword%），不传则不过滤 |
| pinnedOnly | boolean | 否 | false | true=仅返回置顶记录（is_pinned=true），false=全部返回 |

### 4.2 请求体

无。

## 5. 出参字段

响应结构：`Result<PageResult<TagLibraryItemVO>>`

**PageResult 外层字段**：

| 字段 | 类型 | 说明 |
|---|---|---|
| records | array | 当页数据列表，元素见下表 |
| total | int | 符合条件的总记录数 |
| page | int | 当前页码 |
| pageSize | int | 每页条数 |

**TagLibraryItemVO 每条字段**：

| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 标签库行 ID（雪花 ID，序列化为字符串，防 JS 精度丢失） |
| tagScope | string | 作用域枚举值：`SYSTEM` / `PERSONAL`（详见 §6） |
| tagName | string | 标签名 |
| tagColor | string | HEX 色值，如 `#5B8FF9` |
| sortOrder | int | 排序值 |
| isPinned | boolean | 是否置顶 |
| usedCount | int | 使用次数 |
| lastUsedAt | string(datetime) | 最近使用时间，格式 `yyyy-MM-dd HH:mm:ss`，可为 null |

**排序规则（后端固定，前端无需额外排序）**：`is_pinned DESC, sort_order ASC, last_used_at DESC`

## 6. 枚举 / 数据字典

**tagScope — 标签作用域**

| 枚举值 | 含义 |
|---|---|
| SYSTEM | 系统标签，全员共享可见 |
| PERSONAL | 个人标签，仅创建者本人可见、可维护 |

## 7. 错误码

| 错误码 | HTTP 状态 | 含义 | 触发场景 |
|---|---|---|---|
| - | 401 | 未登录 | 请求未携带有效 JWT |
| 581426 | 200 | 管理员会话丢失 | OperatorHolder ThreadLocal 为空（@Async 深度防御场景） |

## 8. 示例

### 8.1 典型成功

请求：
```
GET /v3/admin/tag-library/page?page=1&pageSize=20
```

响应：
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "records": [
      {
        "id": "1938010234567890001",
        "tagScope": "SYSTEM",
        "tagName": "VIP客户",
        "tagColor": "#5B8FF9",
        "sortOrder": 1,
        "isPinned": true,
        "usedCount": 42,
        "lastUsedAt": "2026-06-25 14:32:00"
      },
      {
        "id": "1938010234567890002",
        "tagScope": "PERSONAL",
        "tagName": "高复购",
        "tagColor": "#FF6B6B",
        "sortOrder": 2,
        "isPinned": false,
        "usedCount": 7,
        "lastUsedAt": "2026-06-20 09:15:00"
      }
    ],
    "total": 18,
    "page": 1,
    "pageSize": 20
  }
}
```

### 8.2 边界情况

**标签库为空（或过滤条件无匹配）**：
```
GET /v3/admin/tag-library/page?keyword=不存在的关键字&pinnedOnly=true
```

响应：
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "records": [],
    "total": 0,
    "page": 1,
    "pageSize": 20
  }
}
```

**lastUsedAt 为 null（从未使用过的新标签）**：
```json
{
  "id": "1938010234567890099",
  "tagScope": "PERSONAL",
  "tagName": "待观察",
  "tagColor": "#AAAAAA",
  "sortOrder": 99,
  "isPinned": false,
  "usedCount": 0,
  "lastUsedAt": null
}
```

### 8.3 业务失败

**未登录访问（401）**：
```
GET /v3/admin/tag-library/page
(无 Authorization header)
```

响应：HTTP 401，网关拦截，不返回业务 JSON。

**管理员会话丢失（错误码 581426）**：
```json
{
  "code": 581426,
  "msg": "管理员未登录或会话已过期",
  "data": null
}
```

## 9. 业务边界

**适用**：
- 标签库管理页面分页展示
- 需要关键字搜索标签的场景
- 仅展示置顶标签的场景

**不适用**：
- 打标签弹窗下拉候选列表（仍使用不分页接口 `GET /v3/admin/tag-library`，数据量小且需全量展示）

**特殊边界**：
- 数据范围是「本人可见」：系统标签（全员共享）+ 本人创建的个人标签。不跨用户查看他人个人标签。
- `pinnedOnly=false` 与不传 `pinnedOnly` 等效，均返回全部可见记录。
- `keyword` 传空字符串等同于不过滤。

## 10. 修改前后对比

本次为纯新增接口，无修改，跳过此节。

## 11. 影响评估 / 回滚

本次为纯新增接口，无现有接口变更，无破坏兼容性，跳过此节。

## 12. 注意事项

- `id` 字段为雪花 ID 字符串，前端请勿用 number 类型接收（会精度丢失），统一用 string。
- 排序由后端固定（置顶优先 → sortOrder 升序 → 最近使用降序），前端无需在前端再做排序。
- 不分页接口 `GET /v3/admin/tag-library` 保持不变，打标签弹窗继续调用原接口即可，无需迁移。
- 零 DDL，纯接口新增，对数据库无变更。

## 13. 关联 / 联系人

- **Issue**：https://git.1814.love:8443/wx/HL/issues/4415
- **PR**：https://git.1814.love:8443/wx/HL/pulls/4416
- **Commit**：https://git.1814.love:8443/wx/HL/commit/c596e3a76
- **后端负责人**：yst