114 lines
3.8 KiB
Markdown
114 lines
3.8 KiB
Markdown
# 杜康好客 · 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` |
|
||
|
||
```ts
|
||
{ 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`](../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 主表长字段不再 `...`，可横向滑完
|
||
- [ ] 主列表最左序号跨页连续
|
||
- [ ] 列设置可隐藏/排序；保存后刷新仍在；重置恢复默认
|
||
- [ ] 序号、操作列不能在弹窗关掉或拖走
|
||
- [ ] 详情描述列表仍可省略
|
||
- [ ] 用户列表双击昵称可改，离开编辑后库中已更新
|
||
- [ ] 用户列表手机号完整可见（详情仍脱敏）
|