feat: add system operations dashboard

docs/系统经营仪表盘设计与验收说明.md

@@ -0,0 +1,136 @@
+# 系统经营仪表盘设计与验收说明
+
+## 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. 后续数据能力
+
+地图进入真实交付前需为项目增加规范化地域字段（至少省、市、行政区代码），完成历史数据清洗、权限范围验证和坐标映射。地域字段未完成前继续保持当前降级形态，避免用项目名称、地址自由文本或随机坐标推断业务位置。

docs/财务系统开发交付总方案.md

@@ -77,7 +77,7 @@
 | 来源表格校验 | V068 为 14 类 OA 的 33 个 TABLE 字段补齐嵌套类型、必填和文件引用规则；V069 保留 OA-02 v1 历史账户表格契约，避免 v2 字段追溯污染 |
 | PAGE-20 审计 | 增加不可变事件序号、四种稳定排序、URL 查询状态、同排序 CSV 导出、脱敏详情及 OpenAPI `422` 参数门禁 |
 | PAGE-22 在线更新 | 更新源固定为公共 Gitea Latest Release API，默认不使用 Token；“获取版本”只读取最新版本信息，发现新版本后由管理员点击“立即更新”开始下载。下载、验签完成进入 `READY/下载完成` 后显示“立即更新并重启”。安装健康检查成功后页面从 10 秒倒计时自动刷新；刷新、短暂断线或命令响应丢失时恢复状态轮询。后台只写固定结构请求，由 root oneshot 服务验签、验哈希、按配置选择是否调用已有 `mysqldump`、切换和回滚，不接受页面传入地址、Token 或命令 |
-| Release 工程 | `.gitea/workflows/release.yml` 监听严格 SemVer `v*` tag；Maven `revision`、npm、JAR、前后端 SBOM、签名 manifest 与 tag 必须同版本。工作流执行 Java/前端/OpenAPI/Playwright/依赖审计，使用至少 3072 位 RSA 密钥生成并独立验收恰好 9 个资产；先创建不可见草稿、逐项上传并核对名称/大小，最后发布为可被 `/releases/latest` 读取的正式 Release |
+| Release 工程 | `.gitea/workflows/release.yml` 监听严格 SemVer `v*` tag；Maven `revision`、npm、JAR、前后端 SBOM、签名 manifest 与 tag 必须同版本。工作流执行 Java/前端/OpenAPI/Playwright/依赖审计，使用至少 3072 位 RSA 密钥生成并独立验收恰好 10 个资产；先创建不可见草稿、逐项上传并核对名称/大小，最后发布为可被 `/releases/latest` 读取的正式 Release |
 | Linux 32 位 | i386/i486/i586/i686 下载 Java 17 i686 JRE；JRE 元数据和归档均使用仅允许 HTTPS/TLS 1.2 及以上的受限下载器；由于 MySQL 8.4 无对应服务端镜像，要求预置外部 MySQL 8.4.x，curl 安装只开启 `/setup` 向导，数据库密码在浏览器中提交；安装器不安装 MySQL、不运行 MySQL 客户端，点击完成安装后由应用在专用 schema 中执行迁移 |
 | 更新可靠性 | 下载和安装拆为两个持久动作；下载阶段不停止业务服务，安装阶段只接受同版本 `READY` 缓存并重新验签。公共 Gitea 默认不使用 Token；如改接私有镜像，Token 仅从权限为 `0600` 的 root 配置/临时文件读取，不进入 `curl` 参数、页面、状态或日志，且只允许同源 API/资产使用；请求原子领取到持久 `processing`，systemd 限制失败重试；数据库备份默认为 `skip`，只有显式配置 `KAIDI_DB_BACKUP_MODE=mysqldump` 才调用已有工具；新旧版本健康和回滚均有独立门禁，跨来源拒绝、成功、健康回滚、下载失败、备份失败和不安全请求夹具纳入 CI |
 | 阶段口径 | 把“开发前冻结”更新为“R1 开发中”；明确模块级验收与整套 R1 交付是两个层级，避免一页完成后虚报整套系统完成 |