From 5221560ee0f6795398f21bf667db1cee401f38b4 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Tue, 28 Apr 2026 10:48:39 +0800
Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E=E5=AD=97=E6=AE=B5:=E7=AE=A1?=
 =?UTF-8?q?=E7=90=86=E5=91=98=E8=A1=A8=E5=8A=A0=E4=BC=81=E4=B8=9A=E5=BE=AE?=
 =?UTF-8?q?=E4=BF=A1=E5=AE=A2=E6=9C=8DID(customerServiceId)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

工单 #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>
---
 ...feat_admin-user_add-customer-service-id.md | 151 ++++++++++++++++++
 1 file changed, 151 insertions(+)
 create mode 100644 changelogs/2026-04/28_feat_admin-user_add-customer-service-id.md

diff --git a/changelogs/2026-04/28_feat_admin-user_add-customer-service-id.md b/changelogs/2026-04/28_feat_admin-user_add-customer-service-id.md
new file mode 100644
index 0000000..bfc5fea
--- /dev/null
+++ b/changelogs/2026-04/28_feat_admin-user_add-customer-service-id.md
@@ -0,0 +1,151 @@
+# 新增字段:管理员表加「企业微信客服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` 表新增列：
+
+```sql
+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) |
+
+请求示例：
+```json
+{
+  "username": "zhangsan",
+  "roleIds": [3],
+  "customerServiceId": "wkAJ2GCAAA_kfid_001"
+}
+```
+
+### 2. 更新管理员 `PUT /admin/user/{adminId}`
+
+请求体 `UpdateAdminRequest` 新增字段：
+
+| 字段 | 类型 | 必填 | 长度 | 说明 |
+|---|---|---|---|---|
+| `customerServiceId` | string | 否 | ≤64 | 企业微信客服系统客服ID。**传 null 保留原值，传空字符串 `""` 清空** |
+
+请求示例：
+```json
+{
+  "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：
+  ```json
+  {
+    "code": 400,
+    "message": "customerServiceId: 客服ID长度不能超过64个字符",
+    "data": null,
+    "success": false
+  }
+  ```
+
+---
+
+## 前端处理（yst / mmg）
+
+### 必做改动
+1. **管理员管理列表页**（截图位置：`管理员管理` 主表格）
+   - 加列「客服 ID」（建议放在「企业微信」列右边）
+   - 单元格直接展示 `customerServiceId` 字符串，为 null 时显示 `-`
+
+2. **新增成员表单**
+   - 加输入框「客服 ID」，placeholder 提示 `wkAJ2GCAA...（企业微信客服系统 open_kfid）`
+   - 单行文本，maxlength=64
+   - **非必填**
+
+3. **编辑成员表单**（同新增）
+   - 字段名 `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`）