API Changelog Bot 5221560ee0 新增字段:管理员表加企业微信客服ID(customerServiceId)

工单 #1519 / PR #1521
admin_user 表加 customer_service_id VARCHAR(64) DEFAULT NULL
admin/user 创建/更新/详情/列表四接口加同名字段
@Size(max=64) 校验
PUT 时传 null 保留原值, 传空串清空, 与 enterpriseWechatId 走专属换绑策略不同
测试服已部署 + ALTER + E2E 6 场景验证通过

前端 yst/mmg 需补充: 列表加列, 新增/编辑表单加输入框

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-28 10:48:39 +08:00

4.4 KiB

原始文件 Blame 文件历史

新增字段:管理员表加「企业微信客服ID」(customerServiceId)

类型: 后端新增字段 + 前端管理后台展示/编辑关联: 工单 #1519 / PR #1521 / 用户(wx)需求日期: 2026-04-28 影响范围: 管理员管理（admin/user）模块的所有列表、详情、新增、编辑接口

背景

管理员管理页面要展示并维护每个管理员对应的企业微信「客服系统」客服 ID（open_kfid），用于后续与企业微信客服 API 对接。

与现有 enterpriseWechatId 的区别：

enterpriseWechatId = 员工的企业微信 userid（已有字段，通过 /wechat-binding 专属接口换绑）
customerServiceId = 企业微信「客服系统」里的客服账号 ID（新增字段，open_kfid，无需换绑校验）

数据库变更

admin_user 表新增列：

ALTER TABLE admin_user ADD COLUMN customer_service_id VARCHAR(64) DEFAULT NULL
  COMMENT '企业微信客服系统客服ID(open_kfid)，可空' AFTER enterprise_wechat_id;

类型 VARCHAR(64)，可为 NULL
不建索引、不加唯一约束
不参与查询过滤

接口变更（共 4 处，全部位于现有 admin 接口）

1. 新增管理员 `POST /admin/user`

请求体 CreateAdminRequest 新增字段：

字段	类型	必填	长度	说明
`customerServiceId`	string	否	≤64	企业微信客服系统客服ID(open_kfid)

请求示例：

{
  "username": "zhangsan",
  "roleIds": [3],
  "customerServiceId": "wkAJ2GCAAA_kfid_001"
}

2. 更新管理员 `PUT /admin/user/{adminId}`

请求体 UpdateAdminRequest 新增字段：

字段	类型	必填	长度	说明
`customerServiceId`	string	否	≤64	企业微信客服系统客服ID。传 null 保留原值，传空字符串 `""` 清空

请求示例：

{
  "roleIds": [3],
  "customerServiceId": "wkNEW_kfid_002"
}

⚠️ 与 enterpriseWechatId（PUT 时被忽略，需走专属换绑接口）不同，customerServiceId 在 PUT 接口直接生效，不需要换绑校验。

3. 管理员详情 `GET /admin/user/{adminId}`

响应体 AdminUser 新增字段：

字段	类型	说明
`customerServiceId`	string \| null	企业微信客服系统客服ID

4. 管理员列表 `GET /admin/user`

响应数组每个元素新增同字段 customerServiceId。

校验规则

长度 ≤64 字符

超长返回 HTTP 200 + 业务码 400：

{
  "code": 400,
  "message": "customerServiceId: 客服ID长度不能超过64个字符",
  "data": null,
  "success": false
}

前端处理（yst / mmg）

必做改动

管理员管理列表页（截图位置：管理员管理 主表格）
- 加列「客服 ID」（建议放在「企业微信」列右边）
- 单元格直接展示 customerServiceId 字符串，为 null 时显示 -
新增成员表单
- 加输入框「客服 ID」，placeholder 提示 wkAJ2GCAA...（企业微信客服系统 open_kfid）
- 单行文本，maxlength=64
- 非必填
编辑成员表单（同新增）
- 字段名 customerServiceId
- 不传 = 保留原值；传空串 "" = 清空原值

兼容性

零破坏：新增字段，未传入时后端落空值，原有调用方完全无影响
TypeScript 类型补充：AdminUser 类型加 customerServiceId?: string | null

单元 + E2E 测试覆盖

单元测试（4/4 全绿）

createAdmin_withCustomerServiceId_persistsField
createAdmin_nullCustomerServiceId_persistsNull
updateAdmin_withCustomerServiceId_overwritesValue
updateAdmin_nullCustomerServiceId_keepsOriginalValue

测试服 E2E（6/6 全过）

创建管理员 + customerServiceId → ✅
GET 详情返回 → ✅
PUT 更新覆盖 → ✅
PUT null 保留原值 → ✅
列表查询返回 → ✅
@Size(max=64) 校验 400 → ✅

不在本次范围

不与企业微信客服 API 真正对接（后续工单）
字段不参与查询过滤、不分单
不建索引、不加唯一约束

部署状态

✅ 测试服 admin_user 已 ALTER（生产环境上线时需同步执行 ALTER）
✅ 测试服 hl-user-service 已 Deploy Panel 部署
✅ 测试服端到端验证通过（经网关 https://api.test.1814.love:9443）

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