新增接口：标签库分页列表 GET /v3/admin/tag-library/page（PR #4416，Issue #4415）

changelogs-v2/2026-06/26_4415_标签库分页列表接口-新增接口-管理后台.md

@@ -0,0 +1,216 @@
+# 标签库新增分页列表接口
+
+## 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