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

2026-06-26 09:06:25 +08:00

6.1 KiB

原始文件 Blame 文件历史

标签库新增分页列表接口

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，纯接口新增，对数据库无变更。

13. 关联 / 联系人

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

6.1 KiB 原始文件 Blame 文件历史 Unescape Escape