137 lines
10 KiB
Markdown
137 lines
10 KiB
Markdown
# 系统经营仪表盘设计与验收说明
|
||
|
||
## 1. 交付目标
|
||
|
||
本轮新增 `PAGE-24 /dashboard`，作为登录并选择工作身份后的默认业务首页。页面采用“日常经营驾驶舱 + 系统运行监控 + 全屏故事巡航”的混合形态，同时遵循以下边界：
|
||
|
||
- 仪表盘是独立权限节点 `dashboard:overview:view`；未授权身份看不到菜单，也不能直接访问接口。
|
||
- 超级管理员默认拥有仪表盘权限；业务身份由“权限与配置”按岗位需要授予。
|
||
- 每个指标仍校验原业务权限和 `GLOBAL / COMPANY / PROJECT` 数据范围，不能因为拥有仪表盘权限而扩大数据可见范围。
|
||
- 金额按币种分别查询，不做跨币种相加。
|
||
- 当前项目没有可靠省市字段，因此不伪造地图点位；地图区域明确显示数据能力说明，后续补齐项目地域主数据后再接真实地图。
|
||
- 大屏使用现有 Vue、TDesign 和 ECharts 实现，不增加不透明的第三方大屏运行时依赖。
|
||
|
||
## 2. 页面形态
|
||
|
||
```text
|
||
┌──────────────────────────────────────────────────────────────────────┐
|
||
│ 系统经营仪表盘 币种[CNY⌄] 刷新数据 进入大屏 │
|
||
├──────────────────────────────────────────────────────────────────────┤
|
||
│ ● 应用正常 ● 数据库正常 ● 文件存储 ● 更新服务 版本/运行时长 │
|
||
├──────────┬──────────┬──────────┬──────────┬──────────┬───────────┤
|
||
│进行中项目│ 合同总额 │ 累计收款 │ 累计付款 │ 待办审批 │ 风险事项 │
|
||
├──────────────────────────────────┬───────────────────────────────────┤
|
||
│ 近六个月资金趋势（收款/付款/开票）│ 项目生命周期分布（环形图） │
|
||
├──────────────────────────────────┼───────────────────────────────────┤
|
||
│ 风险与异常（项目/审批/付款/档案） │ 地域能力区（无真实地域时明确降级）│
|
||
├──────────────────────────────────┴───────────────────────────────────┤
|
||
│ 最近业务活动 │
|
||
└──────────────────────────────────────────────────────────────────────┘
|
||
|
||
全屏巡航：
|
||
┌──────────────────────────────────────────────────────────────────────┐
|
||
│ 系统经营态势 章节 1/3 退出全屏 / Esc │
|
||
├──────────────────────────────────────────────────────────────────────┤
|
||
│ 第一幕：资金态势 → 第二幕：项目进程 → 第三幕：风险与系统健康 │
|
||
│ 每 8 秒自动切换，可手动选择章节；保留真实图表和数据来源说明 │
|
||
└──────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 3. 功能清单与实现方式
|
||
|
||
| 功能 | 最终形态 | 实现方式 |
|
||
| --- | --- | --- |
|
||
| 默认首页 | 超级管理员及已授权身份进入 `/dashboard` | 后端角色工作台地址、前端回退地址和 Logo 返回地址统一使用仪表盘 |
|
||
| 菜单首项 | 左侧菜单第一行“仪表盘” | PAGE-24 路由合同 + `orderNo=1` 单菜单组 |
|
||
| 权限节点 | 可按角色授予 `dashboard:overview:view` | V074 写入权限；超级管理员自动获得角色权限和 GLOBAL scope |
|
||
| 系统状态条 | 应用、数据库、文件存储、更新服务、版本、运行时长 | 后端聚合只返回允许公开的健康摘要，不暴露 Actuator 明细 |
|
||
| 核心指标 | 进行中项目、合同额、收款、付款、待办、风险 | 每项独立检查底层业务权限；无权限时显示不可用状态而不是伪造零值 |
|
||
| 资金趋势 | 最近六个月收款、付款、开票折线/柱形组合图 | 服务端按月、币种、授权范围聚合；ECharts 模块化加载 |
|
||
| 生命周期 | 立项、合同、执行、验收、结算、关闭分布 | 服务端状态分桶；环形图和可跳转明细 |
|
||
| 风险异常 | 项目风险、审批超时、付款阻断、档案缺件、隔离文件 | 复用现有业务口径和权限范围，显示级别、数量和跳转入口 |
|
||
| 地图区域 | 高级视觉容器 + 数据能力说明 | 当前 `available=false`，明确不展示虚假地图；预留地域 DTO |
|
||
| 最近活动 | 最近 8 条业务审计活动 | 使用当前用户审计活动，只返回必要标题、结果和目标路由 |
|
||
| 自动刷新 | 60 秒自动刷新，也可手动刷新 | 页面定时器；离开页面时清理，避免后台重复请求 |
|
||
| 大屏巡航 | 三章节全屏故事模式 | 深色全屏层、8 秒巡航、手动切换、Esc 退出、减少动态效果兼容 |
|
||
| 响应式 | 1920、1440、1366、窄屏均不横向溢出 | 分段网格、弹性卡片、图表 ResizeObserver、窄屏重排 |
|
||
| 图表生命周期 | 主题/尺寸变化后正确重建 | ECharts `ResizeObserver`、销毁 `dispose()`、ARIA 描述 |
|
||
|
||
## 4. 后端接口合同
|
||
|
||
```http
|
||
GET /api/v1/dashboard/overview?currency=CNY
|
||
Permission: dashboard:overview:view
|
||
```
|
||
|
||
响应包含：
|
||
|
||
- `system`：总体状态、版本、运行时长、服务状态列表；
|
||
- `metrics`：六项核心指标，包含 `available` 和目标路由；
|
||
- `trend`：六个月资金趋势及各序列可见性；
|
||
- `lifecycle`：项目阶段分布；
|
||
- `risks`：风险异常列表；
|
||
- `geography`：地域可用性、说明和区域数据；
|
||
- `activities`：最近业务活动。
|
||
|
||
币种首期允许 `CNY / USD / EUR / HKD / JPY / GBP`。非法币种返回 422。接口、OpenAPI、前端 operation 合同保持一一对应。
|
||
|
||
## 5. 状态与异常规则
|
||
|
||
- 首次加载显示骨架屏；刷新时保留已有内容并显示加载状态。
|
||
- 网络或后端失败显示中文错误提示和重试按钮。
|
||
- 指标底层权限不足时只隐藏该指标的真实值与跳转，不影响其他已授权模块。
|
||
- 无趋势数据时显示真实零序列和空态，不构造演示数值。
|
||
- 文件目录不可读写时系统状态显示警告；在线更新关闭时显示“未启用”，不误判为服务宕机。
|
||
- 地域数据未配置时展示明确说明，不加载虚假坐标、地图轮廓或项目点位。
|
||
|
||
## 6. 验收标准
|
||
|
||
### 6.1 权限与路由
|
||
|
||
- PAGE-24 存在于 routes、components、operations 三类合同中。
|
||
- 仪表盘是左侧第一项；无 `dashboard:overview:view` 时菜单不可见、直达返回 403。
|
||
- 业务角色获得该权限后可访问；超级管理员无须额外配置。
|
||
- 超级管理员选择身份、点击文字 Logo、结果页返回首页时均进入 `/dashboard`。
|
||
|
||
### 6.2 数据正确性
|
||
|
||
- 所有查询同时使用当前用户、当前角色、权限码、有效期和数据范围。
|
||
- 没有底层权限的组件返回 `available=false`，不能泄露金额、数量或跳转地址。
|
||
- 金额保留数据库精度并按所选币种返回；不得跨币种合计。
|
||
- 生命周期固定补齐六个阶段；没有数据的阶段返回 0。
|
||
- 非法币种必须返回业务校验错误。
|
||
|
||
### 6.3 视觉与交互
|
||
|
||
- 日常驾驶舱、系统状态条、六个 KPI、两类图表、风险区、地域降级区、活动区完整显示。
|
||
- 大屏支持自动巡航、手动章节切换、按钮退出和 Esc 退出。
|
||
- 1366×768、1440×900、1920×1080 以及 390px 窄屏无页面横向溢出。
|
||
- 图表存在可访问名称，容器变化后正确缩放，路由离开后释放实例。
|
||
- 严重和致命级可访问性问题为 0，浏览器控制台无页面错误。
|
||
|
||
### 6.4 工程门禁
|
||
|
||
- 后端单元测试、架构授权扫描、Maven `verify` 通过。
|
||
- 前端 ESLint、Stylelint、Vue 类型检查、Vitest、生产构建和产物卫生扫描通过。
|
||
- Playwright 全页面回归、PAGE-24 专项、多视口、可访问性和生产产物冒烟通过。
|
||
- OpenAPI 合同检查和 `git diff --check` 通过。
|
||
|
||
## 7. 本轮自验记录
|
||
|
||
| 验收项 | 结果 |
|
||
| --- | --- |
|
||
| 后端 `mvn verify` | 通过；本机无 Docker，Testcontainers 的 MySQL 集成类按项目既有配置跳过 |
|
||
| Dashboard 后端单元测试与 Controller 授权扫描 | 通过 |
|
||
| 前端 ESLint / Stylelint | 通过 |
|
||
| Vitest | 13 个文件、64 项通过 |
|
||
| Vue 类型检查 + release build + dist hygiene | 通过 |
|
||
| PAGE-24 专项 Playwright | 三个桌面视口通过 |
|
||
| PAGE-24 axe / 页面溢出 | 通过 |
|
||
| 全页面 Playwright | 246 项均取得通过证据；三并发全量复跑出现 5 项环境性超时，改为单 worker 逐项复测后 5/5 通过 |
|
||
| release dist 冒烟 | 1 项通过 |
|
||
| OpenAPI / diff whitespace | 通过 |
|
||
|
||
## 8. 后续数据能力
|
||
|
||
地图进入真实交付前需为项目增加规范化地域字段（至少省、市、行政区代码），完成历史数据清洗、权限范围验证和坐标映射。地域字段未完成前继续保持当前降级形态，避免用项目名称、地址自由文本或随机坐标推断业务位置。
|