docs(changelog): 告知前端 #3414 选择员工下拉无数据=未接searchAdmins接口(专项通知mmg+字段映射坑)

changelogs-v2/2026-06/05_3414_选择员工下拉无数据-前端未接searchAdmins接口-管理后台.md

@@ -0,0 +1,85 @@
+# 【前端 BUG·管理后台】自定义推送「选择员工」下拉无数据 = 前端未接 searchAdmins 接口
+
+> **关联**: 工单 #3414（内部员工站内信，PR #3424/#3425/#3427）
+> **服务**: 前端 hl-ui（后端无改动）| **提报时间**: 2026-06-05
+>
+> **存放目录**: `changelogs-v2/2026-06/`
+> **影响范围**: 管理后台「通知中心 / 自定义推送」→ 站内信(内部员工) → 指定员工
+> **类型**: 前端接线 bug（mmg 修），**后端已实测正常无需改动**
+
+---
+
+## ⚠️ 关键说明
+
+测试环境「自定义推送」页，选「**站内信(内部员工)**」通道 + 「**指定员工**」后，「**选择员工**」下拉显示「**无数据**」。
+
+**根因 = 前端把下拉 UI 画了，但没接后端搜索接口。** 后端 `GET /admin/notification/custom-push/admins` 实测 **200、返 20 个员工**，后端没问题。
+
+---
+
+## 1. 实证（测试服 nginx 访问日志）
+
+在该页面操作时，浏览器对内部接口的调用**只有一条 `GET /admin/role/all`**（给「按角色」选项用的），对搜员工的 `/admin/notification/custom-push/admins` **零调用**。即「选择员工」远程搜索框没绑后端接口。
+
+后端实测对照（Python 直调，均 200 有数据）：
+
+```bash
+# 空关键词返前 20 个员工
+GET /admin/notification/custom-push/admins?keyword=        -> 200, 20 条
+# 按姓名/用户名模糊
+GET /admin/notification/custom-push/admins?keyword=admin   -> 200, 2 条
+```
+
+---
+
+## 2. 前端修法（mmg）
+
+### 2.1 「指定员工」选择员工下拉 → 接成远程搜索
+
+输入时调用（带当前 admin token）：
+
+```
+GET /admin/notification/custom-push/admins?keyword={输入值}
+```
+
+响应 `data`：员工数组，每项字段：
+
+| 字段 | 类型 | 用途 |
+|---|---|---|
+| `adminId` | string | **option 的 value**（雪花 String，提交时收集成 `adminIds`）|
+| `name` | string | **option 的 label**（企微真名，可能为空则用 `username`）|
+| `username` | string | 登录名（label 兜底）|
+| `roleKey` / `roleName` | string | 角色（可展示副文本）|
+
+提交推送时（§见 04_3414 §5.2）：`{channel:"ADMIN_INAPP", targetType:"ADMIN_SPECIFIC", adminIds:[选中的 adminId...], title, content}`。
+
+### 2.2 ⚠️ 字段名和 C 端不一样，别照搬
+
+若克隆 C 端「选择用户」组件（`/custom-push/users`），注意字段名**不同**：
+
+| 角色 | 接口 | 返回字段 |
+|---|---|---|
+| C 端客人 | `/custom-push/users` | `id` / `realName` / `phone` / `avatarUrl` |
+| **内部员工** | `/custom-push/admins` | **`adminId` / `name` / `username`** / roleKey / roleName |
+
+克隆组件**必须改字段映射**（`id→adminId`、`realName→name`），否则就算接上接口，也会因取不到字段继续「无数据」。
+
+### 2.3 「按角色」目标
+
+「按角色」当前已接 `/admin/role/all` 加载角色列表（正常）。选角色后提交：`{channel:"ADMIN_INAPP", targetType:"ADMIN_BY_ROLE", roleKeys:[选中的 roleKey...], title, content}`。
+
+---
+
+## 3. 后端状态（无需改动）
+
+- `/admin/notification/custom-push/admins`（搜员工）：已部署测试服，实测 200 有数据。
+- `/admin/notification/custom-push`（发站内信）：已部署，ADMIN_SPECIFIC / ADMIN_BY_ROLE 实测通过。
+- 内部员工站内信分类固定 SYSTEM（后端强制，前端「消息分类」对内部员工可隐藏）。
+
+---
+
+## 4. 关联
+
+- 主功能 changelog：`04_3414_内部员工站内信收件箱-SSE实时推送-管理后台.md`（§5 选内部员工 + §3 SSE）
+- 后端负责人：@wx
+- 前端对接（本 bug 修复）：**mmg**