feat: KPI多粒度目标值补提交 — dashboard API + 前端3视图(目标值月/季/年)

已上线未提交的历史功能(2026-08-17): kpi_target_by_frequency + target_monthly/quarterly/yearly 字段透传
2026-08-20 06:57:13 +08:00
parent bd9c70ea05
commit dd53212bcc
5 changed files with 244 additions and 7 deletions
@@ -0,0 +1,155 @@
+# 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（按此文档）
+数据迁移：开发时一起做（备份先行）
+验收：研学（按验收标准逐条验证，铁律七）
+```