6.1 KiB
6.1 KiB
标签库新增分页列表接口
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
响应：
{
"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
响应：
{
"code": 200,
"msg": "success",
"data": {
"records": [],
"total": 0,
"page": 1,
"pageSize": 20
}
}
lastUsedAt 为 null（从未使用过的新标签）：
{
"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）：
{
"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，纯接口新增，对数据库无变更。