name	kpi-calculator
description	验证和调试车险业务16个核心KPI的计算逻辑,包括满期边际贡献率、满期赔付率、单均保费等。当用户提到"KPI"、"计算"、"赔付率"、"边际贡献"、"指标"时使用。
allowed-tools	Read, Grep, Bash

KPI 计算验证器

目标

确保车险业务16个核心KPI的计算逻辑正确,提供清晰的计算过程说明和业务解读。

何时使用

验证 KPI 计算是否正确
调试 KPI 数值异常
添加新的 KPI 指标
用户询问"为什么这个数字是这样的"
理解 KPI 的业务含义

16个核心 KPI（4x4 网格布局）

第一行：核心比率指标

1. 满期边际贡献率

满期边际贡献率 = 100% - 变动成本率
或
满期边际贡献率 = (边际贡献额 / 满期保费) × 100%

业务含义: 盈利能力核心指标,衡量最终的盈利空间 正常范围: 15% - 30%

2. 保费时间进度达成率（50周工作制）

# 当周值模式（累计视角）
保费时间进度达成率 = (实际签单保费累计 / 年度目标保费) / (已过天数 / 365) × 100%

# 周增量模式（单周视角）
保费时间进度达成率 = 周增量 / 周计划 × 100%
其中：周计划 = 年度目标 ÷ 50

业务含义: 衡量保费收入与年度目标的匹配程度 正常范围: 90% - 110%（超过100%表示超额完成）

3. 满期赔付率

满期赔付率 = (已报告赔款 / 满期保费) × 100%

业务含义: 反映赔付支出占满期保费的比例 正常范围: 60% - 80%

< 60%: 可能定价过高或理赔审核过严
80%: 风险较高,需要调整定价或风控

4. 费用率

费用率 = (总费用 / 签单保费) × 100%

业务含义: 衡量获取和管理业务所需成本的效率 正常范围: 15% - 25%

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

5. 满期边际贡献额

满期边际贡献额 = 满期保费 × 满期边际贡献率

业务含义: 利润的绝对值贡献,定位利润的绝对值贡献来源

6. 签单保费

签单保费 = SUM(签单保费)

业务含义: 业务规模的核心体现

7. 已报告赔款

已报告赔款 = SUM(已报告赔款)

业务含义: 已发生并上报的赔案金额

8. 费用额

费用额 = SUM(总费用)

业务含义: 业务相关的总费用支出

第三行：结构与效率指标

9. 变动成本率

变动成本率 = 满期赔付率 + 费用率

业务含义: 成本控制能力,诊断成本端的整体表现 正常范围: 70% - 85%

10. 满期率

满期率 = (满期保费 / 签单保费) × 100%

业务含义: 反映当期保费中已实现风险价值的部分

11. 满期出险率

满期出险率 = (赔案件数 / 满期保单数) × 100%
或
满期出险率 = (赔案件数 / 保单件数) × 满期率

业务含义: 衡量已满期保单的出险频率

12. 保单件数

保单件数 = COUNT(保单)

业务含义: 业务规模的辅助指标

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

13. 赔案件数

赔案件数 = COUNT(赔案)

业务含义: 赔付发生的频率

14. 单均保费

单均保费 = 签单保费 / 保单件数

业务含义: 业务质量,衡量平均每张保单的保费收入

15. 案均赔款

案均赔款 = 已报告赔款 / 赔案件数

业务含义: 风险成本,衡量平均每起赔案的赔付金额

16. 单均费用

单均费用 = 总费用 / 保单件数

业务含义: 运营效率,衡量平均每张保单的费用成本

验证流程

步骤 1: 读取计算逻辑文档

# 读取核心计算文档
Read 开发文档/03_technical_design/core_calculations.md

步骤 2: 检查代码实现

查找 KPI 计算引擎的实现文件:

# KPI 计算引擎
Read src/lib/calculations/kpi-engine.ts

# KPI 公式定义
Read src/lib/calculations/kpi-formulas.ts

# KPI Hook 层
Read src/hooks/domains/useKPICalculation.ts

步骤 3: 验证数据源

使用 Grep 查找数据聚合逻辑:

确认数据过滤条件
检查周次和日期范围处理
验证聚合计算（aggregateData 函数）
检查增量计算逻辑（calculateIncrement 方法）

步骤 4: 计算验证

对比文档中的公式与代码实现:

公式是否与 core_calculations.md 一致
边界条件处理
除零保护（safeDivide 函数）
单位转换（元 → 万元）
50周工作制计算

步骤 5: 输出验证报告

输出格式

# KPI 计算验证报告: [KPI名称]

## 公式定义
根据 `core_calculations.md`:
\```
满期赔付率 = 已报告赔款 / 满期保费 × 100%
\```

## 代码实现
文件: `src/lib/calculations/kpi-engine.ts:119-129`
\```typescript
const loss_ratio = safeDivide(
  aggregated.reported_claim_payment_yuan,
  aggregated.matured_premium_yuan
) !== null
  ? safeDivide(
      aggregated.reported_claim_payment_yuan,
      aggregated.matured_premium_yuan
    )! * 100
  : null
\```

## 验证结果
✅ 公式与文档一致
✅ 包含除零保护 (safeDivide 函数)
✅ 结果转换为百分比（乘以100）
✅ 数据聚合逻辑正确

## 示例计算
假设:
- 已报告赔款: 800,000 元
- 满期保费: 1,000,000 元

计算过程:
1. aggregated.reported_claim_payment_yuan = 800000
2. aggregated.matured_premium_yuan = 1000000
3. safeDivide(800000, 1000000) = 0.8
4. 0.8 × 100 = 80%

结果: 满期赔付率 = 80%

## 业务解读
80% 的赔付率处于正常范围上限(60%-80%),建议:
1. 关注高赔付案件分析
2. 评估是否需要调整定价策略
3. 加强风险评估和核保流程

## 问题发现
⚠️ 无

常见问题排查

问题 1: KPI 数值为 NaN 或 Infinity

原因: 除零错误 检查点:

// ❌ 错误示例
const ratio = totalClaims / totalPremium

// ✅ 正确示例（项目实际实现）
const ratio = safeDivide(totalClaims, totalPremium)

// safeDivide 函数定义
function safeDivide(numerator: number, denominator: number): number | null {
  if (!denominator || denominator === 0) {
    return null
  }
  return numerator / denominator
}

问题 2: KPI 数值异常大或异常小

原因: 数据过滤不正确或单位换算错误 检查点:

周次范围过滤（28-105）
年度筛选（2024-2025）
数据状态过滤（通过 DataService.filter）
金额单位换算:
- 绝对值指标: 元 → 万元（除以 10000）
- 均值指标: 保留元单位
- 比率指标: 乘以 100 转为百分比

问题 3: 增量计算结果不正确

原因: 增量计算逻辑错误或混淆了累计值和增量值 检查点:

绝对值指标（签单保费、保单件数等）: 使用增量数据

signed_premium_yuan: currentAgg.signed_premium_yuan - previousAgg.signed_premium_yuan

比率指标（赔付率、费用率等）: 使用累计数据

// 必须基于累计数据计算
loss_ratio = (累计赔款 / 累计满期保费) × 100%

问题 4: 保费时间进度达成率异常

原因: 周次计算或50周工作制配置错误 检查点:

确认使用 WORKING_WEEKS_PER_YEAR = 50
检查周次到日期的映射（getTimeProgressForWeek 函数）
验证计算模式（current vs increment）

问题 5: 前端显示与计算结果不一致

原因: 数据精度或四舍五入差异 检查点:

比率指标: 保留1-2位小数
金额指标: 万元保留0-2位小数

均值指标: 元单位,四舍五入为整数

const average_premium = average_premium_raw !== null
  ? Math.round(average_premium_raw)
  : null

边贡分析专题

项目包含边际贡献分析的深度下钻功能:

1. 满期边贡率（盈利能力结果）

满期边贡率 = 100% - 变动成本率

解读: 每100元满期保费的净剩余

2. 变动成本率（成本控制能力）

变动成本率 = 满期赔付率 + 费用率

解读: 业务的直接成本结构

3. 满期边贡额（利润绝对值）

满期边贡额 = 满期保费 × 满期边际贡献率

解读: 利润的绝对贡献额

4. 单均边贡额（盈利质量）

单均边贡额 = (满期边贡额 × 10000) / 保单件数

解读: 判断增长是否为高质量的盈利性增长

最佳实践

总是使用 safeDivide - 防止除零错误
明确注释计算逻辑 - 在代码中说明公式来源
保持公式与文档同步 - 修改计算逻辑时同步更新 core_calculations.md
验证单位转换 - 元、万元、百分比要清晰标注
区分累计值和增量值 - 特别是在周增量计算中

核心文件位置

计算引擎: src/lib/calculations/kpi-engine.ts
公式定义: src/lib/calculations/kpi-formulas.ts
Hook 层: src/hooks/domains/useKPICalculation.ts
业务服务: src/services/KPIService.ts
文档定义: 开发文档/03_technical_design/core_calculations.md

工具限制

本 skill 只能读取和分析代码,不能修改。如需修改计算逻辑:

明确告知用户需要调整的地方
提供具体的代码修改建议
说明修改的业务影响
提醒同步更新相关文档

Install Skill

SKILL.md