7.8 KiB
数据治理看板 Vue3 版
本目录是原版数据治理看板的 Vue3 升级版本。原版 indexV2.html、res/ 和 server.js 保持不变，Vue3 版可独立开发和构建，并保持既有接口参数、业务口径、外部页签参数和 1920×1080 大屏布局。
技术栈
- Vue 3 + TypeScript + Vite：组件化开发、类型检查和静态构建。
- Pinia：集中管理筛选条件、监控数据、项目详情和穿透弹窗状态。
- Vue Router：集团、公司、项目三级哈希路由。
- ECharts：柱状图和折线图按需加载，Canvas 渲染。
- Vitest：数据适配和业务口径单元测试。
项目架构
分层关系
flowchart LR
A[App 应用壳层] --> B[Router 路由页面]
B --> C[Pinia Dashboard Store]
C --> D[HTTP Service]
D --> E[同源网关 /qhse_webapi]
E --> F[数据治理接口]
C --> G[Adapter 数据适配]
G --> H[稳定 ViewModel]
H --> B
B --> I[业务组件]
I --> J[ECharts 生命周期组件]
数据读取遵循单向链路：页面触发 Store Action，Service 请求接口，Adapter 将原始响应转换为 ViewModel，Store 更新状态后由 Vue 响应式刷新页面。页面组件不直接兼容后端字段别名，也不直接持有认证令牌。
目录职责
next/
├─ src/
│ ├─ adapters/ 接口原始数据到 ViewModel 的转换及口径测试
│ ├─ components/ KPI、指标列表、ECharts 和全局穿透弹窗
│ ├─ config/ 接口路径、外链、系统枚举和报告文件映射
│ ├─ router/ 集团、公司、项目三级路由
│ ├─ services/ 请求参数、超时、取消、请求 ID 和错误处理
│ ├─ stores/ 筛选、监控数据、项目数据和弹窗状态
│ ├─ styles/ Vue3 版增量样式
│ ├─ types/ API、ViewModel、筛选和弹窗类型
│ ├─ views/ 集团级、公司级、项目级页面
│ ├─ App.vue 大屏壳层、筛选、面包屑和缩放
│ └─ main.ts Vue、Pinia、Router 和样式入口
├─ vite.config.ts 开发服务器和接口代理
├─ tsconfig.json TypeScript 配置
└─ package.json 依赖和工程命令
main.ts 会引入上级 res/css/ 中的原版模块化样式作为视觉基线，Vite 构建时会将这些 CSS 合并进 dist/assets/。Vue3 专属修正放在 src/styles/next.css，禁止修改或重新聚合原版 CSS 文件。
页面与路由
| 层级 | 路由 | 页面职责 |
|---|---|---|
| 集团级 | #/ |
集团 KPI、重点指标、三率趋势、企业分析、报告入口、指标穿透 |
| 公司级 | #/enterprise/:unitId |
公司 KPI、三率趋势、项目分析、公司指标穿透 |
| 项目级 | #/project/:unitId/:projectId |
项目信息、指标历史值、异常状态 |
外部系统的页签参数位于哈希前，例如 ?type=1,2#/。参数映射保持原规则：1 为安全、2 为质量、3 为应急；未传或传入非法值时展示全部系统。
状态管理
stores/dashboardStore.ts 是唯一业务状态入口，主要状态分为：
- 筛选状态：
system、dimension、allowedSystems。 - 监控状态：集团或当前公司的
monitoring、loading、error。 - 项目状态：
projectData、projectLoading、projectError。 - 穿透状态：
dialog、selectedMetric、metricAnalysis、metricLoading。 - 指标列表弹窗：集团和企业复用
allMetrics，使用率低于 70% 的指标显示红色告警卡片。 - 动不动报告状态：
moveReport、moveReportLoading、moveReportError。
集团和公司监控共用 loadMonitoring。新请求开始时会取消旧请求，并通过递增请求序号阻止旧响应覆盖最新筛选结果。项目详情和指标穿透分别使用独立 Action，避免页面组件自行维护请求状态。
接口与数据适配
所有接口使用同源前缀 /qhse_webapi/api/DataGovernance：
GetMetricMonitoringSituation：集团监控。GetUnitMetricMonitoringSituation：公司监控。GetGroupMetricAnalysis：集团指标穿透。GetGroupMoveReportMetricData：动不动报告动态指标列，type=0/1分别对应安全/质量。GetGroupMetricAnalysisMoveReport：动不动报告企业行，range=0/1分别对应所有项目/新开工项目。GetUnitMetricAnalysis：公司指标穿透。GetProjectMonitoringSituation：项目详情。
集团监控接口要求查询字符串始终包含 unitId=，即使值为空也不能省略。services/http.ts 因此只过滤 undefined，显式空字符串会被保留。
adapters/dashboardAdapter.ts 负责兼容 PascalCase/camelCase 字段、非法数字、布尔字符串和空数组，并集中维护上线率口径：
(已关联项目数 + 预立项项目数) / (主数据项目数 + 预立项项目数 - 申请不用项目数)
组件只能读取适配后的 ViewModel。新增或调整接口字段时，应先修改 types/ 和 adapters/，不要在 Vue 模板中增加字段兼容分支。
动不动报告由两个接口共同组成：指标定义接口决定动态列顺序和中文名称，企业行接口通过 MetricAnalysis[].Field 绑定每列使用率。若指标定义接口临时返回空字段，适配层会使用当前监控接口的指标名称兜底，并对重复 Field 去重，避免生成空表头或重复列。
图表与大屏布局
components/EChart.vue 统一负责 ECharts 初始化、响应式更新、ResizeObserver 监听和 dispose。当前只注册柱状图、折线图、网格、图例、提示框和 Canvas 渲染器。
页面按照 1920×1080 设计尺寸渲染，由 App.vue 等比缩放到实际窗口。趋势图宽度跟随面板；项目和企业数量较多的柱状图使用动态最小宽度和横向滚动，避免柱体被强制压缩。
安全与部署边界
- 浏览器只访问同源
/qhse_webapi/，由开发服务器或生产网关转发到正式接口。 - 接口 token 固定在
config/dashboardConfig.ts，由services/http.ts写入每个请求的token请求头。 - token 会进入浏览器构建产物，只适用于当前受控内网部署环境。
- 生产环境仍需将
/qhse_webapi/反向代理到https://qhse.cncecoa.com/qhse_webapi，但无需在网关重复注入 token。 - 网关应配置上游超时、请求 ID 透传、访问日志和 5xx 告警。
本地开发
npm install
npm run dev
访问 http://127.0.0.1:18081/。外部页签参数仍支持 ?type=1、?type=2、?type=3 和 ?type=1,2。
测试
npm run test
npm run typecheck
当前单元测试重点覆盖接口字段归一化、上线率口径、空数据、非法数字和布尔字符串。页面结构或交互调整后，还需要在浏览器验证集团、公司、项目三级路由以及统计和指标穿透弹窗。
构建与部署
npm run build
产物位于 dist/，可部署到静态 Web 服务。生产环境需要由同源网关代理 /qhse_webapi/；token 已由前端请求头携带。
建议网关同时配置 12 秒上游超时、请求 ID 透传、访问日志和 5xx 告警。应用采用哈希路由，无需 Web 服务器配置 SPA history fallback。
开发约定
- 新接口先在
config/dashboardConfig.ts注册，再通过services/http.ts请求。 - 后端响应必须先经过
adapters/，页面不得直接依赖原始字段命名。 - 跨页面状态进入 Pinia；仅组件内部使用的展示状态保留在组件中。
- 通用展示提取到
components/，集团、公司、项目编排保留在views/。 - 图表必须复用
EChart.vue，不要在页面中直接创建实例。 - 样式优先复用原版 CSS 类；Vue3 增量样式只添加到
styles/next.css。 - 修改后至少执行
npm run test和npm run build。