社保批量导入格式转换
把社保明细Excel中的增员名单，转成社保系统的官方参保导入格式。
加载即执行
1. 确认源文件路径 → 用户提供的社保明细Excel
2. 定位增员名单sheet → 查找含「增员」关键字的sheet
3. 读取右侧参保模板区域 → 列28-34（姓名/身份证/学历/参保时间/电话/民族/备注）
4. 学历和民族转换 → 简称→全称+代码前缀
5. 日期和电话修正 → Excel序列号→日期，浮点→字符串
6. 以官方模板为基底输出 → 保留其他Sheet不变
Gotchas（遇到X时做Y）
- 遇到源文件有左右两栏数据时 — 参保导入模板数据在右侧第28列起，不是左侧主表。从第28列开始读取姓名/身份证等信息，不要从第1列读
- 遇到学历字段是简称时（如"大专""本科"） — 先用映射表转全称（大专→大学专科），再加代码前缀（→"31 大学专科"），见 references/mapping-tables.md
- 遇到民族字段时 — 直接加两位数字代码前缀（汉族→"01 汉族"），代码表见 references/mapping-tables.md
- 遇到参保时间字段是数字（如46186）时 — 这是Excel序列号，用
datetime(1899,12,30) + timedelta(days=int(serial))转成日期格式；如果已经是datetime对象则不动 - 遇到电话字段是浮点数（如13800000000.0）时 — 用
str(int(phone))转成纯文本字符串，否则社保系统导入会报错 - 读取源文件时 — 必须传
data_only=True参数给load_workbook()，否则读到的是公式字符串而非计算后的实际值，导致所有字段为None - 写入输出时 — 官方模板有学历、民族、岗位性质、毕业院校地域类别四个Sheet是数据验证源，严禁删除或覆盖，必须完整保留
- 读取列位置前 — 不同版本的源文件列布局可能变化，先读第2行表头确认：列28=姓名/列29=身份证/列30=文化程度/列31=参保时间/列32=移动电话/列33=民族，不对则调整
- 源文件找不到含「增员」的sheet时 — 遍历所有sheet名，输出可用sheet列表让用户选择，不要直接报错退出
核心流程
步骤1：定位源数据
wb_src = load_workbook(source_path, data_only=True)
# 查找含「增员」的sheet
sheet_name = [s for s in wb_src.sheetnames if '增员' in s][0]
ws_src = wb_src[sheet_name]
如果找不到： 输出所有可用sheet名，让用户指定。
步骤2：读取模板区域
从第4行开始（跳过标题行和表头），读列28-33：
- 列28: 姓名 | 列29: 身份证 | 列30: 文化程度 | 列31: 参保时间 | 列32: 移动电话 | 列33: 民族
跳过多余的空行（第4行之外如果有空数据行，跳过）。读取前先读取第2行表头确认列位置是否准确。
步骤3：格式转换
| 字段 | 输入 | 转换规则 | 输出示例 |
|---|---|---|---|
| 学历 | 大专 | 简称→全称→加代码前缀 | 31 大学专科 |
| 民族 | 汉族 | 查表加代码前缀 | 01 汉族 |
| 参保时间 | 46186 (数字) | Excel序列号转datetime | 2026-06-13 |
| 电话 | 13800000000.0 (浮点) | float转str(int) | 13800000000 |
映射表见 references/mapping-tables.md
步骤4：写入输出
使用者需自行从成都社保系统下载官方参保导入模板（Excel格式），以该官方模板为基底，Sheet1清空旧数据并写入转换后的数据，保留其他4个参照Sheet不动，另存为新文件。
> 完整可执行脚本 → scripts/convert_to_official.py
> 用法：python scripts/convert_to_official.py <源文件路径> <官方模板路径> [输出文件名]
> 验证脚本 → scripts/validate_skill.py
快速导航
| 需要什么 | 去这里 |
|---|---|
| 学历/民族代码对照表 | references/mapping-tables.md |
| 可执行转换脚本 | scripts/convert_to_official.py |
| 教学记录（踩坑过程） | references/teaching-record.md |
| 官方参保模板 | 从成都社保系统下载（本技能不附带） |
| 版本变更 | CHANGELOG.md |
验证完成
全部通过才算完成：
□ 输出文件可打开无报错
□ 学历均为「代码 全称」格式（如 31 大学专科）
□ 民族均为「代码 民族名」格式（如 01 汉族）
□ 参保时间为日期格式，非数字
□ 电话号码为文本，非浮点数
□ 官方模板的其他4个Sheet完整保留
□ python scripts/validate_skill.py → ALL CHECKS PASSED
