小型企业工资准备 是做什么的？
在发薪日之前捕获错误和遗漏。
此技能将业主的工资规则及其POS、考勤系统、记账和HR导出文件转换为经过检查的工资单：一个审查工作簿、一个证据链以及用于其工资系统的上传文件。它从不提交工资单。由人工审查并提交。
所有操作均通过此技能文件夹中的单一命令行工具运行：
python3 scripts/payroll.py --help # 需要 Python 3.10+ 和 openpyxl (pip install openpyxl)
在其他位置工作时，使用技能文件夹的绝对路径运行它，例如
python3 <skill-dir>/scripts/payroll.py run <period-folder>。
基本规则（请先阅读）
- 只有
payroll.py run决定一切正常。 退出代码0且output/evidence.json中"status": "ALL CLEAR"是唯一的一切正常标志。切勿根据您自己对数字的判断将运行描述为干净、完成或就绪。退出代码2表示未就绪，退出代码1表示受阻。 - 切勿编造费率、阈值、窗口或工资类型名称。 如果业主没有告知您，请留空以使运行停止并询问。猜测的数字将成为一张工资支票。
- 业主签署的规则是运行的法律。 规则变更应写入
payroll_config.json，然后重新生成并重新批准工资规则手册。切勿手工编辑工作簿或导出文件中的数字；修复输入或规则并重新运行。 - 警告需要决策。 每个警告都会阻止一切正常，直到输入被修复或有人在
period.json中记录了确认信息（acknowledged_warnings，包含决策人和原因）。不要代替业主确认；请询问他们。 - 非法律或税务建议。 州预设仅为起点。告知业主与他们的工资服务提供商或雇佣法律顾问确认加班、最低工资、病假、小费和最后工资规则。
- 保护敏感数据。 引擎只需要姓名、ID、费率和工时。切勿要求或存储社会保障号码、银行详细信息或出生日期。如果导出文件中包含这些信息，不要将这些列复制到任何地方。
工作区结构
<workspace>/
payroll_config.json 业主的规则（来自初始设置）
PAY_RULES_BOOK.md / .html 用通俗语言编写的规则，包含业主的签字确认
connectors/ 可选的HRIS / 工资系统配置文件副本
history/weeks.json 已支付的工时和加班费，按工作周记录（由运行写入）
periods/<start>_<end>/
period.json 日期、月度窗口、窗口、证明、来源、确认信息
raw/ 原样下载的导出文件
inputs/ 引擎读取的标准CSV文件
output/ 审查工作簿、上传文件、运行摘要、evidence.json
如果业主想先看看效果，可以先用一个虚构样本：payroll.py sample ./demo（一家水疗中心）或 payroll.py sample ./demo --kind retail（一家连锁店），然后针对 demo/periods/ 中的每个期间运行 approve ./demo --by "<name>"、hris-import 和 run（参见 references/getting-started.md）。选择最接近业主业务的示例。
业主的需求决定模式
1. 设置（初始信息收集）
业主尚未拥有 payroll_config.json，或希望更改工资支付方式。
- 询问他们所在的行业以及工资支付方式（
references/questionnaire.md中的start.1和start.2）。即使此工具不支持其行业的某些需求，也应尽早告知业主（参见该文件中的“尚未处理”列）。 - 询问他们希望如何回答其余问题：与您面谈，或使用其行业的可填写初始工作簿（
payroll.py intake-workbook intake.xlsx --industry <id>，然后compile-intake intake.xlsx payroll_config.json）。 - 对于面谈，按照
references/questionnaire.md进行：一次一个问题，仅涵盖与其支付方式相符的核心部分及其行业的附加包，在写入任何内容之前，将每个部分作为规则反馈给业主。 - 根据
references/config-reference.md编写配置。从payroll.py init <workspace>开始。从assets/states/加载州预设，并让业主确认它们（references/state-rules.md）。 - 运行
payroll.py validate <workspace>直到它显示 VALID。 - 运行
payroll.py rulebook <workspace>，引导业主检查每个规则ID，修复问题，重新生成。 - 当业主同意时，运行
payroll.py approve <workspace> --by "<owner name>"。
2. 开始一个新的付款周期
payroll.py new-period <workspace> --start YYYY-MM-DD --end YYYY-MM-DD --pay-date YYYY-MM-DD
（在支付月度激励的运行中添加 --monthly；窗口默认为结束日期所在日历月，或使用 --month-start 和 --month-end 设置）。
按日期顺序运行期间：跨越两个周期的工作周需要前一个周期的工时。对于第一个期间，请参阅 references/config-reference.md 中的“history”。它会打印该期间涉及的工作周、边界周警告以及来自 systems.pos_reports 的导出清单。将该清单提供给业主。
3. 将导出文件转换为输入文件
- HR花名册、工资费率和休假记录：使用
systems.hris中的配置文件，运行payroll.py hris-import <period> --roster <file> --time-off <file>（references/hris-connectors.md）。阅读output/hris_import_report.md；使用--map field=Header或编辑<workspace>/connectors/中配置文件的副本修复失败项。 - POS报告：将每个报告映射到标准CSV文件中（
references/input-formats.md、references/pos-mapping.md）。根据标题文本映射，绝不根据列位置。在period.json的sources中记录每个报告及其打印的总数，以便运行可以证明没有数据丢失或重复。 - 如果某个输入在本期间确实没有数据（例如某个地点没有人休过假），则在
period.json中记录一个证明，而不是提供一个空文件。
然后运行 payroll.py check <period>：如果就绪则显示 READY TO RUN，或者显示需要修复的确切失败项。
4. 运行
payroll.py run <period>。它会执行检查关卡、计算、将每个输入总额与已支付总额进行核对、独立重新计算一切（审计）、与上一期比较、写入工资文件，并打印 ALL CLEAR、NOT CLEAR 或 BLOCKED。
- BLOCKED: 未进行任何计算。修复失败的行（通常是输入问题）并重新运行。
- NOT CLEAR: 阅读原因。修复输入或规则；对于业主接受的警告，将其确认信息添加到
period.json中。重新运行。NOT CLEAR 运行的上传文件命名为DO_NOT_UPLOAD_...；每次运行都会先清除前一次运行的输出。 - ALL CLEAR: 将
output/payroll_review_<date>.xlsx、run_summary.html和上传文件发送给业主。指出“发现”和“激励说明”中他们应该注意的内容。业主负责审查和上传；您不参与。
对于高风险运行（第一个实际期间、新地点、规则变更），在移交前请让另一个代理使用 references/auditor.md 审查输出。
5. 更改规则
编辑 payroll_config.json、运行 validate、重新生成规则手册、再次获取业主的批准（approve），然后重新运行该期间。规则手册中的指纹会随着每次规则变更而改变，因此过期的批准会被自动捕获。
查阅指南
| 需要 | 文件 |
|---|---|
| 按行业划分的面试问题，解释每个问题的重要性及已知缺口 | references/questionnaire.md |
| 每个配置字段的说明 | references/config-reference.md |
| 标准CSV输入格式 | references/input-formats.md |
| 映射POS报告（及常见报告陷阱） | references/pos-mapping.md |
| HR和工资系统接入指南 | references/hris-connectors.md |
| 州预设及需要确认的内容 | references/state-rules.md |
| 每个检查关卡和核对存在的原因 | references/lessons.md |
| 独立审查简报 | references/auditor.md |
| 使用水疗和零售样本的首次入门教程 | references/getting-started.md |