hl-api-changelog/changelogs/2026-05/09_feat_admin_customizers-add-enterprise-wechat-name.md

后端 feat 通知 — /admin/user/customizers 加企微姓名字段(产品分享下拉显示中文真名)

日期: 2026-05-09 类型: 后端 feat (产品分享体验优化) 模块: 产品管理 → 产品列表 → 分享产品(ShareModal) 通知: @mmg 前端是否需改动: 是(label 一行改动) 严重性: 体验级(P3)

---

⚠️ 关键变化

针对用户反馈"产品分享下拉显示英文 username (admin/test_admin/mmg/qulili/bozhihe) 不直观,应显示企业微信真名(中文)",后端 PR #1930 已上线:

• GET /admin/user/customizers 响应每条新增 enterpriseWechatName 字段(可空 String)
• 绑了企微的 admin → 返该 admin 在企微通讯录里的中文姓名(如「王骁」「米明光」「曲丽莉」)
• 未绑企微 / 企微 ID 是脏数据(wechat_user 表查不到) → 返 null,前端按约定 fallback 到 username

前端只需改 ShareModal.vue 一行 label 拼接逻辑。

---

后端接口契约(更新)

GET /admin/user/customizers

Response Result<List<CustomizerSimpleVO>>:

{
  "code": 200,
  "data": [
    { "adminId": 1001, "username": "admin", "enterpriseWechatName": null, "avatar": null },
    { "adminId": 1002, "username": "test_admin", "enterpriseWechatName": null, "avatar": null },
    { "adminId": "2021059720172838914", "username": "wx", "enterpriseWechatName": "王骁", "avatar": "https://..." },
    { "adminId": "2027579942221352962", "username": "mmg", "enterpriseWechatName": "米明光", "avatar": "https://..." },
    { "adminId": "2033349904889524226", "username": "qulili", "enterpriseWechatName": "曲丽莉", "avatar": null },
    { "adminId": "2033349906135203841", "username": "bozhihe", "enterpriseWechatName": "卜志鹤 18847040111", "avatar": null }
  ]
}

字段	类型	必返	说明
data[].adminId	Long|String	✅	注意雪花 ID 是 String,要 String 处理防精度丢失(已在前一条 changelog 提过)
data[].username	String	✅	admin 登录名
data[].enterpriseWechatName	String	新增	企微真名,可空
data[].avatar	String	❌	admin_user 自身头像

字段顺序保持 adminId / username / enterpriseWechatName / avatar(JSON 顺序非强约束,但 Swagger 文档与 ApiModelProperty 顺序一致)。

---

前端建议改法

文件:hl-ui/src/views/product/list/components/ShareModal.vue

把 line ~93-96 的 label 拼接从:

.map((u) => ({
  label: u.username,
  value: String(u.adminId),
}))

改为:

.map((u) => ({
  label: u.enterpriseWechatName || u.username,   // ← 优先企微真名,fallback username
  value: String(u.adminId),
}))

可选:为了让选择更直观,可以在企微名后追加一行小字 username,如:

label: u.enterpriseWechatName ? `${u.enterpriseWechatName}（${u.username}）` : u.username

(具体形式由前端 UX 决定,后端不强制。)

---

✅ 已经测试服 round-trip 验证(2026-05-09 21:51)

经 https://api.test.1814.love:9443/admin/user/customizers + SUPER_ADMIN token 实测 11 条抽样,DB ↔ 接口完全一致:

adminId             username     DB expected wxname              接口返 enterpriseWechatName  ✅
1001                admin        NULL                            null                          ✅
1002                test_admin   NULL (脏数据 LEFT JOIN 不到)     null                          ✅
2021059720172838914 wx           王骁                            王骁                          ✅
2027579942221352962 mmg          米明光                          米明光                        ✅
2033349904889524226 qulili       曲丽莉                          曲丽莉                        ✅
2033349906135203841 bozhihe      卜志鹤 18847040111              卜志鹤 18847040111            ✅
2033349907380940801 pantingting  潘婷婷18604706500               潘婷婷18604706500             ✅
2033349908622426113 wangyu       呼籁旅行-王宇                    呼籁旅行-王宇                  ✅
2033349910786715649 lixiaosong   小松                            小松                          ✅
2033350011374485506 zhangjing    张晶13354709299                 张晶13354709299               ✅
2046065465288949761 cz           蒋雨莲                          蒋雨莲                        ✅

注意一些定制师的 wechat_user.name 自带电话号(如「卜志鹤 18847040111」「潘婷婷18604706500」「张晶13354709299」)— 那是企微通讯录里的原始数据,本接口原样返回,前端展示时如不希望带号码可在前端做正则截断,但后端不做加工。

---

不影响范围

• 接口路径 / Method 零变化
• 鉴权逻辑零变化
• N+1 已防御(批量 IN 查 wechat_user,1 次 SQL),不会因为 admin 数量变多导致性能劣化
• /admin/user/designers 接口(C 端订单展示用)零影响,继续过滤 active+企微非空,本次只改 customizers

---

相关 PR / 历史

PR	说明	状态
#1919	实现 admin 分享产品功能(Closes #1918)	✅ 已合
#1924	修复 PR #1919 暴露的 2 个回归(中文括号 + fee_item 全量)	✅ 已合 + 已部署
#1930	本通知关联:customizers 接口加 enterpriseWechatName(企微真名)	✅ 已合 + 已部署 + QA 通过

---

历史 changelog 关系

changelog 文件	说明	是否仍有效
09_frontend_notice_admin_product-share-use-customizers-endpoint.md	通知前端切到 /admin/user/customizers	✅ 有效,本通知是其 follow-up
09_fix_admin_product-share-2-regressions.md	PR #1924 修复后端 2 个回归	✅ 有效,与本通知正交
本通知 09_feat_admin_customizers-add-enterprise-wechat-name.md	customizers 加企微姓名字段	✅ 最新,前端需配合改 1 行

---

联系人: wx