系统经营仪表盘设计与验收说明

1. 交付目标

本轮新增 PAGE-24 /dashboard，作为登录并选择工作身份后的默认业务首页。页面采用“日常经营驾驶舱 + 系统运行监控 + 全屏故事巡航”的混合形态，同时遵循以下边界：

仪表盘是独立权限节点 dashboard:overview:view；未授权身份看不到菜单，也不能直接访问接口。
超级管理员默认拥有仪表盘权限；业务身份由“权限与配置”按岗位需要授予。
每个指标仍校验原业务权限和 GLOBAL / COMPANY / PROJECT 数据范围，不能因为拥有仪表盘权限而扩大数据可见范围。
金额按币种分别查询，不做跨币种相加。
当前项目没有可靠省市字段，因此不伪造地图点位；地图区域明确显示数据能力说明，后续补齐项目地域主数据后再接真实地图。
大屏使用现有 Vue、TDesign 和 ECharts 实现，不增加不透明的第三方大屏运行时依赖。

2. 页面形态

┌──────────────────────────────────────────────────────────────────────┐
│ 系统经营仪表盘              币种[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. 后端接口合同

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. 后续数据能力

地图进入真实交付前需为项目增加规范化地域字段（至少省、市、行政区代码），完成历史数据清洗、权限范围验证和坐标映射。地域字段未完成前继续保持当前降级形态，避免用项目名称、地址自由文本或随机坐标推断业务位置。

10 KiB Raw Permalink Blame History Unescape Escape