---
name: insurance-weekly-report
description: 华安保险车险周报自动生成器（麦肯锡风格）。将周度车险数据（支持Excel/CSV/JSON/DuckDB）转化为12-13页董事会级经营分析报告。采用问题导向标题、16:9宽屏、四象限/气泡图可视化、深红#a02724配色。报告结构：经营概览、保费进度、变动成本、损失暴露、费用支出，每个章节分机构和分客户类别双维度分析。支持自定义阈值配置和保费计划。触发场景：用户上传车险周报数据文件（.xlsx/.csv/.json/.db），要求生成董事会汇报PPT。
---

# 华安保险车险周报自动生成器

## 核心目标

将周度车险保单数据（Excel）转化为**12-13页麦肯锡风格董事会经营分析报告**（PPT），采用问题导向标题、四象限/气泡图分析、16:9宽屏格式。

## 使用流程

### 快速开始（3步）

```bash
# 1. 确认配置文件（首次使用需检查）
ls references/thresholds.json  # 阈值配置
ls references/plans.json        # 保费计划（可选）

# 2. 上传数据文件
# 用户上传：车险保单变动成本清单.xlsx

# 3. 运行生成命令
cd scripts
python generate_report.py <数据文件> <周次> <机构名称> ../references

# 示例
python generate_report.py ../data.xlsx 49 四川分公司 ../references
```

### 数据文件要求

**支持格式：**

- `.xlsx` / `.xls` - Excel 文件（推荐）
- `.csv` - CSV 文本文件（UTF-8 编码）
- `.json` - JSON 格式（数组或对象）
- `.db` / `.duckdb` - DuckDB 数据库（需安装 duckdb）

**✨ v2.1新增：支持两种数据格式**

#### 格式1：汇总数据（中文字段）- 推荐格式

**必需字段：**

- `机构`：三级机构名称（如"高新机构"）
- `客户类别`：客户分类（如"家用车"、"货车"）
- `签单保费`：本周保费收入（元）
- `满期赔付率`：百分比值
- `费用率`：百分比值
- `变动成本率`：百分比值
- `已报告赔款`：已报案赔款金额（元）
- `出险率`：百分比值
- `案均赔款`：平均每案赔款（元）

#### 格式2：保单明细数据（英文字段）- 自动聚合

**✨ 新功能：直接上传明细数据，无需预处理！**

**必需字段：**

- `third_level_organization`：三级机构
- `customer_category_3`：客户类别
- `signed_premium_yuan`：签单保费（元）
- `matured_premium_yuan`：满期保费（元）
- `reported_claim_payment_yuan`：已报告赔款（元）
- `expense_amount_yuan`：费用金额（元）
- `policy_count`：保单件数
- `claim_case_count`：出险件数

**工作原理：**

1. 系统自动识别字段格式（英文/中文）
2. 如检测到明细数据，自动执行聚合操作：
   - 分机构聚合
   - 分客户类别聚合
   - 分机构+客户类别聚合
3. 自动计算率值指标（赔付率、费用率等）
4. 输出标准格式，生成报告

**支持的聚合字段映射（可在 references/field_mappings.json 中自定义）：**

- `third_level_organization` → `机构`
- `customer_category_3` → `客户类别`
- `signed_premium_yuan` → `签单保费`
- 等等...

**格式示例：**

_Excel/CSV 格式：_

```
机构,客户类别,签单保费,满期赔付率,费用率,变动成本率,已报告赔款,出险率,案均赔款
高新机构,家用车,1500000,68.5,18.2,86.7,1027500,22.3,5800
成华机构,货车,800000,75.2,19.5,94.7,601600,28.1,7200
```

_JSON 格式：_

```json
[
  {
    "机构": "高新机构",
    "客户类别": "家用车",
    "签单保费": 1500000,
    "满期赔付率": 68.5,
    "费用率": 18.2,
    "变动成本率": 86.7,
    "已报告赔款": 1027500,
    "出险率": 22.3,
    "案均赔款": 5800
  }
]
```

_DuckDB 格式：_

- 默认读取表名 `insurance_data`
- 或读取数据库中的第一个表
- 表结构需包含上述必需字段

## 工作流程

### 完整报告生成流程

```
1. 数据准备
   ↓
   用户上传数据文件
   系统识别格式（Excel/CSV/JSON/DuckDB）

2. 数据处理
   ↓
   ├─ 汇总数据 → 直接使用
   └─ 明细数据 → 自动聚合
         ├─ 分机构聚合
         ├─ 分客户类别聚合
         └─ 计算率值指标

3. 数据分析
   ↓
   ├─ 应用阈值配置（references/thresholds.json）
   ├─ 读取保费计划（references/plans.json，可选）
   ├─ 识别问题机构
   └─ 生成问题导向标题

4. 图表生成
   ↓
   ├─ 四象限散点图（变动成本 vs 签单保费）
   ├─ 气泡图（出险率 vs 案均赔款）
   ├─ 竖向条形图（分机构、分客户类别）
   └─ 双轴柱线图（趋势分析，如有历史数据）

5. PPT生成
   ↓
   ├─ 使用麦肯锡模板（assets/mckinsey_board_template.pptx）
   ├─ 填充12-13页幻灯片
   ├─ 应用深红配色方案（#a02724）
   └─ 导出最终报告

6. 输出交付
   ↓
   生成文件：{机构名称}_周报_第{周次}周_麦肯锡版.pptx
```

### 决策逻辑

- **格式识别**：根据文件扩展名和字段名自动判断数据格式
- **问题识别**：基于阈值配置自动标识异常指标
- **机构排序**：问题机构优先展示，确保管理层关注重点
- **图表选择**：根据数据维度自动选择最合适的可视化方式

## 报告结构（12-13页）

### 封面

- 标题：{机构名称}车险第{周次}周经营分析
- 日期：自动生成当前日期

### 一、经营概览（2页）

**页1：整体年累计指标**

- 标题：问题导向（自动生成）
  - 规则：基于阈值评价成本率、赔付率等核心指标
  - 示例："本周成本控制良好(85.3%)，高新机构成本需关注"
- 内容：左侧大数字展示4个核心率值指标
  - 签单保费（48pt粗体）
  - 变动成本率（48pt + 颜色状态）
  - 满期赔付率
  - 费用率

**页2：分机构四象限图**

- 标题：概述年、周保费计划达成率与变动成本率的问题机构
- 图表：散点图（X轴=年计划达成率，Y轴=变动成本率）
  - 基准线：X=100%，Y=90%（可配置）
  - 四个象限：双达成、保费落后、成本失控、双落后
  - 标注问题机构名称

### 二、保费进度分析（2页）

**页1：分机构**

- 标题：指出年计划和周计划未完成的问题机构
  - 示例："高新、成华机构年度保费进度落后，周计划完成不足"
- 表格：机构 | 年累计 | 当周值 | 年计划达成率 | 周计划达成率
  - 未达标机构标红

**页2：分客户类别**

- 逻辑同页1，维度改为客户类别

### 三、变动成本分析（2页）

**页1：分机构四象限图**

- 标题：指出变动成本率偏高的问题机构
  - 示例："{机构1}、{机构2}变动成本率偏高，需加强成本管控"
- 图表：散点图（X轴=满期赔付率，Y轴=费用率）
  - 基准线：X=70%，Y=18%（可配置）
  - 气泡大小=签单保费占比

**页2：分客户类别**

- 逻辑同页1

### 四、损失暴露分析（4页）

**页1：分机构气泡图**

- 标题：指出年累计满期赔付率、当年及当周已报告赔款占比超保费占比的问题三级机构
- 图表：气泡图
  - X轴：满期赔付率
  - Y轴：当年已报告赔款占比
  - 气泡大小：当周已报告赔款占比
  - 公式：已报告赔款占比 = 本机构已报告赔款 / 各机构已报告赔款合计

**页2：分客户类别**

- 逻辑同页1

**页3：二级指标分机构四象限图**

- 标题：指出年累计满期出险率与案均赔款的问题机构
- 图表：散点图（X轴=出险率，Y轴=案均赔款）
  - 基准线：X=20%，Y=6000元（可配置）

**页4：二级指标分客户类别**

- 逻辑同页3

### 五、费用支出分析（2页）

**页1：分机构四象限图**

- 标题：指出问题的三级机构
  - 示例："{机构1}费用率偏高且费用占比超保费占比"
- 图表：散点图（X轴=费用率，Y轴=费用占比超保费占比）
  - 费用占比超保费占比 = 费用占比 - 保费占比
  - 三级机构保费占比 = 三级机构签单保费 / 各三级机构签单保费之和

**页2：分客户类别**

- 逻辑同页1

### （可选）六、趋势分析

如用户上传多个周数据，自动添加趋势分析页：

- 核心指标折线图（保费、成本率、赔付率、费用率）
- 环比变化分析

## 问题导向标题生成规则

### 自动生成逻辑

基于 `references/thresholds.json` 中的阈值配置，自动识别问题并生成标题。

**识别规则：**

1. 变动成本率 > 95% → "成本偏高"
2. 变动成本率 < 85% → "成本控制良好"
3. 满期赔付率 > 75% → "赔付率偏高"
4. 费用率 > 20% → "费用率偏高"
5. 年计划达成率 < 95% → "保费进度落后"
6. 周计划达成率 < 90% → "周计划未达标"

**标题模板：**

```
格式：{整体评价}，{问题机构1}、{问题机构2}机构{具体问题}

示例1：本周成本控制良好(85.3%)，高新、成华机构保费进度落后
示例2：高新机构变动成本率偏高(98.2%)，需加强成本管控
示例3：各机构经营状况稳健，费用控制良好
```

### 问题机构排序

当多个机构存在问题时，按以下优先级排序：

1. 同时存在多个问题的机构（如成本高且保费低）
2. 偏离阈值最严重的机构
3. 保费规模最大的机构（影响面大）

最多展示3个问题机构名称，避免标题过长。

## 麦肯锡风格要点

### 视觉规范

- **配色**：深红 #a02724（主色）+ 灰度 + 状态色（绿#00b050/黄#ffc000/红#c00000）
- **字体**：
  - 标题：微软雅黑 Bold 24pt
  - 核心数字：Arial Bold 48pt
  - 正文：微软雅黑 14pt
- **布局**：
  - 16:9 宽屏（13.333 x 7.5英寸）
  - 页边距：0.8英寸（大量留白）
  - 左对齐，左右分栏布局
- **装饰**：
  - 仅顶部红色细线（0.015英寸高）
  - 无Logo堆砌，无多余装饰

### 图表设计原则

1. **简洁至上**：单色或双色，无渐变
2. **数据标注**：直接在图上标注数值，不用图例
3. **四象限图**：
   - 基准线使用虚线（灰色）
   - 象限标签放在角落（小字号）
   - 问题象限的点标红
4. **气泡图**：
   - 气泡大小代表权重
   - 问题点标红并标注机构名

## 配置文件说明

### references/thresholds.json

定义所有阈值和状态评价标准。用户可直接编辑此文件调整业务规则。

```json
{
  "状态评价阈值": {
    "变动成本率": {
      "优秀": { "max": 80, "color": "#00b050", "label": "成本控制优秀" },
      "达标": { "min": 80, "max": 95, "color": "#92d050" },
      "预警": { "min": 95, "max": 100, "color": "#ffc000" },
      "严重": { "min": 100, "color": "#c00000", "label": "成本失控" }
    }
    // ... 其他指标类似
  },

  "问题机构识别阈值": {
    "年保费未达标": 95, // 百分比
    "变动成本率超标": 95,
    "满期赔付率超标": 75,
    "费用率超标": 20
  },

  "四象限基准线": {
    "保费达成率": 100, // 百分比
    "变动成本率": 90,
    "满期赔付率": 70,
    "费用率": 18
  }
}
```

### references/plans.json（可选）

保费计划数据，用于计算达成率。如无此文件，保费进度分析页将显示警告。

```json
{
  "年度保费计划": {
    "四川分公司": 500000000,
    "高新机构": 80000000,
    "成华机构": 60000000
    // ... 其他机构
  },

  "周保费计划": {
    "第49周": {
      "四川分公司": 10000000,
      "高新机构": 1600000
      // ... 其他机构
    }
  }
}
```

**首次使用时，请用户提供此文件或告知无法计算达成率。**

## 错误处理

### 数据验证失败

- 缺少必需字段 → 列出缺失字段，终止运行
- 数据类型错误 → 提示具体行/列，要求修正

### 配置文件缺失

- 无 thresholds.json → 使用默认阈值，继续运行
- 无 plans.json → 警告无法计算达成率，跳过保费进度分析页

### 数据异常

- 所有成本率 > 100% → 警告数据可能有误，继续运行
- 机构名称不一致 → 自动合并相似名称（如"高新"和"高新机构"）

## 调用示例

**场景1：基础用法（Excel格式）**

```
用户：我上传了第49周的车险数据，帮我生成董事会汇报PPT

Skill执行：
1. 检查 references/ 配置文件
2. 自动识别文件格式（.xlsx）
3. 运行：python scripts/generate_report.py data.xlsx 49 四川分公司 references/
4. 生成 12 页 PPT
5. 移动到 /mnt/user-data/outputs/
6. 返回下载链接
```

**场景2：CSV 格式**

```
用户：这是我从系统导出的 CSV 数据，生成周报

Skill执行：
1. 识别文件格式（.csv）
2. 自动检测编码（UTF-8）
3. 运行生成命令
4. 返回 PPT
```

**场景3：DuckDB 数据库**

```
用户：我的数据存在 DuckDB 里，生成第49周报告

Skill执行：
1. 检查 DuckDB 是否安装
2. 连接数据库，查找 insurance_data 表
3. 读取数据并生成报告
4. 返回 PPT
```

**场景4：JSON 格式（从 API 获取）**

```
用户：这是从 API 拿到的 JSON 数据，生成报告

Skill执行：
1. 解析 JSON 格式
2. 转换为 DataFrame
3. 生成报告
4. 返回 PPT
```

**场景5：缺少保费计划**

```
用户：生成周报

Skill执行：
1. 检测到无 plans.json
2. 提示："检测到您尚未配置保费计划文件。保费进度分析页将无法计算达成率。是否提供 plans.json 或继续生成（跳过保费进度页）？"
3. 根据用户选择执行
```

**场景3：多周趋势分析**

```
用户：我上传了第48周和第49周的数据，生成带趋势分析的报告

Skill执行：
1. 检测到多周数据
2. 分别计算每周KPI
3. 生成基础12页 + 趋势分析页（第13页）
4. 返回下载链接
```

## 技术栈

- **数据处理**：pandas, numpy
- **PPT生成**：python-pptx
- **可视化**：matplotlib（嵌入PPT）
- **配置管理**：json

## KPI 计算公式

本技能的 KPI 计算逻辑完全对齐 **kpi-calculator** 技能，确保数据一致性。

### 核心 KPI（10个）

#### 核心比率指标（%）

1. **满期赔付率** = 已报告赔款 / 满期保费 × 100%
2. **费用率** = 费用金额 / 签单保费 × 100%
3. **变动成本率** = 满期赔付率 + 费用率
4. **满期率** = 满期保费 / 签单保费 × 100%
5. **满期边际贡献率** = 100% - 变动成本率

#### 结构与效率指标

6. **满期出险率** = (出险件数 / 保单件数) × 满期率

#### 单均质量指标（元）

7. **案均赔款** = 已报告赔款 / 出险件数
8. **单均保费** = 签单保费 / 保单件数
9. **单均费用** = 费用金额 / 保单件数

#### 核心金额指标（元）

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

### 与 kpi-calculator 的关系

- ✅ **公式完全一致**：所有 KPI 计算公式与 kpi-calculator 保持一致
- ✅ **自动计算**：无需单独运行 kpi-calculator
- ✅ **交叉验证**：可使用 kpi-calculator 验证计算准确性
- ✅ **单元测试**：通过 test_kpi_alignment.py 验证一致性

### 关键差异说明

**出险率**：

- 本技能计算"满期出险率" = (出险件数/保单件数) × 满期率
- 考虑了保单成熟度因素，更准确反映风险水平
- 与简单出险率不同，避免包含未满期保单的影响

**新增指标（v2.1.1）**：

- 满期率
- 满期边际贡献率
- 满期边际贡献额
- 单均保费
- 单均费用

## 版本信息

- **版本**：v2.1.1 (KPI Alignment Edition)
- **更新日期**：2025-12-09
- **维护者**：Alongor
- **设计风格**：McKinsey & Company
- **符合标准**：Anthropic Skills Best Practices

**核心改进（v2.1.1）：**

- ✅ **KPI 计算对齐 kpi-calculator**（公式完全一致）
- ✅ 新增 5 个核心 KPI（满期率、满期边际贡献率等）
- ✅ 修正出险率为满期出险率
- ✅ 增强公式解析器（支持括号运算）
- ✅ 单元测试验证（test_kpi_alignment.py）
- ✅ 交叉验证通过（误差 < 0.05%）

**核心改进（v2.1.0）：**

- ✅ **自动数据格式识别和转换**（无需预处理）
- ✅ 支持保单明细数据自动聚合
- ✅ 字段映射配置化（references/field_mappings.json）
- ✅ 模块化数据处理层（data_transformer.py）
- ✅ 向后兼容（支持原有汇总数据格式）
- ✅ 完全符合 Skills 最佳实践

**继承特性（v2.0.0）：**

- ✅ 单一脚本入口（generate_report.py）
- ✅ 配置文件驱动（用户可编辑阈值和计划）
- ✅ 问题导向标题自动生成
- ✅ 严格遵循麦肯锡视觉规范
- ✅ 12-13页结构化报告
- ✅ 双维度分析（分机构 + 分客户类别）