给用户增加“备注”列

docs/杜康好客-v3.5.9-开发文档.md

@@ -1,7 +1,7 @@
 # 杜康好客 · v3.5.9 开发文档
 
 > **2026-08-25** · admin-web / API  
-> **主题**：门店累计核销好客权益、HQ 表格去省略号、序号列与列设置；用户列表改昵称 / 手机号不脱敏
+> **主题**：门店累计核销好客权益、HQ 表格去省略号、序号列与列设置；用户备注 / 手机号不脱敏
 
 ---
 
@@ -10,7 +10,7 @@
 1. **门店列表**增加「累计核销好客权益」：该店历史核销券面额合计。
 2. **全 HQ 表格**去掉 `...` 截断，长文本完整展示，横向滚动。
 3. 每张 **主列表**：最左序号（跨页连续）；「列设置」弹窗控制显示列与顺序，偏好存当前 HQ 账号。
-4. **用户列表**：双击昵称进入编辑，离开编辑（失焦 / 回车 / Esc）即写入数据库；手机号列表明文，不脱敏。
+4. **用户列表**：昵称只读（用户自己的）；新增「备注」列，双击编辑 HQ 标记，离开即写入 `user_user.hq_remark`；手机号列表明文，不脱敏。
 
 **不做**：C 端 / 合伙人 / 门店端；详情 Drawer 内嵌表不加列设置。
 
@@ -52,20 +52,21 @@
 |------|------|------|
 | GET | `/admin/auth/me` | `listColumnPrefs` |
 | PUT | `/admin/me/list-columns/:listKey` | `{ order, hidden }` 或 `{ reset: true }`；只改当前账号 |
-| PUT | `/admin/users/:id` | `{ nickname }`，空串存 `null` |
+| PUT | `/admin/users/:id` | `{ hqRemark }`，空串存 `null`；不改 nickname |
 
 `listKey` 白名单见 `packages/shared-types/src/hq-list-columns.ts`。无新权限键。
 
 ---
 
-## 5. 用户列表：改昵称 / 手机号不脱敏
+## 5. 用户列表：备注 / 手机号不脱敏
 
 | 项 | 行为 |
 |----|------|
-| 昵称 | 双击单元格进入输入；失焦、回车或 Esc 退出编辑即 `PUT /admin/users/:id` 保存（空串写成 `null`）；最长 64 |
+| 昵称 | 只读，来自用户自己的 `nickname`，HQ 不可改 |
+| 备注 | 双击单元格进入输入；失焦、回车或 Esc 退出编辑即 `PUT /admin/users/:id` `{ hqRemark }`（空串写成 `null`）；最长 128；C 端不展示 |
 | 手机号 | 列表列明文 `phone`，不再 `maskPhone`。详情抽屉仍脱敏 |
 
-审计：`USER_UPDATE`（修改用户昵称）。无新权限键，已登录 HQ 即可（与用户列表同入口）。
+审计：`USER_UPDATE`（修改用户备注）。无新权限键，已登录 HQ 即可（与用户列表同入口）。
 
 ---
 
@@ -73,7 +74,12 @@
 
 `hq_account.list_column_prefs` JSON NULL。
 
-脚本：[`server/dukang-api/prisma/migrate-hq-list-column-prefs-v359.sql`](../server/dukang-api/prisma/migrate-hq-list-column-prefs-v359.sql)
+`user_user.hq_remark` VARCHAR(128) NULL。
+
+脚本：
+
+- [`migrate-hq-list-column-prefs-v359.sql`](../server/dukang-api/prisma/migrate-hq-list-column-prefs-v359.sql)
+- [`migrate-user-hq-remark-v359.sql`](../server/dukang-api/prisma/migrate-user-hq-remark-v359.sql)
 
 ---
 
@@ -81,7 +87,7 @@
 
 | 步骤 | 动作 |
 |------|------|
-| 1 | 执行 `migrate-hq-list-column-prefs-v359.sql` 或 `prisma db push` |
+| 1 | 执行 `migrate-hq-list-column-prefs-v359.sql`、`migrate-user-hq-remark-v359.sql` 或 `prisma db push` |
 | 2 | `pnpm build`（shared-types + API + admin-web） |
 | 3 | 发 `dukang-api` + `admin-web` |
 
@@ -97,7 +103,7 @@
 | 表格 hook | `apps/admin-web/src/lib/useAdminListColumns.tsx` |
 | 弹窗 | `AdminListColumnsModal.tsx` |
 | 样式 | `admin.css` |
-| 改昵称 | `admin-users.service.ts` · `UsersPage.tsx` |
+| 备注 | `admin-users.service.ts` · `UsersPage.tsx` |
 
 ---
 
@@ -109,5 +115,5 @@
 - [ ] 列设置可隐藏/排序；保存后刷新仍在；重置恢复默认
 - [ ] 序号、操作列不能在弹窗关掉或拖走
 - [ ] 详情描述列表仍可省略
-- [ ] 用户列表双击昵称可改，离开编辑后库中已更新
+- [ ] 用户列表昵称只读；双击「备注」可改，离开编辑后 `user_user.hq_remark` 已更新；C 端看不到该字段
 - [ ] 用户列表手机号完整可见（详情仍脱敏）