小型企業薪資準備
在發薪日前找出錯誤與遺漏。
此技能會將業主的薪資規則，以及其 POS、打卡系統、預約系統和 HR 的匯出資料，轉換為一份已檢查的薪資：一份審閱工作簿、一份證據追蹤鏈，以及供其薪資系統上傳的檔案。它絕不實際提交薪資。員工審閱並提交。
所有操作都透過此技能資料夾中的一個命令列工具執行：
python3 scripts/payroll.py --help # 需要 Python 3.10+ 和 openpyxl（pip install openpyxl）
在其他位置工作時，請使用技能資料夾的絕對路徑來執行，例如 python3 <技能資料夾路徑>/scripts/payroll.py run <週期資料夾>。
基本規則（請先閱讀）
- 只有
payroll.py run能決定「一切無誤」。 退出碼 0 加上output/evidence.json中的"status": "ALL CLEAR"才是唯一的「一切無誤」。切勿根據您自己對數字的解讀，將執行結果描述為乾淨、完成或就緒。退出碼 2 是「未就緒」，退出碼 1 是「受阻」。 - 切勿發明費率、門檻、時間窗或薪資類型名稱。 如果業主尚未告知，請將其留空，以便執行時停止並詢問。猜測的數字會變成實際薪資。
- 業主簽署的規則是執行的法律。 規則變更應寫入
payroll_config.json，然後重新產生並重新批准「薪資規則手冊」。切勿手動編輯工作簿或匯出檔案中的任何數字；請修正輸入或規則，然後重新執行。 - 每個警告都需要一個決定。 每個「警告」都會阻止「一切無誤」，直到輸入被修正，或者有人將確認記錄在
period.json中（acknowledged_warnings，包含決定者和原因）。請勿代替業主確認；必須詢問他們。 - 非法律或稅務建議。 州預設值僅為起點。請告知業主，必須向其薪資供應商或勞動法律師確認加班、最低工資、病假、小費和最終工資規則。
- 勿保留敏感資料。 引擎只需要姓名、ID、費率和工時。切勿要求或儲存社會安全號碼、銀行詳細資訊或出生日期。如果某個匯出檔案包含這些資料，請勿複製那些欄位。
工作區
<工作區>/
payroll_config.json 業主的規則（來自訪談）
PAY_RULES_BOOK.md / .html 以通俗英文撰寫的規則，並附有業主簽核
connectors/ 可選的 HRIS / 薪資設定檔編輯副本
history/weeks.json 已支付的每週工時和加班時數（由執行寫入）
periods/<開始日期>_<結束日期>/
period.json 日期、月度視窗、時間窗、證明、來源、確認
raw/ 完全按原樣下載的匯出檔案
inputs/ 引擎讀取的標準 CSV 檔案
output/ 審閱工作簿、上傳檔案、執行摘要、evidence.json
如果業主想先看看效果，可以嘗試一個虛構的範例：payroll.py sample ./demo（一間水療中心）或 payroll.py sample ./demo --kind retail（一家連鎖店），然後對 demo/periods/ 中的每個週期依序執行 approve ./demo --by "<姓名>"、hris-import 和 run（請參閱 references/getting-started.md）。選擇最接近業主業務類別的範例。
業主的需求決定模式
1. 設定（訪談）
業主尚未有 payroll_config.json，或想要更改員工的薪資方式。
- 詢問他們所屬的行業以及員工的薪資方式（
references/questionnaire.md中的start.1和start.2）。及早告知他們此工具無法處理的需求（該文件中「Not handled yet」欄位）。 - 詢問他們想如何回答其餘問題：由您進行訪談，或使用其行業適用的可填寫訪談工作簿（
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 <工作區>開始。從assets/states/載入州預設值，並讓業主確認它們（references/state-rules.md）。 - 執行
payroll.py validate <工作區>直到顯示 VALID。 - 執行
payroll.py rulebook <工作區>，帶業主逐條檢視每個規則 ID，修正後重新產生。 - 當業主同意時，執行
payroll.py approve <工作區> --by "<業主姓名>"。
2. 開始一個薪資週期
payroll.py new-period <工作區> --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 花名冊、薪資費率和請假：
payroll.py hris-import <週期> --roster <檔案> --time-off <檔案>，使用systems.hris中的設定檔（references/hris-connectors.md）。閱讀output/hris_import_report.md；使用--map field=Header或編輯<工作區>/connectors/中的設定檔副本來修正 FAIL。 - POS 報表：將每個報表映射為標準 CSV（
references/input-formats.md、references/pos-mapping.md）。根據欄位標題文字映射，絕不根據欄位位置。將每個報表及其列印的總計記錄在period.json的sources中，以便執行時能證明沒有任何資料被刪除或重複計算。 - 如果某個輸入在本週期確實沒有任何內容（某個地點無人請假），請在
period.json中記錄一個證明，而不是提供一個空白檔案。
然後執行 payroll.py check <週期>：顯示 READY TO RUN，或需要修正的確切 FAIL。
4. 執行
payroll.py run <週期>。它會執行閘門檢查、計算、核對每個輸入總計與已支付金額、獨立重新計算所有項目（稽核）、與上一期比較，然後寫入薪資檔案，並列印 ALL CLEAR、NOT CLEAR 或 BLOCKED。
- BLOCKED（受阻）： 未計算任何項目。修正 FAIL 行（通常是輸入問題）後重新執行。
- NOT CLEAR（未就緒）： 閱讀原因。修正輸入或規則；對於業主接受的警告，將他們的確認新增到
period.json。重新執行。來自 NOT CLEAR 執行的上傳檔案將命名為DO_NOT_UPLOAD_...；每次執行都會先清除前一次執行的輸出。 - ALL CLEAR（一切無誤）： 將
output/payroll_review_<日期>.xlsx、run_summary.html和上傳檔案發送給業主。指出「發現」和「獎勵備註」中他們應注意的事項。業主審閱並上傳；您不需要。
對於高風險的執行（第一次實際週期、新地點、規則變更），請在移交之前，讓另一個代理使用 references/auditor.md 審閱輸出。
5. 變更規則
編輯 payroll_config.json，驗證，重新產生規則手冊，再次取得業主的批准（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 |