vue3 升级

2026-07-14 10:56:51 +08:00
parent 25ae6f610c
commit 9d02c0a840
26 changed files with 4456 additions and 0 deletions
@@ -0,0 +1,148 @@
+# 数据治理看板 Vue3 版
+
+本目录是原版数据治理看板的 Vue3 升级版本。原版 `indexV2.html`、`res/` 和 `server.js` 保持不变，Vue3 版可独立开发和构建，并保持既有接口参数、业务口径、外部页签参数和 1920×1080 大屏布局。
+
+## 技术栈
+
+- Vue 3 + TypeScript + Vite：组件化开发、类型检查和静态构建。
+- Pinia：集中管理筛选条件、监控数据、项目详情和穿透弹窗状态。
+- Vue Router：集团、公司、项目三级哈希路由。
+- ECharts：柱状图和折线图按需加载，Canvas 渲染。
+- Vitest：数据适配和业务口径单元测试。
+
+## 项目架构
+
+### 分层关系
+
+```mermaid
+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 响应式刷新页面。页面组件不直接兼容后端字段别名，也不直接持有认证令牌。
+
+### 目录职责
+
+```text
+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/dashboard.ts` 是唯一业务状态入口，主要状态分为：
+
+- 筛选状态：`system`、`dimension`、`allowedSystems`。
+- 监控状态：集团或当前公司的 `monitoring`、`loading`、`error`。
+- 项目状态：`projectData`、`projectLoading`、`projectError`。
+- 穿透状态：`dialog`、`selectedMetric`、`metricAnalysis`、`metricLoading`。
+
+集团和公司监控共用 `loadMonitoring`。新请求开始时会取消旧请求，并通过递增请求序号阻止旧响应覆盖最新筛选结果。项目详情和指标穿透分别使用独立 Action，避免页面组件自行维护请求状态。
+
+### 接口与数据适配
+
+所有接口使用同源前缀 `/qhse_webapi/api/DataGovernance`：
+
+- `GetMetricMonitoringSituation`：集团监控。
+- `GetUnitMetricMonitoringSituation`：公司监控。
+- `GetGroupMetricAnalysis`：集团指标穿透。
+- `GetUnitMetricAnalysis`：公司指标穿透。
+- `GetProjectMonitoringSituation`：项目详情。
+
+集团监控接口要求查询字符串始终包含 `unitId=`，即使值为空也不能省略。`services/http.ts` 因此只过滤 `undefined`，显式空字符串会被保留。
+
+`adapters/dashboard.ts` 负责兼容 PascalCase/camelCase 字段、非法数字、布尔字符串和空数组，并集中维护上线率口径：
+
+```text
+(已关联项目数 + 预立项项目数) / (主数据项目数 + 预立项项目数 - 申请不用项目数)
+```
+
+组件只能读取适配后的 ViewModel。新增或调整接口字段时，应先修改 `types/` 和 `adapters/`，不要在 Vue 模板中增加字段兼容分支。
+
+### 图表与大屏布局
+
+`components/EChart.vue` 统一负责 ECharts 初始化、响应式更新、`ResizeObserver` 监听和 `dispose`。当前只注册柱状图、折线图、网格、图例、提示框和 Canvas 渲染器。
+
+页面按照 1920×1080 设计尺寸渲染，由 `App.vue` 等比缩放到实际窗口。趋势图宽度跟随面板；项目和企业数量较多的柱状图使用动态最小宽度和横向滚动，避免柱体被强制压缩。
+
+### 安全与部署边界
+
+- 浏览器只访问同源 `/qhse_webapi/`，前端构建产物不包含接口 token。
+- 本地 token 仅写入 `.env.local`，由 Vite 开发代理注入。
+- 生产环境由网关反向代理 `https://qhse.cncecoa.com/qhse_webapi` 并注入 token。
+- 网关应配置上游超时、请求 ID 透传、访问日志和 5xx 告警。
+
+## 本地开发
+
+复制 `.env.example` 为 `.env.local`，填写仅供本地代理使用的 `QHSE_API_TOKEN`，然后执行：
+
+```powershell
+npm install
+npm run dev
+```
+
+访问 `http://127.0.0.1:18081/`。外部页签参数仍支持 `?type=1`、`?type=2`、`?type=3` 和 `?type=1,2`。
+
+## 测试
+
+```powershell
+npm run test
+npm run typecheck
+```
+
+当前单元测试重点覆盖接口字段归一化、上线率口径、空数据、非法数字和布尔字符串。页面结构或交互调整后，还需要在浏览器验证集团、公司、项目三级路由以及统计和指标穿透弹窗。
+
+## 构建与部署
+
+```powershell
+npm run build
+```
+
+产物位于 `dist/`，可部署到任意静态 Web 服务。生产环境需要由同源网关代理 `/qhse_webapi/`，并在服务端注入接口 token；token 不进入浏览器构建产物。
+
+建议网关同时配置 12 秒上游超时、请求 ID 透传、访问日志和 5xx 告警。应用采用哈希路由，无需 Web 服务器配置 SPA history fallback。
+
+## 开发约定
+
+- 新接口先在 `config/dashboard.ts` 注册，再通过 `services/http.ts` 请求。
+- 后端响应必须先经过 `adapters/`，页面不得直接依赖原始字段命名。
+- 跨页面状态进入 Pinia；仅组件内部使用的展示状态保留在组件中。
+- 通用展示提取到 `components/`，集团、公司、项目编排保留在 `views/`。
+- 图表必须复用 `EChart.vue`，不要在页面中直接创建实例。
+- 样式优先复用原版 CSS 类；Vue3 增量样式只添加到 `styles/next.css`。
+- 修改后至少执行 `npm run test` 和 `npm run build`。