insurance-weekly-report

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步）

# 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 格式：

[
  {
    "机构": "高新机构",
    "客户类别": "家用车",
    "签单保费": 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

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

{
  "状态评价阈值": {
    "变动成本率": {
      "优秀": { "max": 80, "color": "#00b050", "label": "成本控制优秀" },
      "达标": { "min": 80, "max": 95, "color": "#92d050" },
      "预警": { "min": 95, "max": 100, "color": "#ffc000" },
      "严重": { "min": 100     
    
    
  

   
      
     
     
     
  

   
      
     
     
     
  

references/plans.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页结构化报告
• ✅ 双维度分析（分机构 + 分客户类别）