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