# 后端 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>>`:

```json
{
  "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 拼接从:

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

改为:

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

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

```js
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
