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

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

---

## 1. 版本目标

1. **门店列表**增加「累计核销好客权益」：该店历史核销券面额合计。
2. **全 HQ 表格**去掉 `...` 截断，长文本完整展示，横向滚动。
3. 每张 **主列表**：最左序号（跨页连续）；「列设置」弹窗控制显示列与顺序；可拖表头分割线改列宽。偏好（含列宽）存当前 HQ 账号。主展示列（名称 / 单号 / 昵称等）带下划线，点击进入编辑或详情。
4. **用户列表**：昵称只读（用户自己的）；新增「备注」列，双击编辑 HQ 标记，离开即写入 `user_user.hq_remark`；手机号列表明文，不脱敏。

**不做**：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"], widths: { name: 180 } } }
```

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

### API

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

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

---

## 5. 用户列表：备注 / 手机号不脱敏

| 项 | 行为 |
|----|------|
| 昵称 | 只读，来自用户自己的 `nickname`，HQ 不可改 |
| 备注 | 双击单元格进入输入；失焦、回车或 Esc 退出编辑即 `PUT /admin/users/:id` `{ hqRemark }`（空串写成 `null`）；最长 128；C 端不展示 |
| 手机号 | 列表列明文 `phone`，不再 `maskPhone`。详情抽屉仍脱敏 |

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

---

## 6. Prisma / SQL

`hq_account.list_column_prefs` JSON NULL。

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

---

## 7. 发版步骤

| 步骤 | 动作 |
|------|------|
| 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` |

---

## 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 主表长字段不再 `...`，可横向滑完
- [ ] 主列表最左序号跨页连续
- [ ] 列设置可隐藏/排序；保存后刷新仍在；重置恢复默认
- [ ] 主展示列带下划线，点击进入对应编辑或详情
- [ ] 序号、操作列不能在弹窗关掉或拖走
- [ ] 详情描述列表仍可省略
- [ ] 用户列表昵称只读；双击「备注」可改，离开编辑后 `user_user.hq_remark` 已更新；C 端看不到该字段
- [ ] 用户列表手机号完整可见（详情仍脱敏）
- [ ] 权益券列表：用户编号、订单号可点进对应用户/订单详情；来源含商品名、规格、数量、配送方式、实付金额
- [ ] 订单列表「状态」可多选；导出按所选状态过滤；不选即全部

---

## 10. 权益券列表快链与来源

- **用户**、**订单**列（及券详情）用主列下划线，分别打开用户详情抽屉、订单详情抽屉。
- **来源**：关联订单时拼 `商品名 / 规格 / 数量(瓶或箱) / 配送方式 / ¥实付`；无订单仍用 `sourceProduct`（如总部手动发放）。
- 列表接口 `order` 增补 `productName`、`productSpec`、`quantity`、`saleUnit`、`deliveryType`、`payAmount`。

---

## 11. 订单列表状态多选

`GET /admin/orders` 与 `POST /admin/orders/export` 的 `status` 支持多值（重复 query、逗号串、JSON 数组均可）。列表筛选为多选；空 = 全部。单值旧链接仍可用。