# CMA Epic 2 — KPI数据分析增强和驾驶舱优化
> 技术方案 v1.0 | 2026-06-13

## 一、现状分析

### 现有系统状态
- **后端**: FastAPI @ 127.0.0.1:8010，运行正常
- **数据库**: cma.db，18个活跃KPI，4个维度（finance:8, customer:3, process:3, learning:4）
- **预警**: 16个待处理预警
- **Dashboard.vue**: CEO/Finance/Business/IT四角色视图，已有KPI矩阵、预测、简报等功能
- **MyDashboard.vue**: PDCA管理闭环、趋势柱状图
- **deviation_engine.py**: 已有同比/环比计算基础函数（calc_period_diff），但未被dashboard API集成
- **ai_analysis.py**: 已集成DeepSeek API做CEO简报和KPI分析

### 待开发功能
1. **同比环比趋势分析** — deviation_engine.py已有calc_period_diff，需集成到dashboard API
2. **预警趋势统计** — 按等级/维度/时间的统计API
3. **KPI数据导出CSV** — 导出功能
4. **驾驶舱KPI增强** — 增加trend字段和achievement_rate
5. **Dashboard.vue趋势分析tab** — ECharts折线图
6. **Dashboard.vue预警统计卡片** — 饼图+趋势线
7. **Dashboard.vue达成率进度条** — 已有简单进度条，增强可视化

## 二、后端新增API

### 1. KPI同比环比趋势分析
```
POST /api/cma/dashboard/trend-analysis
参数: kpi_ids (list[int]), period_type (month/quarter/year), compare_type (yoy/mom)
返回: {
  data: [{
    kpi_id, kpi_code, kpi_name, unit,
    current_value, current_period,
    previous_value, previous_period,
    change_rate,          # 变化率(%)
    change_amount,        # 变化额
    trend_direction,      # up/down/stable
    dimension
  }]
}
```

### 2. 预警趋势统计
```
GET /api/cma/dashboard/alert-stats
参数: period (month/quarter/year)
返回: {
  total_pending: N,
  by_severity: { red: N, yellow: N, green: N },
  by_dimension: [{ dimension, count }],
  trend_by_month: [{ month, red, yellow, green }]
}
```

### 3. KPI数据导出CSV
```
GET /api/cma/dashboard/export
参数: kpi_ids (comma-separated), period
返回: CSV文件流 (Content-Type: text/csv)
```

### 4. 驾驶舱KPI增强（修改现有get_dashboard_kpis）
- 每个KPI增加 `trend` 字段（最近3期环比变化率）
- 增加 `achievement_rate` 字段（actual_value / target_value）
- 增加 `period_values` 数组（最近6期数据，供前端画趋势图）

## 三、前端改造

### Dashboard.vue 增强（CEO视图）
1. **趋势分析标签页** — ECharts折线图，支持同比/环比切换
2. **预警统计卡片** — 饼图(severity分布) + 趋势折线
3. **KPI卡片增强** — 达成率百分比 + 彩色进度条 + 趋势箭头
4. **数据导出按钮** — 调用export API下载CSV

### 前端API扩展
在 `/frontend/src/api/index.ts` 的 `dashboardApi` 中增加：
- `trendAnalysis: (params) => api.post('/dashboard/trend-analysis', params)`
- `alertStats: (params) => api.get('/dashboard/alert-stats', { params })`
- `exportKpis: (params) => api.get('/dashboard/export', { params, responseType: 'blob' })`

## 四、执行顺序

```
Step 1 (并行):     Backend → 趋势分析API + 预警统计API + 导出API
                   Frontend → API扩展定义（与后端同步）
Step 2 (串行, 依赖Step1): Frontend → Dashboard.vue改造
Step 3 (串行, 依赖Step2): DevOps → 部署重启
Step 4 (串行, 依赖Step3): QA → 全流程验证
```

## 五、依赖关系

- trend-analysis API: 可直接复用deviation_engine.py的calc_period_diff
- alert-stats API: 可直接从KPIAlert表聚合统计
- export API: 无依赖
- Dashboard.vue趋势tab: 依赖Step1的API