jacy
fed8ff3d3a
HQ 列表主操作居右、列设置贴最右侧；订单筛选状态可多选，导出同步过滤。 Co-authored-by: Cursor <cursoragent@cursor.com>
138 lines
5.4 KiB
Markdown
138 lines
5.4 KiB
Markdown
# 杜康好客 · 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 数组均可）。列表筛选为多选；空 = 全部。单值旧链接仍可用。
|