hl-api-changelog/changelogs-v2/2026-09/13_7625_员工选择器接口-新增接口-管理后台.md

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	7625	员工选择器轻量接口：按部门+关键词查员工 adminId/姓名，不限角色，供业务表单经办人下拉	admin	yst	新增接口	deployed	not_required	verified	mmg	8a9eae337077a3406ffe7d67db0b55e8c40dba0a		2026-09-13	新增只读接口 GET /admin/user/employee-options，只要求登录、不限制角色（任何登录操作员可用），供财务等业务表单经办人/员工选择器"下拉。替代有角色限制的 GET /admin/user。【前端 2026-09-13 交付 verified】api/user.js 新增 getEmployeeOptions（GET /user/employee-options，不限角色，区别于 getUserPage 限 SUPER_ADMIN/ADMIN），供 #7612 业务外收支经办人下拉；adminId 雪花字符串透传，姓名优先 enterpriseWechatName 回落 username。随 #7612 同 commit 交付，新增 user.spec。	2026-09-13	dev-v3

员工选择器轻量接口 —— GET /admin/user/employee-options

服务: hl-user-service 端: 管理后台 类型: 🆕 新增接口（只读） 日期: 2026-09-13 关联: Issue #7625 / PR #7627（已合并 dev-v3，已部署测试服）

一、接口背景

业务表单（如财务"业务外收支/经办人"）需要一个"员工选择器"下拉：按部门过滤 + 关键词模糊，返回员工 adminId + 姓名，供选定经办人。现有接口都不合适：

• GET /admin/user（管理员列表）限 SUPER_ADMIN/ADMIN 角色，其他角色 403，普通操作员不可用。
• GET /admin/wechat/users 返回的是企微 userid（String），不含 adminId。

故新增本接口：任何登录操作员都可用，直接返回业务要用的 adminId + 姓名。

二、接口详情

GET /admin/user/employee-options

• 鉴权：只要求登录（网关 token），不限制角色（任何登录 admin 可用）。
• 性质：只读查询。

三、入参（Query）

字段	类型	必填	说明
deptId	Long(String)	否	部门过滤（传部门树节点 id；员工任一部门命中即返回）
keyword	String	否	关键词模糊（用户名 / 企微姓名）
page	Integer	否	页码，默认 1（钳制 [1,100]）
pageSize	Integer	否	每页条数，默认 20

四、出参

Result<PageResult<EmployeeOptionRespVO>>，records 项字段：

字段	类型	说明
adminId	String	员工 adminId（Long 已转 String 防 JS 精度丢失）——业务用它做关联值
username	String	登录名
enterpriseWechatName	String	姓名（企微真名；未绑企微时为 null，可回落 username 显示）
deptNames	String	所属部门名（如 "运营部"；未绑部门为 null）

PageResult 含 total + records。

五、示例

典型·查运营部员工

GET /admin/user/employee-options?deptId=35&page=1&pageSize=20
→ 200 { "code":200, "message":"成功", "data":{ "total":1, "records":[
     { "adminId":"2083457702519873537", "username":"jinwei", "enterpriseWechatName":"金卫", "deptNames":"运营部" } ] } }

典型·关键词搜姓名

GET /admin/user/employee-options?keyword=金&page=1&pageSize=20
→ 200 { "code":200, "data":{ "total":1, "records":[ { "adminId":"...", "enterpriseWechatName":"金卫", ... } ] } }

边界·无该部门员工 / 越界页

GET /admin/user/employee-options?deptId=999  → 200 { "code":200, "data":{ "total":0, "records":[] } }
GET /admin/user/employee-options?page=999    → 200 { "code":200, "data":{ "total":<总数>, "records":[] } }（越界返空 records，total 保留）

六、业务边界 / 注意事项

1. 不限角色：任何登录操作员可调用，无需 SUPER_ADMIN/ADMIN。
2. 按 deptId 筛会漏未绑企微的员工（其部门归属来自企微同步，未绑企微则无部门数据）；如需全员，不传 deptId 用 keyword 搜。
3. 出参不含手机号/敏感信息，仅 adminId/username/姓名/部门名，属后台内部通讯录性质。
4. 典型用法（经办人下拉）：先选部门（部门树 GET /admin/wechat/departments/tree）→ 用该 deptId 调本接口过滤本部门员工 → 选中取 adminId 传给业务接口（如 nonbiz operatorId）。

七、关联 / 联系人

• Issue：https://git.1814.love:8443/wx/HL/issues/7625
• PR：https://git.1814.love:8443/wx/HL/pulls/7627
• 消费方示例：业务外收支经办人下拉（changelog 13_7612_业务外收支接供应商与经办人-修改接口-管理后台.md）
• 负责人：yst（腰苏图）