# 2026-08-11 更新说明：角色工作台 + 后台 UI 优化

> 约定：以后每轮增强都在 `docs/updates/` 下按日期新增一份更新说明。

## 一、角色工作台模块体系（新功能）

工作台首页从「所有人一样」升级为「按角色装载模块」，模块配置存库、后台可视化调整。

- 新表 `xk_role_workbench_widget`：按 `role_id` 配置模块（widget_code / 标题覆盖 / 排序 / 启停）
- 后端 `workbench/layout` 按当前登录角色下发布局，前端按 code 动态挂组件
- 角色管理页新增「工作台模块」配置抽屉：勾选模块、上下排序、保存即生效
- 各角色专属 KPI 摘要接口（轻量 count，与对应列表页同口径）：
  - 医生：今日接诊（待接诊/接诊中/已完成/开方数/有效处方金额，与医生小程序同口径）
  - 药师：待审方总数
  - 业务员/省/市经理：门店录入摘要（近 7 天，复用业务员看板接口）
  - 诊所管理员：今日挂号 + 待发货
  - 订单管理员：平台待发货 / 退款处理中

## 二、超管/系统管理员工作台修正（本次反馈重点）

**问题**：超管看到的是业务员视角的「门店录入」摘要（近 7 天无新录入时全是 0），不是角色判断 bug，而是初版种子把该模块也配给了超管/系统管理员，内容错配。

**修正**：超管/系统管理员换成两个专属模块——

1. **平台总览**（`platform_overview`）：今日订单数、今日营业额（有效商品订单 + 有效挂号，与业务员看板同口径）、今日挂号数、今日新增门店录入，点击直达对应列表页
2. **待办中心**（`todo_center`）：行式待办列表，数量 > 0 高亮，点击直达处理页
   - 待审方 → 审方列表
   - 待审核提现 → 提现审核
   - 待审核门店录入 → 录入审核
   - 待发货订单 / 退款处理中 → 商品订单
   - 全部清零时展示「今日无待办」空态

省/市经理和业务员仍保留「门店录入」摘要（语义匹配）。超管如需再看门店录入，可在「角色管理 → 工作台模块」自助勾回。

## 三、工作台 KPI 组件健壮性（功能性补强）

此前 KPI 卡接口失败或加载中会**整卡消失**（用户感知为「功能坏了」），本次统一收口到 `KpiCard` 外壳：

- 加载中：渲染与统计芯片同形状的骨架占位，无布局跳动
- 失败：显示「数据加载失败 + 重试」，可点击重拉
- 标题栏新增手动刷新按钮（加载时图标旋转）
- 七个 KPI 模块（医生/药师/业务员/诊所/订单/平台总览/待办中心）全部接入

## 四、提现管理页 UI 优化

- 状态列（审核状态/审核结果/打款状态）从素 Tag、裸文本换成带圆点的主题化状态胶囊，颜色走 `--success/--warning/--destructive` 变量，暗色自动适配
- 资金变动金额列去掉写死的 `#52c41a/#ff4d4f`（暗色下刺眼），改主题变量 + 涨跌趋势图标 + 等宽数字
- 列表区外壳与顶部账户卡统一 14px 圆角 + 主题描边
- 四个列表本就走自有封装 `useVbenVxeGrid`，保持不变

## 五、消息中心优化

- **消息列表**：首次加载改为与消息行同布局的 shimmer 骨架屏；「今天/昨天/近 7 天」日期分组滚动吸顶（毛玻璃底）
- **通知详情页**（`/notice/detail/:id`）整页重做：
  - 与收件箱同一套视觉：按消息类型色晕染的氛围渐变 + Hero 卡片 + 主题变量配色，暗色全适配（原来写死 gray/sky 色值）
  - 修复 bug：Markdown 预览原来写死暗色主题，亮色模式下是一块黑底，现在跟随系统亮/暗切换
  - 保留全部逻辑：VIP 站内信解析、未读人员名单、富文本/Markdown 双渲染

## 六、工作台布局重排 + 周期总结分受众（第三轮增强）

### 6.1 超管工作台顶部双列布局

- **平台总览 + 待办中心合并为一张「管理驾驶舱」卡**（`WidgetAdminHub.vue`）：上半是四个总览统计芯片，分隔线下半是待办统计芯片（同视觉，count>0 主色高亮），两个接口并行拉取、共用一个刷新/骨架/重试
- 合并卡放在**快捷入口上方左列（约 58%）**，右列（约 42%）是公告卡，窄屏（<1024px）自动退化为上下堆叠
- 其他角色（布局不含这两个模块）保持原布局不变（快捷入口在顶、公告在底）

### 6.2 公告卡增强（后端零改动）

- 每条公告新增**类型胶囊**：按标题关键词前端推导（维护/停机 → 维护、更新/升级 → 更新、活动/福利 → 活动、默认 → 公告），主题色变量着色
- **点击公告行弹出详情弹层**：`announcement/latest` 本就全量返回 content，前端直接用 premium 风格弹层（光斑 Hero 头 + 富文本正文）展示，暗色全适配

### 6.3 周期总结分受众版本（后端新能力）

原周期总结只发平台管理员、只有平台指标。现在一次 `notice:period-report` 执行推送**五个受众版本**，各自看各自的经营数据：

| 受众 | 接收人 | 指标 |
|---|---|---|
| 平台 | 超管/系统管理员/总部财务 | 活跃门店、挂号、处方（线上/线下、待审/通过/驳回）、临期待审 |
| 诊所 | 诊所管理员（yii_store.type=0） | 本店挂号（总数/已完成）、处方（总数/待审）、结算收入 |
| 药店 | 诊所管理员（yii_store.type=1） | 本店有效订单/营业额、待发货、退款处理中、结算收入 |
| 供应商 | 供应商账号（role 7） | 分账笔数、已结算/待结算金额（yii_ledger user_type=3） |
| 配送仓库 | 仓库管理员（role 16） | 新增/已发/待发包裹（xk_product_order_shipment）、结算收入 |

- 指标全部 `whereIn + groupBy` 批量聚合（`AudienceOpsSummaryService`），不逐店查库
- `action_payload` 新增 `audience` / `subject`（主体 id+名称）字段，旧数据无 audience 按平台版兼容渲染
- crontab 不变，同一条命令自动多受众分发

### 6.4 周期总结详情视图重做（毛玻璃）

`PeriodReportView.vue` 整体重写：

- 按 `audience` 切换五套指标瓷砖配置 + 受众徽标（平台/诊所/药店/供应商/配送仓库），一套模板配置驱动
- 毛玻璃视觉：Hero 区双主色光斑 + `backdrop-filter: blur`，指标瓷砖半透明底 + 磨砂 + 内侧高光细线，warn/ok 色调走 `--warning`/成功色低透明度，暗色全适配
- Markdown 文字摘要收进可折叠玻璃面板（默认收起，指标卡已表达核心信息）

## 七、SQL 与上线步骤

按顺序执行（均幂等，可重复执行）：

1. `sql/20260811/xk_role_workbench_widget.sql` — 建表 + 全角色初版种子
2. `sql/20260811/xk_role_workbench_widget_fix_admin.sql` — 软删超管/系统的门店录入，换上平台总览 + 待办中心

后端无需额外操作（路由自动注册）；前端正常发版即可。

## 涉及文件清单

### xk-api（后端）

| 文件 | 变更 |
|---|---|
| `app/Enum/WorkbenchWidgetEnum.php` | 新增 `platform_overview` / `todo_center` |
| `app/Service/admin/system/WorkbenchService.php` | 新增 `platformOverview()` / `todoCenter()` |
| `app/Http/Controllers/admin/system/WorkbenchController.php` | 新增两个 GET 端点 |
| `app/Service/admin/system/RoleWorkbenchWidgetService.php` | （前轮）角色模块配置 CRUD |
| `app/Service/common/doctor/DoctorWorkbenchStatsService.php` | （前轮）医生统计公共口径 |
| `app/Enum/PeriodReportAudienceEnum.php` | 新增：周期总结受众枚举 |
| `app/Service/common/notice/AudienceOpsSummaryService.php` | 新增：诊所/药店/供应商/仓库指标批量聚合 |
| `app/Service/common/notice/AdminNoticePeriodReportService.php` | 重构：五受众分发，payload 带 audience/subject |
| `app/Console/Commands/NoticePeriodReportCommand.php` | 描述更新（签名不变，crontab 无需调整） |

### xk-admin（前端）

| 文件 | 变更 |
|---|---|
| `views/dashboard/workspace/components/WidgetPlatformOverview.vue` | 新增：平台总览 |
| `views/dashboard/workspace/components/WidgetTodoCenter.vue` | 新增：待办中心 |
| `views/dashboard/workspace/components/KpiCard.vue` | 收口加载骨架/失败重试/手动刷新 |
| `views/dashboard/workspace/components/Widget*.vue`（5 个角色 KPI） | 接入 loading/error/refresh |
| `views/dashboard/workspace/api/index.ts`、`config/widgets.ts` | 新接口 + 组件注册 |
| `views/dashboard/workspace/components/WidgetAdminHub.vue` | 新增：总览+待办合并驾驶舱卡 |
| `views/dashboard/workspace/index.vue` | 顶部双列布局（左驾驶舱右公告） |
| `views/dashboard/workspace/components/WidgetNotice.vue` | 类型胶囊 + 点击弹公告详情 |
| `views/notice/views/PeriodReportView.vue` | 重写：五受众配置 + 毛玻璃视觉 |
| `views/finance/withdrawal/index.vue` | 状态胶囊 + 暗色修复 + 列表壳统一 |
| `views/notice/index.vue` | 骨架屏 + 粘性日期分组 |
| `views/notice/compoents/detail.vue` | 整页重做 + MdPreview 主题跟随修复 |

### sql

| 文件 | 变更 |
|---|---|
| `20260811/xk_role_workbench_widget.sql` | （前轮）建表 + 初版种子 |
| `20260811/xk_role_workbench_widget_fix_admin.sql` | 新增：超管/系统模块修正 |
| `z_xk数据结构.sql` | （前轮）同步新表结构 |
