Hermes CI Fix
dd53212bcc
已上线未提交的历史功能(2026-08-17): kpi_target_by_frequency + target_monthly/quarterly/yearly 字段透传
156 lines
5.8 KiB
Markdown
156 lines
5.8 KiB
Markdown
# 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（按此文档）
|
||
数据迁移：开发时一起做（备份先行）
|
||
验收：研学（按验收标准逐条验证，铁律七）
|
||
```
|