申报社保足额补缴助手
目的
帮助劳动者完成社保未足额缴纳的申诉文书起草、工资总额汇算与补缴金额测算。核心产出四类成果：投诉申请文书（3 份 Word）、工资总额汇算表、缴存基数汇总表、养老保险个人补缴金额测算表。
目录结构
references/— 按需加载的参考文档：00-新手入门指引.md：材料清单、获取渠道、完整流程、常见问题（面向用户的说明，可摘引给用户）01-文书填写使用规范.md：强制规范——文书只填内容、不碰格式02-数据汇算使用规范.md：强制规范——同月多条数据必须先合计再填表03-政策依据与缴费比例.md：法律依据、缴费比例（以广东/江门为例）、计算口径scripts/— 可执行工具：fill_doc_template.py：文书填数据通用工具（打开模板 → 替换占位符 → 另存）admin_doc_template.py：行政文书格式生成器（v9 定稿版），仅用于新增文书时生成同格式模板monthly_aggregator.py：按月分组合计工具templates/— 定稿模板（9 份）：3 份 docx 文书模板 + 6 份 xlsx 汇算/测算表
> 首次使用必做（SkillHub 版）：9 份模板以 base64 纯文本随包（模板目录内原文件名后加.b64.txt后缀）。首次使用前运行一次python scripts/restore_assets.py还原；fill_doc_template.py启动时会自动调用还原。还原后路径与调用方式完全一致。
工作流程
第 1 步：确认信息与材料
开始前向用户确认以下信息，缺失则追问，不要猜测：
- 劳动关系期间（入职、离职/退休年月，可能有多段）
- 用人单位全称、参保地（市、区）
- 材料是否齐备：社保缴费历史明细、个税纳税清单、银行工资流水（必需）；医疗保险缴费明细、住房公积金缴存明细（重要）
材料获取渠道见 references/00-新手入门指引.md 第二节，用户缺材料时按该表指引。
第 2 步：汇算工资总额（二选一或并用）
- 途径一（报税规范）：工资总额 = 个税申报收入额 + 个人所得税额 → 用
templates/途径一_个税申报收入汇总表.xlsx - 途径二（报税不规范）：工资总额 = 实发工资 + 补贴 + 各项代扣缴个人部分 → 用
templates/途径二_银行流水代扣缴工资总额表.xlsx
强制规范（详见 references/02-数据汇算使用规范.md）：同一月份存在多条记录（正常工资+年终奖等）时，必须先用 scripts/monthly_aggregator.py 的 aggregate_by_month() 按月合计，再填入表格。禁止逐行直接填入。输出前自检：总月数、无同月两行、年度合计与原始数据一致。
汇算结果按年度填入 templates/年度工资总额汇总表.xlsx，得出各年度月均工资（缴费基数）。
第 3 步：已缴数据汇算
将社保缴费明细粘贴入 templates/社保缴费明细汇算表.xlsx，提取缴费年月、缴费工资（已申报基数）、养老个人缴费额，自动反推各年度个人缴费比例。
第 4 步：补缴差额测算
用 templates/养老保险个人补缴差额测算表.xlsx 逐月计算：个人补缴差额 = 实际工资总额 × 8% − 已缴养老个人。快速估算用 templates/社保补缴金额估算表.xlsx。计算口径与历史缴费比例（广东/江门）见 references/03-政策依据与缴费比例.md。
第 5 步：起草文书
三份文书按用户维权阶段选用（路径：协商 → 社保经办机构申请 → 劳动监察投诉 → 行政复议 → 行政诉讼）：
| 文书 | 场景 |
|---|---|
templates/社保补缴申请书.docx |
向社保征缴主管部门申请补缴 |
templates/劳动保障监察投诉书.docx |
社保部门推诿时向劳动监察大队投诉 |
templates/行政复议申请书.docx |
不受理/超期不答复时申请复议 |
强制规范（详见 references/01-文书填写使用规范.md）：格式已定稿，只填内容、不碰格式。必须调用 scripts/fill_doc_template.py 的 fill_template(模板名, info, 输出名) 填数据，禁止用 python-docx 从头创建文档或改动模板文件。info 字段：name, unit, city（不带"市"字）, district（不带"区/县"字）, start_date, end_date, period1, period2, end_note（可选，默认"离职（退休）"）。三份文书各字段能否自动填充见该规范第六节的覆盖表；复议申请书的个案空白（日期、文号、复议机关选择）在副本上手工填入后再交用户复核。
第 6 步：复核与交付
交付前逐项检查：文书三份齐全且字段无遗漏；各表月份数、合计数自检通过；向用户明示重要提醒——
- 时效：向社保经办机构申请追缴无时效限制；劳动监察投诉 2 年；行政复议 60 日；行政诉讼 6 个月
- 滞纳金由违法欠缴的单位承担；个人部分由个人承担、单位部分由单位承担
- 补缴测算仅供参考，最终金额以社保经办机构核定为准
- 各地缴费比例与办理流程不同，建议先拨 12333 确认
地区适用性
历史缴费比例数据目前以广东省（江门市）为例（见 references/03-政策依据与缴费比例.md）。处理其他地区用户时：不得直接套用广东比例，须提示用户向当地社保部门核实对应年度的单位缴费比例；个人比例 8% 全国统一可放心使用；时效规定全国统一。
隐私要求
用户材料（社保明细、纳税清单、流水）含个人身份信息。处理时：仅在本地临时目录操作；生成的文书与表格交付用户后不留副本；不得将含个人信息的文件写入技能目录或任何对外位置。
