cma-management/architecture/epic2-plan.md

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