| name | kpi-calculator |
| description | 基于每周六截止的年度累计CSV数据，精确计算车险业务16个核心KPI指标。接受原始CSV数据，执行聚合和计算，输出完整的KPI结果。当用户提到"计算KPI"、"KPI计算"、"赔付率"、"边际贡献"、"指标"时使用。 |
| allowed-tools | Read, Grep, Bash, mcp__ide__executeCode |
车险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周实际发生）
计算模式
- 当周值模式（累计视角）: 直接使用CSV中的累计数据
- 周增量模式（单周视角）: 第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计算公式
第一行：核心比率指标（%）
- 满期边际贡献率 =
100% - 变动成本率
- 保费时间进度达成率:
- 当周值模式:
(累计签单保费/年度目标) / (已过天数/365) × 100%
- 周增量模式:
周增量签单保费 / (年度目标÷50) × 100%
- 满期赔付率 =
累计已报告赔款 / 累计满期保费 × 100%
- 费用率 =
累计费用额 / 累计签单保费 × 100%
第二行：核心金额指标（万元）
- 满期边际贡献额 =
累计满期保费 × 满期边际贡献率 / 10000
- 签单保费 =
累计签单保费_元 / 10000
- 已报告赔款 =
累计已报告赔款_元 / 10000
- 费用额 =
累计费用额_元 / 10000
第三行：结构与效率指标
- 变动成本率 =
满期赔付率 + 费用率
- 满期率 =
累计满期保费 / 累计签单保费 × 100%
- 满期出险率 =
(累计赔案件数 / 累计保单件数) × 满期率
- 保单件数 =
累计保单件数
第四行：单均质量指标（元）
- 赔案件数 =
累计赔案件数
- 单均保费 =
累计签单保费_元 / 累计保单件数
- 案均赔款 =
累计已报告赔款_元 / 累计赔案件数
- 单均费用 =
累计费用额_元 / 累计保单件数
辅助字段
- 商业险自主系数 =
累计签单保费 / 累计商业险折前保费
- 单均边贡额 =
累计边际贡献额 / 累计保单件数
计算工作流
模式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结果
关键差异表
| 指标类型 | 当周值模式 | 周增量模式 |
|---|
| 签单保费 | 累计值 | 增量值 |
| 保单件数 | 累计值 | 增量值 |
| 满期赔付率 | 累计赔款/累计保费 | 累计赔款/累计保费 ⚠️ |
| 费用率 | 累计费用/累计保费 | 累计费用/累计保费 ⚠️ |
| 单均保费 | 累计保费/累计件数 | 增量保费/增量件数 |
核心计算规则
- 安全除法: 分母≤0时返回
null（使用 safeDivide 函数）
- 单位转换:
- 金额类: 元 → 万元（÷10000，四舍五入到整数）
- 比率类: 小数 → 百分比（×100，保留2位小数）
- 均值类: 保留整数元
- 数据来源:
- 所有比率的分子分母必须来自同一时间点的累计数据
- 增量只用于绝对值指标的展示
- 验证关系:
- 变动成本率 = 满期赔付率 + 费用率（必须相等）
- 满期边际贡献率 = 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数据 + "周六" / "累计" / "年初至今"
⚠️ 关键注意事项
- 累计数据本质: CSV数据是累计值，计算比率时分子分母必须来自同一累计时点
- 周增量计算: 通过差分获得，但比率指标仍用累计数据（避免单周波动）
- 周六截止: 每周数据截止到周六，时间进度计算需考虑周次映射
- 50周工作制: 周计划 = 年度目标 ÷ 50，不是52
- 除零保护: 使用
safeDivide，分母为0返回 null
- 代码一致性: 与
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
