社保汇总工作簿

它解决什么问题

在多公司、多分页的社保归集场景里，把各源表的五险明细誊进一张总表，很容易出现三类问题：小计和合计公式被改成静态结果、合并单元格与表头版式走样、新增或减少员工后公式引用的行号漂移。手工修表不仅耗时，还常常留下难以察觉的引用错误。

核心能力

这个技能把归集动作收敛成一次脚本运行：读取 --data-folder 指定的源数据目录，按参考表的版式生成新的汇总工作簿，输出的是带公式的活表，而不是一份只能看的总结文档。

关键步骤如下：

• 先读取 references/field-rules.md，确认字段识别与五险列的对应方式
• 复制参考表作为基底，再写入员工行，默认不改动原参考表
• 只在「员工数据区起始行」和「小计行」之间同步员工行，分页名、合并单元格、小计/合计、格式均保留参考表
• 已在参考表中的员工，只替换五险金额列，一级部门 到 缴费基数 等静态信息保持原样
• 数据表里出现、参考表中没有的员工，在小计上方插入新行，并复制邻近行的样式与公式；不猜测基础信息列，模板没有明确值时留空
• 参考表里有、数据表中已不存在的员工，仅删除其数据行，不碰小计、合计、审核、制表等固定行
• 同一员工在源表出现多行时，先累计金额再写入

参考表默认使用内置的 assets/template.xlsx，不需要用户额外提供。只有明确要求使用自有模板时，才通过 --reference-workbook 覆盖。

分页映射与校验

数据文件与目标分页的对应按三步执行：先做精确文件名匹配，再用别名表做子串匹配，最后回退到员工姓名交叉比对。中文文件名、别名和表头识别都放在 Python 内部处理。

校验环节除了跑 scripts/test_social_insurance_workbook.py，还要用真实输入运行主脚本，确认输出文件已生成且原参考表未被修改。公式保真度很重要时，需要检查工作表 XML 里的 shared formulas 与 array formulas，不能只看 openpyxl 展示出来的公式字符串。检查范围要覆盖首个、中间、最后一个员工行的汇总列，确认小计值与可见员工行求和一致；小计行号不能写死，必须从当前分页内容里动态定位。

适用边界

这个技能只处理「各公司员工五险明细源表 → 社保汇总总表」这一层归集，不做工资计算，也不生成申报文件。源数据的列名、分页别名如果不在映射表内，需要先补齐映射规则再运行。