v3.5.8和v3.5.9版本更新

docs/杜康好客-v3-PRD.md

@@ -27,6 +27,8 @@
 | 3.5.5 | 08-23 | HQ 订单监控导出 Excel/PDF + 列表页布局优化 | [`v3.5.5`](./杜康好客-v3.5.5-开发文档.md) |
 | 3.5.6 | 08-23 | HQ 任务导出；核销/财务银行信息；工单图片入任务；运营去调试；门店审核全屏 | [`v3.5.6`](./杜康好客-v3.5.6-开发文档.md) |
 | 3.5.7 | 08-23 | 门店端核销记录时间显示秒；首页「今日核销金额」文案 | [`v3.5.7`](./杜康好客-v3.5.7-开发文档.md) |
+| 3.5.8 | 08-24 | HQ 单账号追加/撤销权限；运营改客服修复；城市门店服务+城市范围 | [`v3.5.8`](./杜康好客-v3.5.8-开发文档.md) |
+| 3.5.9 | 08-25 | 门店累计核销好客权益；HQ 表格去省略号；序号列 + 列设置；用户列表改昵称 / 手机号不脱敏 | [`v3.5.9`](./杜康好客-v3.5.9-开发文档.md) |
 
 ---
 
@@ -60,6 +62,14 @@
 
 **权限**：合伙人平级隔离；推广员仅拓店+看自己店；手机号脱敏（门店/合伙人中间4位）。
 
+**HQ WebAdmin 权限（v3.5.8）**：
+
+- 分组：超级管理员 / 运营 / 财务 / 客服 / **城市门店服务**
+- 生效权限 =（角色权限 ∪ 账号追加）− 账号撤销
+- 任意 HQ 账号可勾选负责城市；未勾选 = 全国。城市门店服务必须 ≥1 城，且只能看勾选城市的门店（列表、入驻审核、套餐/信息变更审核、评价、账户、资源）。分类为全国字典。
+- 城市门店服务默认：概览、门店列表、审核通知、评价、分类（不含账户/资源）。分类可新增/编辑，不可删除。概览按权限裁剪，且只看负责城市。
+- 超管始终全权限、全国可见
+
 ---
 
 ## 3. 核心规则
@@ -126,8 +136,11 @@
 - 未填联系电话时，对外展示回退登录手机号（兼容旧数据）。
 - **不**再因客户端 `validation_error` 自动创建技术支持工单。
 - 合伙人入驻提交前须展示 HQ 可配企微客服二维码，并确认已添加客服。
-- HQ 门店列表：长店名截断、操作列右固定、表过宽可横向滚动。
-- 详 [`v3.4.16`](./杜康好客-v3.4.16-门店联系电话与体验优化.md)。
+- HQ 门店列表：店名完整展示、操作列右固定、表过宽可横向滚动（v3.5.9 去掉省略号）。
+- HQ 主列表：最左序号；「列设置」控制显示列与顺序，偏好挂当前 HQ 账号。
+- 门店列表展示「累计核销好客权益」（该店核销券面额合计）。
+- HQ 用户列表：双击昵称、离开编辑即保存；列表手机号不脱敏（详情仍脱敏）。
+- 详 [`v3.4.16`](./杜康好客-v3.4.16-门店联系电话与体验优化.md)、[`v3.5.9`](./杜康好客-v3.5.9-开发文档.md)。
 
 ---
 

docs/杜康好客-v3-现状对照.md

@@ -62,9 +62,13 @@
 | 3.5.5 | [`HQ 订单导出 + 订单监控页优化`](./杜康好客-v3.5.5-开发文档.md) | 🔶 开发完成，待发版 |
 | 3.5.6 | [`HQ 任务导出/财务银行信息/工单图片/运营去调试/审核全屏`](./杜康好客-v3.5.6-开发文档.md) | ✅ 已交付 |
 | 3.5.7 | [`门店核销记录时间秒 + 今日核销金额文案`](./杜康好客-v3.5.7-开发文档.md) | 🔶 开发完成 |
+| 3.5.8 | [`HQ 追加/撤销权限 + 运营改客服 + 城市门店服务`](./杜康好客-v3.5.8-开发文档.md) | 🔶 开发完成 |
+| 3.5.9 | [`门店累计核销 + HQ 去截断 + 列设置`](./杜康好客-v3.5.9-开发文档.md) | 🔶 开发完成 |
 
 | 日期 | 说明 |
 |------|------|
+| 2026-08-25 | v3.5.9：门店列表累计核销好客权益；HQ 表格去省略号；主列表序号 + 列设置存 HQ 账号；用户列表双击改昵称、手机号不脱敏 |
+| 2026-08-24 | v3.5.8：HQ 单账号追加/撤销权限；运营改客服；城市门店服务与城市范围；分类删除权限与概览按权限/城市裁剪 |
 | 2026-08-23 | v3.5.7：门店核销记录时间显示秒；首页「今日到账金额」→「今日核销金额」 |
 | 2026-08-23 | v3.5.6：开发计划任务导出；核销/财务银行信息与打款凭证；工单图片入任务；运营去调试；门店审核全屏 |
 | 2026-08-23 | HQ 订单监控：筛选/勾选导出 Excel（xlsx）与 PDF；`POST /admin/orders/export` |

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

@@ -0,0 +1,132 @@
+# 杜康好客 · v3.5.8 开发文档
+
+> **2026-08-24** · admin-web / API  
+> **主题**：HQ 单账号追加/撤销权限、运营改客服修复、城市门店服务角色与城市范围
+
+---
+
+## 1. 版本目标
+
+1. **单账号权限** 在角色基础上可追加，也可撤销某项功能。
+2. **运营 → 客服** 可保存成功，且生效权限跟随新角色（清空账号级追加/撤销）。
+3. **新分组「城市门店服务」**：默认门店列表、审核通知、评价、分类；按账号勾选城市，非勾选城市的门店不可见。
+4. 任意 HQ 账号都可绑城市；**未勾选 = 全国**。该新角色 **必须至少 1 个城市**。
+5. 超管始终全权限、全国可见，不受撤销/城市限制。
+
+**不做**：C 端 / 合伙人 / 门店端；按区分权；小程序版本号。
+
+---
+
+## 2. 权限模型
+
+公式：`生效权限 = (角色权限 ∪ 账号追加) − 账号撤销`
+
+| 层 | 存储 | 说明 |
+|----|------|------|
+| 角色 | `hq_role_permission` | 分组默认能力，超管基础权限固定 |
+| 账号追加 | `hq_account_permission.effect=GRANT` | 在角色之上加点权限 |
+| 账号撤销 | `hq_account_permission.effect=DENY` | 去掉角色已有的某项 |
+
+同一账号同一权限键只能 GRANT 或 DENY。切换角色时清空该账号 GRANT/DENY。
+
+### 2.1 角色
+
+| 值 | 标签 | 默认 |
+|----|------|------|
+| SUPER_ADMIN | 超级管理员 | 目录全部（含调试；危险操作需按用户勾选） |
+| OPS | 运营 | 与现网一致，且含拆分后的门店子权限 |
+| FINANCE | 财务 | 同上（含门店子权限） |
+| CUSTOMER_SERVICE | 客服 | dashboard / users / orders / tickets / tech_support / invoices / logs |
+| CITY_STORE_SERVICE | 城市门店服务 | dashboard、stores、store_audits、store_ratings、store_categories（**无** store_categories_delete） |
+
+### 2.2 门店权限拆分
+
+| 键 | 菜单 |
+|----|------|
+| `stores` | 门店列表（含入驻审核） |
+| `store_audits` | 审核通知（套餐变更 / 信息变更） |
+| `store_ratings` | 门店评价 |
+| `store_categories` | 门店分类（全国字典，不按城过滤；可新增/编辑） |
+| `store_categories_delete` | 删除门店分类 / 同步默认分类（危险操作；运营/财务默认有，城市门店服务无） |
+| `store_accounts` | 门店账户 |
+| `store_media` | 门店资源 |
+
+存量角色/账号若已有 `stores`，迁移一次性补齐后 5 键（行为与拆分前一致）。新角色不补账户/资源。删除分类键另按「非城市门店服务 + 已有分类权限」补齐。
+
+---
+
+## 3. 城市范围
+
+- 表 `hq_account_city`；空列表且非「城市门店服务」= 全国。
+- 「城市门店服务」保存时必须 ≥1 城；若数据异常无城市，则看不到任何门店。
+- 有范围时：列表/详情/审核/评价/账户/资源均 `Store.cityId IN (...)`；越权 403「无权访问该城市的门店」。
+- 概览 `GET /admin/dashboard/stats|analytics`：按生效权限裁剪指标；有城市范围时只统计负责城市（无「未选城」）。
+- `GET /admin/auth/me` 返回 `cityIds`、`cityScoped`。
+
+---
+
+## 4. 运营改客服修复
+
+1. 短信账号 `loginName` 为空时，编辑提交空字符串不再报「用户名不能为空」（视为不改）。
+2. 切换角色清空账号级权限，避免运营追加的门店等权限带到客服。
+3. 改为「城市门店服务」时若未绑城市则拒绝。
+
+---
+
+## 5. Prisma / SQL
+
+- `HqAdminRole` 增加 `CITY_STORE_SERVICE`
+- `HqPermissionEffect`：`GRANT` / `DENY`；`hq_account_permission.effect`
+- `hq_account_city`
+
+脚本：[`server/dukang-api/prisma/migrate-hq-permissions-v358.sql`](../server/dukang-api/prisma/migrate-hq-permissions-v358.sql)  
+已跑过主脚本的库补删除分类键：[`migrate-hq-permissions-v358-categories-delete.sql`](../server/dukang-api/prisma/migrate-hq-permissions-v358-categories-delete.sql)
+
+---
+
+## 6. API
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET/PUT | `/admin/hq-permissions/accounts/:id` | 返回/保存 `grantKeys`、`denyKeys` |
+| PUT | `/admin/hq-accounts/:id` | 可传 `cityIds`；空 loginName 忽略 |
+| GET | `/admin/auth/me` | `permissionKeys` + `cityIds` + `cityScoped` |
+
+门店相关 HQ 接口加 `HqPermissionGuard` 对应键。
+
+---
+
+## 7. 发版步骤
+
+| 步骤 | 动作 |
+|------|------|
+| 1 | 执行 `migrate-hq-permissions-v358.sql` 或 `prisma db push` |
+| 2 | `pnpm build`（shared-types + API + admin-web） |
+| 3 | 发 `dukang-api` + `admin-web` |
+
+---
+
+## 8. 关键路径
+
+| 域 | 路径 |
+|----|------|
+| 权限目录/公式 | `packages/shared-types/src/hq-permissions.ts` |
+| 生效解析 | `hq-permission.guard.ts` |
+| 账号/城市 | `admin-hq-accounts.service.ts` |
+| 权限页 | `HqPermissionsPage.tsx` |
+| 账户页 | `HqAccountsPage.tsx` |
+| 菜单 | `AdminLayout.tsx` |
+| 门店范围 | `admin-stores.service.ts`、套餐/信息变更审核、评价 |
+
+---
+
+## 9. 验收清单
+
+- [ ] 按用户分配：可追加非角色权限，可取消角色已有权限（撤销后菜单与 API 均不可用）
+- [ ] 短信登录的运营账号改为客服：保存成功；刷新后无运营菜单
+- [ ] 新建「城市门店服务」不选城市无法保存；选城后仅见这些城市的门店/审核/评价
+- [ ] 直链其他城市门店详情/审核 403
+- [ ] 该角色默认无「门店账户」「门店资源」；运营原菜单不变
+- [ ] 超管仍全国、全权限
+- [ ] 分类页可见但不按城过滤；城市门店服务可新增/编辑，无删除与「同步默认分类」
+- [ ] 概览只显示有权限的卡片；城市范围账号仅统计负责城市

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

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

docs/杜康好客-v3编码手册.md

@@ -41,6 +41,10 @@ C 端购酒核销 · 门店扫码核销+打款 · 合伙人拓店履约 · WebAd
 | 合伙人 | 拓店三步→HQ审核→辖区订单/账单 |
 | HQ | 开城/商品/审核/订单/权益/核销/结算/工单 |
 
+**HQ 权限（v3.5.8）**：生效 =（角色 ∪ 追加）− 撤销。城市范围绑在账号上（空=全国；「城市门店服务」必须勾城）。门店 API 按 `cityIds` 强制过滤。城市门店服务可新增分类、不可删除；概览按权限与城市范围裁剪。
+
+**HQ 列表（v3.5.9）**：主表不省略号、可横滑；最左序号；列设置（显隐/顺序）存 `hq_account.list_column_prefs`。门店列表「累计核销好客权益」= 该店 `RedeemRecord.amount` 合计。用户列表双击昵称、离开即保存；列表手机号不脱敏。
+
 ## 5. 验收用例（必过）
 
 **主链路 15 项**：登录、4 SKU、起购、支付+权益、双通道核销、payout、关店不可见、拓店审核、配送完成、退款、T+1/T+30…  

docs/杜康好客-知识库.md

@@ -87,11 +87,12 @@
 |--------|------|
 | 开城 | 城市、合伙人(全城/区域+佣金)、仓库 |
 | 商品 | SKU、上下架、详情模板 |
-| 门店 | 审核、套餐 Tab 直存/审核、合伙人列 |
+| 门店 | 审核、套餐 Tab 直存/审核、合伙人列、累计核销好客权益 |
+| 用户 | 列表手机号明文；双击昵称离开即保存 |
 | 交易 | 订单、权益券、核销记录、推广码+metrics |
 | 财务 | 门店/合伙人/酒厂/物流账单；打款确认 |
 | 工单 | 售后四类型 + 技术支持(ST) + 开发计划 |
-| 系统 | 账号权限、客户端配置、企微机器人/消息推送 |
+| 系统 | 账号权限、客户端配置、企微机器人/消息推送；列表「列设置」按账号保存 |
 | 日志 | HQ/用户/门店/合伙人/企微 |
 
 ## 6. 商品与模板
@@ -140,7 +141,7 @@ HQ 推广码：场景/合伙人绑定/上下线；touch 归因；metrics 四指
 
 ## 16. 系统设置
 
-HQ 账号/角色(`hq-permissions`) · 客户端 `minClientVersion` · 运营告警走企微消息推送(DB Webhook)。
+HQ 账号/角色(`hq-permissions`，生效=(角色∪追加)−撤销；可绑城市；城市门店服务可增分类不可删，概览按权限/城市) · 客户端 `minClientVersion` · 运营告警走企微消息推送(DB Webhook)。
 
 ## 17. 企业微信