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

杜康好客 · v3.5.9 开发文档

2026-08-25 · admin-web / API
主题：门店累计核销好客权益、HQ 表格去省略号、序号列与列设置；用户列表改昵称 / 手机号不脱敏

---

1. 版本目标

1. 门店列表增加「累计核销好客权益」：该店历史核销券面额合计。
2. 全 HQ 表格去掉 ... 截断，长文本完整展示，横向滚动。
3. 每张 主列表：最左序号（跨页连续）；「列设置」弹窗控制显示列与顺序，偏好存当前 HQ 账号。
4. 用户列表：双击昵称进入编辑，离开编辑（失焦 / 回车 / Esc）即写入数据库；手机号列表明文，不脱敏。

不做：C 端 / 合伙人 / 门店端；详情 Drawer 内嵌表不加列设置。

---

2. 累计核销好客权益

口径：当前页每家店 SUM(user_redeem_record.amount)，含测试核销；无记录为 —。不是结算额 settleAmount。

GET /admin/stores 行字段 totalRedeemedBenefitAmount（数字）。详情/导出不加。

---

3. 表格展示

• 全局单元格：nowrap + 不省略；描述列表仍省略。
• 列级 ellipsis 去掉；操作列仍可 fixed: 'right'。

---

4. 序号与列设置

项	规则
序号	(page-1)*pageSize+index+1，锁定最左，不可隐藏
操作列	锁定最右，不可隐藏
弹窗	勾选显示、拖拽/上下移排序、重置默认
存储	hq_account.list_column_prefs JSON，按 listKey

{ stores: { order: ["name", "cityName"], hidden: ["intro"] } }

新列按默认位置插入且默认显示；未知 key 忽略。重置即删除该 listKey。

API

方法	路径	说明
GET	/admin/auth/me	listColumnPrefs
PUT	/admin/me/list-columns/:listKey	{ order, hidden } 或 { reset: true }；只改当前账号
PUT	/admin/users/:id	{ nickname }，空串存 null

listKey 白名单见 packages/shared-types/src/hq-list-columns.ts。无新权限键。

---

5. 用户列表：改昵称 / 手机号不脱敏

项	行为
昵称	双击单元格进入输入；失焦、回车或 Esc 退出编辑即 PUT /admin/users/:id 保存（空串写成 null）；最长 64
手机号	列表列明文 phone，不再 maskPhone。详情抽屉仍脱敏

审计：USER_UPDATE（修改用户昵称）。无新权限键，已登录 HQ 即可（与用户列表同入口）。

---

6. Prisma / SQL

hq_account.list_column_prefs JSON NULL。

脚本：server/dukang-api/prisma/migrate-hq-list-column-prefs-v359.sql

---

7. 发版步骤

步骤	动作
1	执行 migrate-hq-list-column-prefs-v359.sql 或 prisma db push
2	pnpm build（shared-types + API + admin-web）
3	发 dukang-api + admin-web

---

8. 关键路径

域	路径
门店聚合	admin-stores.service.ts
列偏好	auth.service.ts · admin-me.controller.ts
类型	packages/shared-types/src/hq-list-columns.ts
表格 hook	apps/admin-web/src/lib/useAdminListColumns.tsx
弹窗	AdminListColumnsModal.tsx
样式	admin.css
改昵称	admin-users.service.ts · UsersPage.tsx

---

9. 验收清单

• 门店列表「累计核销好客权益」= 该店核销记录金额合计；无核销为 —
• HQ 主表长字段不再 ...，可横向滑完
• 主列表最左序号跨页连续
• 列设置可隐藏/排序；保存后刷新仍在；重置恢复默认
• 序号、操作列不能在弹窗关掉或拖走
• 详情描述列表仍可省略
• 用户列表双击昵称可改，离开编辑后库中已更新
• 用户列表手机号完整可见（详情仍脱敏）