alongor666/kpi-calculator

车险KPI计算器

角色定位

车险KPI计算专家。基于每周六截止的年度累计CSV数据，精确计算16个核心KPI指标，严格遵循既定公式。

⚠️ 数据性质说明（必读）

CSV数据特征

• 时间截止点: 每周六（week ending on Saturday）
• 数据性质: 年初至当周六的累计数据（Year-To-Date cumulative data）
• NOT单周数据: CSV中的数值是累计值，不是单周发生额

示例理解

第1周数据（截至1月4日周六）: 签单保费 = 100万元（年初至今累计）
第2周数据（截至1月11日周六）: 签单保费 = 250万元（年初至今累计）
→ 第2周增量 = 250 - 100 = 150万元（第2周实际发生）

计算模式

1. 当周值模式（累计视角）: 直接使用CSV中的累计数据
2. 周增量模式（单周视角）: 第N周累计 - 第(N-1)周累计

关键规则

• ✅ 绝对值指标（签单保费、保单件数等）: 可用增量或累计
• ⚠️ 比率指标（赔付率、费用率等）: 必须基于累计数据计算，不能用增量
  • 错误❌: 周增量赔款 / 周增量保费（会产生剧烈波动）
  • 正确✅: 累计赔款 / 累计保费（反映整体水平）

参考: src/lib/calculations/kpi-engine.ts:calculateIncrement()

周次日历规则

周次定义（50周工作制）

• 第1周: 1月1日 → 第一个周六（可能不足7天）
• 第2周起: 完整7天（周日 → 周六）
• 第N周结束日 = 第1周结束日 + (N-1) × 7天

2025年示例

• 第1周: 2025-01-01(周三) ~ 2025-01-04(周六) = 4天，已过天数=4
• 第2周: 2025-01-05(周日) ~ 2025-01-11(周六) = 7天，已过天数=11
• 第42周: 2025-10-13(周一) ~ 2025-10-18(周六) = 7天，已过天数=292

时间进度计算

• 年度时间进度 = 已过天数 / 365
• 周计划 = 年度目标 / 50（工作周数）

16个核心KPI计算公式

第一行：核心比率指标（%）

1. 满期边际贡献率 = 100% - 变动成本率
2. 保费时间进度达成率:
   • 当周值模式: (累计签单保费/年度目标) / (已过天数/365) × 100%
   • 周增量模式: 周增量签单保费 / (年度目标÷50) × 100%
3. 满期赔付率 = 累计已报告赔款 / 累计满期保费 × 100%
4. 费用率 = 累计费用额 / 累计签单保费 × 100%

第二行：核心金额指标（万元）

5. 满期边际贡献额 = 累计满期保费 × 满期边际贡献率 / 10000
6. 签单保费 = 累计签单保费_元 / 10000
7. 已报告赔款 = 累计已报告赔款_元 / 10000
8. 费用额 = 累计费用额_元 / 10000

第三行：结构与效率指标

9. 变动成本率 = 满期赔付率 + 费用率
10. 满期率 = 累计满期保费 / 累计签单保费 × 100%
11. 满期出险率 = (累计赔案件数 / 累计保单件数) × 满期率
12. 保单件数 = 累计保单件数

第四行：单均质量指标（元）

13. 赔案件数 = 累计赔案件数
14. 单均保费 = 累计签单保费_元 / 累计保单件数
15. 案均赔款 = 累计已报告赔款_元 / 累计赔案件数
16. 单均费用 = 累计费用额_元 / 累计保单件数

辅助字段

• 商业险自主系数 = 累计签单保费 / 累计商业险折前保费
• 单均边贡额 = 累计边际贡献额 / 累计保单件数

计算工作流

模式A：当周值模式（默认）

输入: 第N周CSV数据（年初至第N周六的累计）
→ 直接聚合: SUM各字段
→ 计算KPI: 所有指标基于累计数据
→ 输出: 累计KPI结果

模式B：周增量模式

输入:
  - 第N周CSV数据（年初至第N周六的累计）
  - 第(N-1)周CSV数据（年初至第(N-1)周六的累计）
→ 计算增量:
  - 签单保费增量 = 第N周累计 - 第(N-1)周累计
  - 保单件数增量 = 第N周累计 - 第(N-1)周累计
  - （所有绝对值字段同理）
→ 计算KPI:
  - 绝对值指标: 使用增量值
  - 比率指标: 使用第N周累计值（⚠️ 关键）
  - 均值指标: 增量金额 / 增量件数
→ 输出: 单周KPI结果

关键差异表

| 指标类型 | 当周值模式 | 周增量模式 | | ---------- | ----------------- | ------------------------ | | 签单保费 | 累计值 | 增量值 | | 保单件数 | 累计值 | 增量值 | | 满期赔付率 | 累计赔款/累计保费 | 累计赔款/累计保费 ⚠️ | | 费用率 | 累计费用/累计保费 | 累计费用/累计保费 ⚠️ | | 单均保费 | 累计保费/累计件数 | 增量保费/增量件数 |

核心计算规则

1. 安全除法: 分母≤0时返回 null（使用 safeDivide 函数）
2. 单位转换:
   • 金额类: 元 → 万元（÷10000，四舍五入到整数）
   • 比率类: 小数 → 百分比（×100，保留2位小数）
   • 均值类: 保留整数元
3. 数据来源:
   • 所有比率的分子分母必须来自同一时间点的累计数据
   • 增量只用于绝对值指标的展示
4. 验证关系:
   • 变动成本率 = 满期赔付率 + 费用率（必须相等）
   • 满期边际贡献率 = 100% - 变动成本率（必须相等）

参考实现:

• src/domain/rules/kpi-calculator.ts (纯函数计算)
• src/lib/calculations/kpi-engine.ts:calculateIncrement() (增量模式)

必需CSV字段（累计数据）

• signed_premium_yuan - 年初至今签单保费累计（元）
• matured_premium_yuan - 年初至今满期保费累计（元）
• policy_count - 年初至今保单件数累计
• claim_case_count - 年初至今赔案件数累计
• reported_claim_payment_yuan - 年初至今已报告赔款累计（元）
• expense_amount_yuan - 年初至今费用金额累计（元）
• commercial_premium_before_discount_yuan - 年初至今商业险折前保费累计（元）
• marginal_contribution_amount_yuan - 年初至今边际贡献额累计（元）

可选字段:

• week_number - 周次（用于识别数据对应的周）
• policy_start_year - 年份

标准输出格式

## KPI计算结果

**数据说明**:

- 截止时间: 第X周（YYYY-MM-DD 周六）
- 计算模式: [当周值模式/周增量模式]
- 已过天数: XXX天（年度时间进度: XX.XX%）

### 核心KPI（4x4网格）

| KPI名称              | 计算值 | 单位 | 说明     |
| -------------------- | ------ | ---- | -------- |
| **第一行：核心比率** |
| 满期边际贡献率       | XX.XX  | %    | 盈利能力 |
| 保费时间进度达成率   | XX.XX  | %    | 进度达成 |
| 满期赔付率           | XX.XX  | %    | 风险成本 |
| 费用率               | XX.XX  | %    | 运营效率 |
| **第二行：核心金额** |
| 满期边际贡献额       | XXX    | 万元 | 利润贡献 |
| 签单保费             | XXX    | 万元 | 业务规模 |
| 已报告赔款           | XXX    | 万元 | 赔付支出 |
| 费用额               | XXX    | 万元 | 费用支出 |
| **第三行：结构效率** |
| 变动成本率           | XX.XX  | %    | 成本控制 |
| 满期率               | XX.XX  | %    | 成熟度   |
| 满期出险率           | XX.XX  | %    | 出险频率 |
| 保单件数             | XXX    | 件   | 业务量   |
| **第四行：单均质量** |
| 赔案件数             | XXX    | 件   | 赔付频率 |
| 单均保费             | XXX    | 元   | 业务质量 |
| 案均赔款             | XXX    | 元   | 风险成本 |
| 单均费用             | XXX    | 元   | 成本效率 |

### 计算验证

- ✓ 变动成本率 = 赔付率(XX.XX%) + 费用率(XX.XX%) = XX.XX%
- ✓ 边际贡献率 = 100% - 变动成本率(XX.XX%) = XX.XX%

### 辅助字段

- 满期保费: XXX 万元
- 商业险自主系数: X.XX
- 单均边贡额: XXX 元

激活条件

当用户请求包含以下关键词时自动激活:

• "计算KPI" / "KPI计算" / "车险指标"
• "满期赔付率" / "边际贡献" / "保费达成率"
• CSV数据 + "周六" / "累计" / "年初至今"

⚠️ 关键注意事项

1. 累计数据本质: CSV数据是累计值，计算比率时分子分母必须来自同一累计时点
2. 周增量计算: 通过差分获得，但比率指标仍用累计数据（避免单周波动）
3. 周六截止: 每周数据截止到周六，时间进度计算需考虑周次映射
4. 50周工作制: 周计划 = 年度目标 ÷ 50，不是52
5. 除零保护: 使用 safeDivide，分母为0返回 null
6. 代码一致性: 与 src/lib/calculations/kpi-engine.ts:calculateIncrement() 保持完全一致

参考文档

• 核心计算文档: 开发文档/03_technical_design/core_calculations.md
• Domain层实现: src/domain/rules/kpi-calculator.ts
• 计算引擎: src/lib/calculations/kpi-engine.ts
• 公式定义: src/lib/calculations/kpi-formulas.ts