---
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周实际发生）
```

### 计算模式

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` - 年份

## 标准输出格式

```markdown
## 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`