数据治理看板 Vue3 版
本目录是原数据治理看板的 Vue3 重构版本，可独立开发、测试和构建。项目保持原有接口协议、业务口径、外部页签参数和 1920×1080 大屏布局；上级目录中的 indexV2.html、res/ 与旧版脚本不受影响。
技术栈
| 分类 | 技术 | 当前版本 | 用途 |
|---|---|---|---|
| 视图 | Vue | 3.5.39 | Composition API、<script setup> 与响应式渲染 |
| 状态 | Pinia | 3.0.4 | 筛选、监控、项目详情和穿透状态 |
| 路由 | Vue Router | 5.1.0 | 集团、企业、项目三级哈希路由 |
| 构建 | Vite | 8.1.4 | 开发服务、代理与生产构建 |
| 类型 | TypeScript | 5.9.3 | 严格类型检查与 ViewModel 约束 |
| 图表 | ECharts | 6.1.0 | 柱状图、折线图和 Canvas 渲染 |
| 单元测试 | Vitest | 4.1.10 | Adapter、Store 和纯函数测试 |
| 组件测试 | Vue Test Utils | 2.4.6 | Vue 组件渲染与事件测试 |
| 端到端测试 | Playwright | 1.55.1 | 路由、筛选、接口拦截与大屏截图验证 |
架构概览
项目采用 feature-first 目录，将业务能力、共享基础设施和应用装配分开。页面只读取稳定 ViewModel，不直接兼容接口的 PascalCase/camelCase 字段。
flowchart LR
A[App.vue 与 Router] --> B[页面与布局]
B --> C[页面 composable]
C --> D[特性 Setup Store]
D --> E[特性 API]
E --> F[共享 HTTP Client]
F --> G[同源网关 /qhse_webapi]
G --> H[数据治理接口]
D --> I[Adapter]
I --> J[稳定 ViewModel]
J --> B
B --> K[共享 UI 与图表组件]
目录结构
next/
├─ src/
│ ├─ api/ HTTP 客户端、端点定义和特性 API
│ ├─ assets/styles/next.css Vue3 版本增量样式
│ ├─ components/
│ │ ├─ base/EChart.vue 通用 ECharts 生命周期组件
│ │ └─ features/ 监控和穿透业务展示组件
│ ├─ composables/ 页面生命周期和跨 Store 操作
│ ├─ layouts/DashboardLayout.vue 应用壳层、大屏缩放、筛选和导航
│ ├─ pages/ 集团、企业、项目路由页面
│ ├─ router/index.ts 三级哈希路由与页面懒加载
│ ├─ stores/ 筛选、监控、项目、穿透四个 Setup Store
│ ├─ types/ API、ViewModel 和业务类型
│ ├─ utils/
│ │ ├─ adapters/ 原始接口到 ViewModel 的转换
│ │ ├─ charts/ 各特性的纯图表 option 构造函数
│ │ └─ dashboardConfig.ts 系统、外链和报告文件配置
│ ├─ App.vue 根组件
│ ├─ main.ts Vue、Pinia、Router 和样式入口
│ └─ vite-env.d.ts Vite 环境变量类型声明
├─ e2e/ Playwright 主流程测试
├─ .env.example 环境变量模板
├─ playwright.config.ts E2E 配置
├─ vitest.config.ts 单元和组件测试配置
├─ vite.config.ts 开发服务器与接口代理
└─ package.json 依赖和工程命令
状态边界
| Store | 职责 |
|---|---|
useFilterStore |
system、dimension、allowedSystems 及接口 type/range 映射 |
useMonitoringStore |
集团/企业监控数据、当前单位、加载和错误状态 |
useProjectStore |
项目详情 ViewModel、加载和错误状态 |
useDrilldownStore |
弹窗、指标穿透、动不动报告及各自请求状态 |
useMonitoringPage 和 useProjectPage 监听路由参数及筛选状态。参数变化或组件销毁时会取消旧请求；各 Store 同时使用请求序号，避免失效响应覆盖最新状态。
Adapter 与 ViewModel
monitoringAdapter.ts：集团/企业汇总、单位、项目、指标、趋势和动不动报告。projectAdapter.ts：项目信息与项目指标历史值。drilldownAdapter.ts：集团单位分析和企业项目指标穿透。- 页面模板禁止读取
MetricProjectInfo、ProjectMetrics等原始接口字段。 - 图表 option 由
utils/charts下的纯函数生成，components/base/EChart.vue只管理实例生命周期、更新、尺寸监听和销毁。
页面与参数
| 层级 | 路由 | 主要内容 |
|---|---|---|
| 集团 | #/ |
KPI、重点指标、三率趋势、企业分析、报告与集团指标穿透 |
| 企业 | #/enterprise/:unitId |
企业 KPI、趋势、项目分析和企业指标穿透 |
| 项目 | #/project/:unitId/:projectId |
项目信息、指标历史值和异常状态 |
外部页签参数必须位于哈希前，例如 ?type=1,2#/：
type=1：安全。type=2：质量。type=3：应急。type=1,2：安全和质量。- 未传或值无效：显示全部系统。
本版本严格保留当前界面的 70% 未达标阈值和现有文案；如调整为其他业务口径，需要同步 Adapter、页面文案和测试。
接口约定
接口前缀为 /qhse_webapi/api/DataGovernance：
| 接口 | 用途 |
|---|---|
GetMetricMonitoringSituation |
集团监控 |
GetUnitMetricMonitoringSituation |
企业监控 |
GetGroupMetricAnalysis |
集团指标穿透 |
GetUnitMetricAnalysis |
企业指标穿透 |
GetProjectMonitoringSituation |
项目详情 |
GetGroupMoveReportMetricData |
动不动报告动态指标列 |
GetGroupMetricAnalysisMoveReport |
动不动报告企业数据 |
集团监控请求即使没有单位也必须保留 unitId=。指标穿透参数继续使用后端既有拼写 filed，不要自行更名。
上线率兜底计算口径为：
(已关联项目数 + 预立项项目数) / (主数据项目数 + 预立项项目数 - 申请不用项目数)
环境变量
安装依赖后创建本地配置：
Copy-Item .env.example .env.local
设置浏览器端接口 token：
VITE_QHSE_API_TOKEN=实际令牌
该变量由 Vite 在构建期注入，最终会进入浏览器构建产物，仅适用于当前受控内网部署模式。不要提交真实生产 token。
本地开发
npm install
npm run dev
默认地址：http://127.0.0.1:18081/。
开发服务会把 /qhse_webapi 转发到 https://qhse.cncecoa.com。生产环境也必须配置相同的同源反向代理；应用使用哈希路由，不需要 SPA history fallback。
测试与构建
# Adapter、Store 和组件测试
npm run test
# TypeScript 与 Vue 模板检查
npm run typecheck
# 生产构建
npm run build
# 集团、企业、项目路由和外部页签主流程
npm run test:e2e
本地 Playwright 默认使用系统 Edge 通道，CI 使用标准 Chromium。E2E 通过接口拦截运行，不访问正式数据，并在 1920×1080 视口生成集团页面截图。
构建产物位于 dist/。当前 ECharts 独立懒加载块约 535 kB，Vite 会提示大块告警，但不影响构建和运行。
开发约定
- 新页面放入
pages，页面专属展示组件放入components/features/<name>，跨页面基础能力放入components/base、utils或api。 - Store 使用 Setup Store；异步 action 必须维护 loading、error、取消和竞态保护。
- 接口响应先转换为 ViewModel，页面和共享 UI 不得直接依赖原始字段。
- 页面 composable 负责连接路由、筛选和 Store，并在作用域销毁时清理副作用。
- 通用组件使用 props/emits，不读取业务 Store；弹窗等业务组件留在所属特性。
- 图表统一复用
components/base/EChart.vue，页面不得直接创建或销毁 ECharts 实例。 - 原版模块化 CSS 继续作为视觉基线，Vue3 增量样式只写入
src/assets/styles/next.css。 - 修改后至少执行
npm run test、npm run typecheck和npm run build；涉及路由或交互时还需执行npm run test:e2e。