社保基数补差计算器
核心原则
- 禁止脑补：所有数据必须来自用户提供的申报表截图或明确输入，不得猜测费率、基数、人员。
- 先验证后计算：从截图反推基数差和费率，与已知标准交叉验证一致后再计算。
- 区分费用性质：基数补差（旧基数→新基数的差额补缴）与当月正常缴费（按新基数全额缴纳）必须分开列示，不得混淆。
- 分厘尾差正常化：社保系统按月截断与四舍五入可能产生 ≤0.03 元差异，标注说明即可，不视为错误。
工作流程（六步）
第一步：读取并解析申报表截图（注意凭证鉴别）
用户通常提供以下材料，需首先鉴别材料性质：
1. 社保/医保缴费申报明细表（【必须】）：含费款所属期、缴费基数、费率、应缴费额、参保人数等明细行。
2. 人员参保明细截图：含参保人员姓名、参保状态、起止月份等。
3. 【警惕】税收完税证明：若用户仅提供完税证明或扣款回单（仅有合计总金额），必须明确告知用户无法直接测算，需引导其前往电子税务局或社保客户端导出“申报明细表截图”。
解析要点：
- 从申报表"缴费基数"列提取每月补差总基数（注意：补差月份的缴费基数是差额，不是全额基数）
- 从"费率"列提取各险种单位/个人费率
- 从"应缴费额"列提取每月各险种实际扣费
- 从费款所属期确定补差月份范围
- 从人员明细确定每人参保起始月，进而确定每人补差月份数
第二步：验证人均月基数差额（识别全员统一与差异化档位）
用两种方式交叉验证：
1. 按人数反推：每月补差总基数 ÷ 当月参保人数 = 人均月基数差
- 全员按最低基数保底申报的企业：不同参保人数的月份（如3人月和4人月）算出的月基数差必须完全一致（如太原均为 46 元）。
- 若不同月份算出的月差存在跳变，提示企业内部可能存在按个人实际工资申报（非最低档）的员工，需逐人确认基数差额。
2. 全额基数反推：正常缴费月（如9月）总基数 ÷ 人数 = 新基数；新基数 - 人均月差 = 旧基数
第三步：验证费率与险种
将截图中费率列与默认费率（山西太原，见 references/rate-table-shanxi-taiyuan.md）对比：
- 一致 → 使用默认费率
- 不一致（如工伤费率因行业风险类别不同）→ 以截图为准，通过脚本 --rates 参数覆盖
- 存在定额险种（如职工大额医疗互助 14 元/人）→ 通过 --fixed-items 配置
验证方法：用截图中的月补差总基数 × 费率，看是否等于截图中的应缴费额。
第四步：确认人员与补差周期
根据人员明细截图和费款所属期：
- 列出每位员工的姓名、补差月份数、以及各自的基数差（全员相同时统一传入，差异化时逐人指定）
- 补差月份数 = 该员工在补差期间内的实际参保月数
- 新增员工只补其入职后的月份，离职员工只补其离职前的月份
向用户确认人员名单和月份数后再计算（如用户已明确说明则直接使用）。
第五步：执行计算
调用脚本 scripts/calculate_adjustment.py，采用确定性税控标准算法（tax_standard 模式自动按总差额基数核算，彻底消除多月提前舍入产生的尾差）。
1. 极简命令行语法（Windows 友好，防 Shell 转义脱扣）：
python scripts/calculate_adjustment.py \
--base-diff 46 \
--people "张三:6,李四:1" \
--normal-month "2026-09:4244:4"
2. 差异化员工基数差计算（如张三补46，李四补24）：
python scripts/calculate_adjustment.py \
--people "张三:6:46,李四:1:24"
3. 标准 JSON 参数或从文件读取：
python scripts/calculate_adjustment.py \
--base-diff 46 \
--people people.json \
--rates '{"injury":{"unit":0.007}}'
4. JSON 结构化输出（便于下游消费）：
python scripts/calculate_adjustment.py ... --format json
脚本路径：<skill_dir>/scripts/calculate_adjustment.py
第六步：生成输出
输出必须包含以下三部分，按顺序呈现：
1. 计算前提说明
- 人均月基数差额及验证方法
- 采用的费率列表
- 人员名单及各自补差月份
- 补差期间范围
2. 明细表格（至少包含以下表）
表一：单人单月补差标准（所有人通用基准）
| 险种 | 单位补差(元/人/月) | 个人补差(元/人/月) | 单月合计 |
|------|---------------------|---------------------|----------|
表二：分人员累计补差明细
| 姓名 | 补差月份 | 养老单位 | 养老个人 | 医疗单位 | 医疗个人 | 失业单位 | 失业个人 | 工伤单位 | 单位合计 | 个人合计 | 总计 |
|------|----------|----------|----------|----------|----------|----------|----------|----------|----------|----------|------|
（或按人员分块展示，每人一个子表）
表三：全单位分月补差汇总（如用户需要逐月核对）
| 费款所属期 | 参保人数 | 项目 | 养老保险 | 医疗保险 | 失业保险 | 工伤保险 | 当月总计 |
|------------|----------|------|----------|----------|----------|----------|----------|
（项目分为单位部分、个人部分、合计三行）
如含当月正常缴费，追加：
表四：当月正常缴费明细（标注"非补差，全额新基数"）
| 险种 | 单位缴纳 | 个人缴纳 | 合计 |
|------|----------|----------|------|
表五：本次一次性扣款总合计
| 费用项目 | 单位承担 | 个人承担 | 总金额 |
|----------|----------|----------|--------|
| 基数补差 | | | |
| 当月正常缴费 | | | |
| 合计 | | | |
3. 客户说明文字
生成一段客户可直接阅读的说明文字，要求：
- 开头先讲扣款构成（补差 + 当月正常缴费）
- 用通俗语言解释基数补差的含义
- 列出每人补差总额（不展开险种明细，客户只关心总数）
- 给出总扣款金额
- 结尾说明数据已与系统核对
参考模板：
您好，跟您说明一下本次扣款的构成：
本次是【X-X月基数补差 + X月当月社保医保】两笔费用合并一次性扣除。
一、基数补差部分
因2026年度缴费基数上调，需补缴X月至X月的基数差额，每人每月基数差XX元：
- 员工A（X个月）：补差XX.XX元
- 员工B（X个月）：补差XX.XX元
补差合计XXX.XX元，其中单位承担XX.XX元，个人承担XX.XX元。
二、X月当月正常缴费
X月按新基数全额正常缴纳，当月社保医保合计XXX.XX元。
三、本次扣款总计
两笔合计XXX.XX元。所有数据均与申报系统明细一致，可放心核对。
校验规则（交付前必查）
- 基数差一致性：不同参保人数月份反推出的人均月基数差必须相同
- 费率乘积验证：月补差总基数 × 费率 ≈ 截图应缴费额（允许 ≤0.01 元尾差）
- 分人员汇总验证：各人补差总计之和 = 全单位补差总计
- 单位/个人拆分验证：单位合计 + 个人合计 = 总计
- 与截图总额验证：计算出的各险种补差累计 ≈ 截图中补差月份应缴费额累计（允许 ≤0.03 元工伤保险尾差）
- 9月不混入补差：正常缴费月（全额基数）必须单独列示，不得计入补差总额
常见问题处理
Q：计算结果与申报表应缴费额是否有尾差？
A：脚本默认启用 tax_standard 模式（按总差额基数统一核算后再四舍五入），已消除多月单月预舍入引起的累计偏差。若截图申报表因社保局按月截断产生了极细微分厘差异（≤0.03元），直接在交付报告中注明“社保税控系统小数取整正常尾差”即可。
Q：企业内部员工薪资不同，部分人不是按最低基数保底申报？
A：通过简写语法 --people "张三:6:46,李四:1:24" 逐人为员工指定个性化月基数差（如张三调基补 46 元，李四因原工资高于旧下限仅需补 24 元）。未调基的员工基数差为 0 或不计入补差名单。
Q：用户拿来的是《税收完税证明》或银行回单，而非申报表？
A：完税证明仅显示当期划扣税费总额，无基数、费率与险种分项。必须明确告知用户：社保测算必须基于《社会保险费缴费申报表》或电子税务局《社保费申报明细》，请其登录截取明细后再行测算。
Q：用户只提供了社保申报表，没有医保截图？
A：先计算社保部分（养老、失业、工伤），向用户明确说明医保补差需要医保申报表截图后补充，严禁自行假设医保费率和金额。
Q：人员有进有出，补差月份各不相同？
A：在 --people 参数中为每人指定实际在保月份（如 --people "张三:6,李四:1"），脚本会自动分别独立分摊计算并在报告中单独列出。
Q：用户所在地区不是山西太原？
A：基数差验证逻辑通用。费率以当地政策为准，通过 --rates 覆盖比例险种（如工伤、医疗），通过 --fixed-items 配置当地定额险种（如定额长护险）。
参考文件
- 山西太原费率表：
references/rate-table-shanxi-taiyuan.md - 计算脚本：
scripts/calculate_adjustment.py
