DataGovernanceDashboard/next/README.md

# 数据治理看板 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 字段。

```mermaid
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 与图表组件]
```

### 目录结构

```text
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`，不要自行更名。

上线率兜底计算口径为：

```text
(已关联项目数 + 预立项项目数) / (主数据项目数 + 预立项项目数 - 申请不用项目数)
```

## 环境变量

安装依赖后创建本地配置：

```powershell
Copy-Item .env.example .env.local
```

设置浏览器端接口 token：

```dotenv
VITE_QHSE_API_TOKEN=实际令牌
```

该变量由 Vite 在构建期注入，最终会进入浏览器构建产物，仅适用于当前受控内网部署模式。不要提交真实生产 token。

## 本地开发

```powershell
npm install
npm run dev
```

默认地址：<http://127.0.0.1:18081/>。

开发服务会把 `/qhse_webapi` 转发到 `https://qhse.cncecoa.com`。生产环境也必须配置相同的同源反向代理；应用使用哈希路由，不需要 SPA history fallback。

## 测试与构建

```powershell
# 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`。