cma-management/docs/req-kpi-target-multi-granularity.md

KPI目标值多粒度改造（月/季/年分离）

需求提出：2026-08-17 | 提出人：任总（工作台使用中发现混淆） 文档版本：v1.0 | 状态：待评审 类型：后端改表 + 前端改造 + 数据清洗

一、问题描述

用户故事

作为CMA系统的操作人员，我在工作台看到"目标 1200"时，无法判断这个目标是月度、季度还是年度；当我点击进入KPI详情调整目标值时，不知道该改的是月目标、季目标还是年目标——系统只有一个单值 target_value，三个周期的目标混在一起，必然造成操作混淆。

现状痛点

① KPI定义的frequency字段：monthly 63个 / quarterly 11个 / weekly 2个 / half_year 10个
   → 定义了"考核频率"，但target_value是单值，没说清对应哪个周期

② target_value单值无法表达多周期目标：
   同一KPI（如F_REVENUE营收）：
     frequency=quarterly（季度考核）
     target_value=1200（单值）
     kpi_values.period=2026.06（月度数据！）
   → 1200到底是月目标？季目标？年度目标？三个信息互相矛盾

③ period格式混乱：
   2026.06 / 2025.1（缺零）/ 2026H1 / 2026-06 / 2021（年）
   → 前端排序、环比计算、图表展示不可靠

核心矛盾

考核频率（月/季/年）× 目标值（单值）× 实际数据周期（混合格式）
    ↓
三者不对齐 = 数据粒度不匹配 = 使用者必然混淆

二、解决方案

方案总览：目标值分级 + period格式化

① 数据库：kpi_definitions 增加三列
   target_monthly / target_quarterly / target_yearly

② 数据迁移：现有target_value按frequency归入对应列

③ 前端显示：按frequency显示对应目标值 + 周期标签

④ period格式统一：kpi_values.period 标准化为 YYYY-MM / YYYY-Qn / YYYY

三、功能列表

后端（backend）

• 1. kpi_definitions 表加3列（target_monthly / target_quarterly / target_yearly，decimal(15,2) 可空）
• 2. 数据迁移脚本：UPDATE ... SET target_monthly=target_value WHERE frequency='monthly'（quarterly/yearly同理）；weekly/half_year归入最接近周期（weekly→monthly，half_year→quarterly）并记录
• 3. API改造：KPI详情/列表接口返回 target_monthly、target_quarterly、target_yearly + frequency
• 4. 前端保存KPI时，按frequency写入对应目标列（如frequency=monthly则写target_monthly）
• 5. 新增period标准化工具脚本（清洗历史数据）

前端（frontend）

• 6. 工作台KPI卡：目标值旁显示周期标签"目标(月)"/"目标(季)"/"目标(年)"
• 7. KPI详情页"目标值"编辑：显示当前frequency对应的目标字段，明确标注周期
• 8. 历史数据tab：period统一展示格式（YYYY-MM）

数据（data）

• 9. 清洗kpi_values.period历史数据（2025.1→2025-01，2026H1→2026-H1，等）

四、数据流

展示流：
工作台/详情页 GET /kpis/:id
  → 返回 kpi + target_monthly/quarterly/yearly + frequency
  → 前端按frequency取对应目标值
  → 显示"目标(月): 18%" 或 "目标(季): 1200"

编辑流：
用户在详情页改目标值
  → 前端按frequency路由到对应字段（monthly→target_monthly）
  → PUT /kpis/:id { target_monthly: 20 }
  → 后端只更新该列，其他周期目标不受影响

五、界面设计

工作台KPI卡（改动）

┌─────────────────────────────────┐
│ 毛利率             [达标]        │
│ 18.5%   目标(月): 18%           │ ← 加频率标签
│ ████████████░░░░░               │
└─────────────────────────────────┘

KPI详情页-基本信息（改动）

目标值(月度): [ 18 ] %    ← frequency=monthly时显示这个
目标值(季度): [     ]     ← 季度目标可另行填写
目标值(年度): [     ]     ← 年度目标可另行填写

六、验收标准

1. 工作台KPI卡显示带周期标签的目标值（如"目标(月): 18%"）
2. 月度KPI改目标只改target_monthly，季度/年度目标不受影响
3. frequency=quarterly的KPI（如F_REVENUE）工作台显示季度目标
4. kpi_values.period全部为标准格式（无2025.1、2026H1等异常格式）
5. 数据迁移后：原monthly的target_value已迁入target_monthly，无丢失
6. 一致性检查通过（consistency-check不报新错误）

七、工作量评估

项	内容	人天
后端	加列+迁移脚本+API改造	0.5
前端	工作台标签+详情页多周期目标	0.5
数据	period清洗脚本+执行	0.3
测试	验收用例（多frequency验证）	0.2
合计		1.5天

八、关联模块

• 工作台（MyDashboard.vue）—— KPI卡显示
• KPI详情页（KPIDetail.vue）—— 目标值编辑
• KPI字典列表（KPIList.vue）—— 列表目标值列
• kpis.py API —— 目标值读写
• dashboard.py API —— my-dashboard返回
• 与"科目≠KPI"规范（kpi-account-governance-rule.md）配套：本需求解决"时间粒度"，前者解决"类型混用"

九、风险与注意

⚠️ 迁移不可逆：先备份kpi_definitions表（参考2026-08-17备份流程）
⚠️ weekly/half_year归并需人工确认映射规则
⚠️ period清洗会影响历史报表展示，需回归测试
⚠️ 前端所有"目标值"引用点需全局搜索（不止工作台和详情页）

十、执行分工建议

方案评审：研学（已分析）
需求文档：研学（本文档）
开发实施：项目Bot或全栈Bot（按此文档）
数据迁移：开发时一起做（备份先行）
验收：研学（按验收标准逐条验证，铁律七）