feat: 优化了若干接口页面，可用性存疑

2026-08-12 08:57:15 +08:00
parent 6db736a6f4
commit f622743661
67 changed files with 8729 additions and 1133 deletions
--- a/docs/updates/20260811-个人中心.md
+++ b/docs/updates/20260811-个人中心.md
@@ -0,0 +1,28 @@
+# 2026-08-11 更新说明：个人中心（PC）
+
+## 一、功能概述
+
+顶栏头像下拉的「个人中心」此前指向 Vben 模板假数据页，本次重做为真实功能页，并在工作台新增入口。
+
+- **基本资料 tab**：头像（复用表单 Avatar 上传组件，走 `upload/image`）+ 昵称可编辑；登录账号 / 手机号 / 角色 / 所属门店 / 工号 / 最后登录等只读展示（身份信息不允许自助修改）
+- **修改密码 tab**：复用顶栏「修改密码」弹窗同一份表单 schema（`layouts/config/form.ts` 的 `passwordModalForm`）与同一个接口（`admin/update-password`），两个入口口径完全一致
+- 保存资料成功后后端同步刷新 Redis 会话，前端重拉 `auth/my-info`，顶栏与工作台头像昵称立即生效
+
+## 二、入口
+
+1. 顶栏头像下拉「个人中心」（已有，指向静态路由 `/profile`，不走 `xk_menu`）
+2. 工作台问候头：头像/姓名区域整块可点击（hover 反馈），铃铛旁新增「个人中心」圆形图标按钮（`lucide:user`，同 bell 样式）
+
+## 三、涉及文件
+
+- 重做 `views/_core/profile/index.vue`：左侧账号卡（头像/昵称/角色）+ 右侧 tab 容器，资料统一从 `auth/my-profile` 实时接口拉取；删除模板假 tab「安全设置」「新消息提醒」（连同 `security-setting.vue`、`notification-setting.vue`）
+- 重写 `views/_core/profile/base-setting.vue`：`useVbenForm`（Avatar + VbenInput）+ 只读信息栅格（主题变量适配暗色）
+- 重写 `views/_core/profile/password-setting.vue`：复用 `passwordModalForm` schema + `views/system/admin/api` 的 `updatePassword`
+- 新建 `views/_core/profile/api/index.ts`：`getMyProfile` / `updateMyProfile`（后端 `auth/my-profile`、`auth/update-my-profile`）
+- 修改 `views/dashboard/workspace/components/WorkspaceHeader.vue`：左侧区域可点 + 右侧个人中心按钮，颜色全走主题变量
+
+## 四、后端配套（xk-api）
+
+- 新增 `app/Service/common/profile/AdminProfileService.php`（五端共用：PC + 四个小程序管理端）
+- `AdminController` 加 `myProfile` / `updateMyProfile`，`routes/admin.php` auth 分组注册
+- 详细见 `sql/doc/0811-个人中心.md`
--- a/docs/updates/20260811-工作台与UI优化.md
+++ b/docs/updates/20260811-工作台与UI优化.md
@@ -0,0 +1,144 @@
+# 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` | （前轮）同步新表结构 |
--- a/docs/updates/20260812-日历待办与VIP质感.md
+++ b/docs/updates/20260812-日历待办与VIP质感.md
@@ -0,0 +1,55 @@
+# 20260812 更新：日程日历（待办 + 提醒）与 VIP 组件黑金质感
+
+## 一、日程日历页（新增）
+
+菜单：「概览」组下「日程日历」（`/calendar`，name `WorkCalendar`，component `/dashboard/calendar/index`，SQL 见 sql 仓库 `20260812/xk_calendar_todo.sql`）。
+
+### 目录结构
+
+```
+views/dashboard/calendar/
+├── index.vue                    # 日历页（自定义头部 + antd Calendar + 右键菜单）
+├── api/index.ts                 # calendar-todo CRUD API
+├── config/
+│   ├── constants.ts             # 提醒渠道选项（notice/email/sms）
+│   └── form.ts                  # 待办弹窗表单 schema（级联显隐）
+├── components/
+│   ├── todo-modal.vue           # 新建/编辑待办弹窗（含删除）
+│   └── day-todos-modal.vue      # 当日待办列表弹窗（勾选完成/编辑/删除）
+└── utils/almanac.ts             # 黄历计算封装（lunar-typescript，带缓存）
+```
+
+### 功能点
+
+- **黄历**：农历（初一显示月名）、二十四节气、节日、法定调休「休/班」徽标；格子副标题按 节日 > 节气 > 农历日 择优展示，多个节日 Tooltip 全量提示
+  - 中国传统节日（春节/端午/中秋…）按农历推算；国际节日（元旦/圣诞/母亲节…）按公历——由 `lunar-typescript` 内置数据支持（新增依赖）
+- **右键菜单**：任意格子右键 → 新建待办 / 查看当日待办（Teleport 到 body，贴边自动内收，点击/滚动关闭）
+- **待办**：格子内直接显示前 3 条（完成划线），超出显示「还有 N 项」；hover 格子出现快捷「+」
+- **详情备注为 Markdown**：编辑用新封装的 `MarkdownEditor` 表单组件（`components/form/components/markdown-editor.vue`，自动注册、全项目可复用：精简工具栏 + 主题跟随亮暗），弹窗放宽到 640px；站内信提醒以 `edit_type=1` 发送、消息详情 MdPreview 渲染，邮件提醒后端转 HTML
+- **提醒**：待办可设提醒时间 + 多选渠道（站内信/邮箱/短信），表单级联显隐（选邮箱/短信渠道时出现收件人输入，不填回落个人资料）；后端每分钟扫描发送
+- **头部**：公历年月 + 农历干支生肖年、图例、上月/今天/下月、新建待办
+- 全部配色走 `hsl(var(--xxx))` 主题变量，暗色模式自动适配
+
+### 新依赖
+
+- `lunar-typescript@1.8.6`（农历/节气/节假日计算，纯 TS 无副作用）
+
+## 二、VIP 组件黑金质感升级
+
+旧版蓝绿渐变卡面（#2c3e50 → #6acdbb）统一升级为「黑金贵宾卡」视觉：深色曜石渐变底 + 右上暗金光晕 + 斜切流光 + 金色描边 + 香槟金文字。深色卡面亮/暗主题通用，删除了原 `.dark` 渐变分支。
+
+| 组件 | 改动 |
+| --- | --- |
+| `components/vip/StoreVipMemberCard.vue` | 诊所设置会员卡：黑金卡面 + glow/sheen 装饰层，期限改金字胶囊并入标题行 |
+| `components/vip/HeaderVipBadge.vue` | 顶栏 VIP 气泡卡头图：黑金化 + glow，期限胶囊化 |
+| `components/vip/VipUpgradeModal.vue` | 开通/升级弹窗预览卡：黑金化 + glow |
+
+`VipHubModal` / `VipStoreRecordsModal` / `StoreVipCell`（主题变量）与 `VipBadgeCombo`（纯图片）/ `VipGate`（纯逻辑）无需调整。
+
+小程序端（xk-doctor-wx）同步升级：`vip-member-card.vue`（我的页会员卡）与 `my/vip-detail.vue`（会员详情头卡）同款黑金视觉。
+
+## 三、后端接口（xk-api）
+
+- `GET calendar-todo/get-list?start_time&end_time`：按范围查本人待办
+- `POST calendar-todo/create|update|delete|toggle-done`
+- 提醒调度：`calendar:todo-remind` 每分钟（routes/console.php）；短信模板需配 `SMS_TODO_REMIND_TEMPLATE_ID`，邮箱需配 SMTP