name: payroll-data-audit version: 7.4.0 description: 工資資料稽核系統，基於確定性規則引擎 + Python 指令碼執行。 全量對齊《工資稽核標準流程 SOP》6 步流程。v7.2 修復P0阻斷bug：_get_pay_month() 支援 中文格式（"2026年4月"/"2026年04月"/"202604"），RL-003/RL-007 排除邏輯完全生效。 v7.1 修復5個P0阻斷bug：全形/半形括號統一、RL-003狀態列檢查、RL-007新員工排除+上月1號調薪豁免、FR-003實習生排除、YL-006上月1號豁免。 v6.2 新增總稽核報告（Master Report）、 規則判定過程詳解（judgment）、黃線排除邏輯完善。 v6.2.1 新增編排指南：單節點原則。 Use when user asks to 工資資料稽核、薪資校驗、算薪邏輯驗證、薪酬合規檢查、 工資單稽核、月度薪資校驗、發薪前資料檢查、payroll audit、salary check、 wage verification、payroll compliance. 不適用於非薪酬類資料稽核、純算薪操作（非稽核）、外部薪酬調研、個稅/社保計算. 此技能需手動觸發.

Payroll Data Audit v7.4.1

架構原則：確定性操作下沉到程式碼，模糊推理留給 LLM。AI 不做計算和判斷，只做路由決策和報告翻譯。

概述

工資資料稽核系統，全量對齊《工資稽核標準流程 SOP》6 步流程，對飛書/SAP/ADP 匯出的工資表執行自動化合規校驗。SOP 覆蓋率 95%（41/43 項）。

v6.3 新功能

• RL-003 排除邏輯修復：低於最低工資檢查排除實習生(日薪)、實習生(月薪)、當月入職、當月離職、當月長時間請假（病假>5天或事假>5天）
• RL-004 排除邏輯修復：社保公積金應繳未繳排除實習生(月薪)
• YL-006 誤報修復：非1號轉正/調薪導致的跨月工資變化不再誤報（生效日期在[上月發薪月, 當月發薪月]範圍內自動排除）
• COLUMN_ALIAS 擴充：新增 40+ 個欄位別名變體，覆蓋更多實際工資表列名（如"應發工資合計"、"實發工資"、"個人所得稅扣款"等）
• 連續在職人員環比分析：新增 analyze_continuous_employees() 方法，自動識別連續在職人員，排除實習生/當月入離職/近期調薪轉正/請假>2天/多主體發薪人員，對比12項計薪科目環比變化，自動標記 >10% 異常波動並分類原因
• 場景十·檔案交付（Step 9）：新增 deliver_audit_files.py，11個必發文件清單生成 + 稽核結論摘要自動生成，流水線結束後 Phase 8/8 自動交付準備
• 稽核清單增強：呈現稽核資料情況、通過/不通過原因、判定過程詳解

v6.2 新功能

• 總稽核報告（Master Report）：Phase 7/7，將資料掃描、稽核結果、判定過程、問題清單、抽樣校驗聚合為一份完整的 HTML 總報告（06_master_report.html）
• 規則判定過程詳解（judgment）：每條規則輸出 judgment 欄位，包含規則邏輯、檢查範圍、排除人數及原因、實際檢查人數、通過率、判定結論，讓看報告的人能看到"怎麼判的、排了誰、閾值是什麼"
• 黃線排除邏輯完善：YL-001~004、YL-006 新增實習生/日薪/保潔/當月入職/當月離職排除；YL-005（出勤天數超計薪天數）不排除任何人（資料質量問題全員檢查）

v6.0 新功能

• 表格化報告：整體以表格形式呈現，資訊密度高，替代 v5 的卡片+SVG 風格
• 動態互動看板：支援篩選/排序/搜尋/展開明細/匯出CSV/深色模式（零依賴，純內嵌JS）
• 資料支撐索引：data_index.json 作為報告和看板的關聯核心，保證資料一致性
• 三者聯動：報告 ↔ 看板 ↔ 資料索引，通過 rule_id 雙向錨定

功能範圍

• SOP 第一步（強制）：資料掃描確認（發薪月/公司主體/計薪項/特殊人員/工號重複檢測）
• 欄位完整性檢查（30+ 列名容錯對映）
• 公式校驗（Decimal 精度，0.01 容差）
• 業務邏輯校驗（出勤工資/天數/績效係數/加班/最低工資）
• 紅線校驗（實發≤0、加班超36h、低於最低工資、社保未繳）
• 黃線校驗（績效異常、出勤超限、工資波動）
• 藍線校驗（跨月趨勢，僅提示）
• 政策校驗（道旅國際豁免、15號後入職、實習生/保潔豁免、離職當月社保）
• 人數對比分析（新入職/離職/波動>5%）
• 總額環比分析（12項計薪科目，±10%閾值自動標記）
• 分主體/分四級部門對比（按公司主體分組環比）
• 按人深入分析（連續在職篩選+排除邏輯+六類變化分類+核實標記）
• HTML/Markdown 稽核報告生成
• 資料支撐：每個稽核結論必須有資料依據
• 稽核清單看板：完整條目清單（結果+資料依據+處理建議），HTML+Markdown 雙格式
• 分段稽核：7階段獨立執行，避免上下文截斷，支援斷點續傳
• 抽樣校驗：隨機抽樣+獨立重算+偏差檢測，二次確認稽核結果
• 超連結複核：異常項可點選複核連結（支援 {emp_id}/{emp_name}/{row_index}）
• 端到端流水線：run_full_pipeline.py 一鍵跑完不中斷（資料掃描→稽核→報告→看板→抽樣→問題清單→總稽核報告）

不覆蓋：實際算薪操作、薪酬市場調研、個稅計算、社保核算。

SOP 流程對映

使用

決策路由

先判斷使用者需求屬於哪類場景，再執行對應流程：

場景零：資料掃描確認（⚠️ 強制第一步）

⚠️ 禁止跳過此步驟直接執行稽核！

出報告前必須先資料掃描確認，等待使用者回覆"確認無誤"後才執行後續稽核。

第一步：資料掃描

python3 scripts/data_scan.py \
  --data <工資資料.csv> \
  --output /tmp/data_scan_result.json

掃描輸出以下資訊供使用者確認： - 發薪月分佈（往月/最新發薪月對應人數） - 最新發薪月公司主體列表及對應人數 - 主要計薪項資料（應發合計、實發金額合計、加班費合計、個人社保合計、個人公積金合計） - 特殊欄位識別（實習生人數、保潔人數、入職人數、離職人數、轉正/調薪人數） - 工號重複檢測

資料掃描輸出示例：

============================================================
📊 工資資料掃描報告
============================================================

📋 總記錄數: 2000
📅 最新發薪月: 2026-05

📅 發薪月分佈:
  2026-05: 2000 人 ← 最新
  2026-04: 1980 人

🏢 公司主體分佈:
  道旅科技: 1500 人
  道旅國際: 300 人
  道旅服務: 200 人

💰 主要計薪項彙總:
  應發合計: ¥15,234,567.89
  實發金額合計: ¥12,345,678.90
  加班費小計: ¥234,567.89
  個人社保: ¥1,234,567.89
  個人公積金: ¥987,654.32

👥 特殊人員:
  新入職: 15 人
  離職: 8 人
  轉正: 12 人
  調薪: 5 人

🔍 資料質量檢測:
  工號重複: ✅ 無異常
  姓名為空: ✅ 無異常

============================================================
請確認以上資料是否正確，回覆'確認無誤'後開始正式稽核。
============================================================

第二步：使用者確認

等待使用者回覆"確認無誤"或指出問題。如果使用者指出問題，先修正資料再繼續。

第三步：正式稽核

使用者確認後才執行場景一的完整稽核流程。

場景一：完整稽核（Step 1 → 6）

第一步：獲取資料 — 要求使用者提供本月工資資料檔案（CSV/Excel），必須同時提供上月資料用於跨月對比。

第二步：資料掃描確認 — 見場景零。

第三步：執行稽核

python3 -m scripts.rules_engine \
  --data <本月工資資料.csv> \
  --prev <上月工資資料.csv> \
  --output /tmp/audit_result.json

第四步：確認門 — 如果 summary.blocked == true（觸發紅線），不要生成報告，先輸出紅線清單並要求使用者確認資料修正後再繼續。

第五步：生成報告 — 通過紅線後，用指令碼輸出 JSON 生成人類可讀報告：

python3 scripts/generate_report.py \
  --input /tmp/audit_result.json \
  --format both

輸出檔案：report.html + report.md 在工作目錄。

場景二：快速紅線校驗

python3 -m scripts.rules_engine \
  --data <工資資料.csv> \
  --step red_lines \
  --output /tmp/red_lines_result.json

適用於發薪前快速檢查，只需 10 秒。

場景三：資料梳理（欄位檢查）

python3 -m scripts.rules_engine \
  --data <工資資料.csv> \
  --step fields \
  --output /tmp/fields_result.json

檢查必填欄位是否缺失、格式是否正確。

場景四：公式校驗

python3 -m scripts.rules_engine \
  --data <工資資料.csv> \
  --step formulas \
  --output /tmp/formulas_result.json

驗證應發/實發計算是否與公式一致。

場景五：報告生成

# HTML 視覺化報告
python3 scripts/generate_report.py \
  --input /tmp/audit_result.json --format html --output report.html

# Markdown 報告
python3 scripts/generate_report.py \
  --input /tmp/audit_result.json --format markdown --output report.md

# 兩者都生成
python3 scripts/generate_report.py \
  --input /tmp/audit_result.json --format both

場景六：稽核清單看板（Step 7）

稽核清單看板 = 完整稽核條目展開清單，每條包含稽核結果 + 資料依據 + 處理建議。

python3 scripts/generate_kanban.py --input /tmp/audit_result.json --format both

超連結複核：--review-link "https://hr.example/emp/{emp_id}?row={row_index}" 輸出 kanban.html + kanban.md，展開 rules.json 所有規則（28+條）。

場景七：抽樣校驗（Step 8，推薦）

稽核完成後進行二次確認：python3 scripts/sampling_verify.py --data <資料.csv> --audit <稽核結果.json> --sample-size 30 --threshold 0.05 --output <輸出.json>

流程：隨機抽樣→獨立重算（公式/紅線/業務規則）→交叉對比→偏差率≤5%通過；>5%觸發根因分析後重新稽核。偏差超標時輸出根因報告並使用 run_audit.py --resume 斷點重審。

場景八：分段稽核編排（推薦大數據量場景）

python3 scripts/run_audit.py --data <本月.csv> --prev <上月.csv> --output-dir /tmp/audit_phases

7個獨立階段（欄位→公式→業務規則→紅線阻斷門→黃線→藍線→彙總），每階段輸出獨立 JSON，避免上下文截斷。紅線觸發時自動阻斷後續階段。支援斷點續傳：--resume。

場景九：端到端流水線（一鍵跑完不中斷）

輸出檔案：00_data_scan.json 01_audit_result.json 02_report.html/md 02_report_v6.html/md（表格化，推薦）02a_data_index.json（三者關聯核心）03_kanban.html/md 03_kanban_v6.html（動態互動，推薦）04_sampling_verify.json 05_issue_report.md(問題清單) 06_master_report.html(總稽核報告) audit_summary.md(稽核結論摘要)。

python3 scripts/run_full_pipeline.py --data <本月.csv> --prev <上月.csv> --output-dir /tmp/audit_output --review-link "https://hr.example/emp/{emp_id}?row={row_index}"

場景十：檔案交付到飛書（Step 9，強制）

稽核完成後必須執行此步驟，不可跳過。

python3 scripts/deliver_to_feishu.py --output-dir /tmp/audit_output --audit-result /tmp/audit_output/01_audit_result.json

自動化交付流程（LLM 不可干預、不可跳過）： 1. 驗證檔案完整性 — 檢查 11 個必發文件全部存在，缺失則拒絕執行 2. 上傳檔案到飛書雲盤 — 逐一上傳，輸出上傳結果 3. 建立飛書文件 — 用 02_report_v6.md import 為 docx 格式 4. 生成交付訊息 — 自動生成包含文件連結+檔案清單+總額環比的完整飛書訊息 5. 輸出 delivery_message.md + delivery_result.json — 供 LLM 直接傳送

⚠️ LLM 層唯一職責：把 delivery_message.md 的內容通過訊息工具傳送到飛書。 ⚠️ 禁止：自行挑選檔案上傳、自行建立文件格式、自行裁剪交付內容。

資料來源

• 優先：飛書多維表格匯出 CSV / SAP HCM 匯出 Excel / ADP 匯出
• 降級：要求使用者提供 CSV/Excel 檔案
• 兜底：無任何資料來源時拒絕執行，回覆："請提供工資資料檔案（CSV 或 Excel 格式），我才能進行稽核。"

資料支撐原則

每個稽核結論必須有資料依據，不憑空判斷。 這是稽核系統的核心原則——"稽核通過"不是感覺出來的，是資料算出來的。

一、"通過"結論的資料支撐邏輯

每個判定為"正常/通過"的稽核專案，必須同時輸出以下三項資料：

完整示例： - ✅ 正確："公式校驗通過：2000條記錄全部在0.01元容差範圍內，通過率100%" - ❌ 錯誤："公式校驗通過"（無資料支撐，無法驗證結論可靠性）

為什麼必須這樣：如果沒有檢查數和通過數，"通過"可能是隻檢查了1條、也可能是2000條——可信度完全不同。

7w4.net收錄了海量優質技能外掛。

二、異常結論的資料支撐

必須列出具體人員、工號、異常值、預期值、違反的規則ID：

• ✅ 正確："張三（工號E001）實發金額為-500元，預期值≥0，違反RL-001（實發≤0），嚴重等級：BLOCK"
• ❌ 錯誤："有人實發金額異常"（無具體資訊，無法採取行動）

三、趨勢判斷的資料支撐

必須給出具體數值、變化幅度、驅動因素：

• ✅ 正確："應發總額環比+12.3%（¥15.2M→¥17.1M），超出±10%正常範圍，主要由業務線獎金增加導致（+45.2%，¥2.1M→¥3.0M）"
• ❌ 錯誤："工資總額有明顯增長"（無資料，無法判斷合理性）

四、排除說明的資料支撐

當某人被排除在異常分析外時，必須說明排除原因和依據：

• ✅ 正確："李四（工號E002）應發變化+15.8%，但4月有調薪記錄（調薪生效日期=2026-04-01），匹配排除規則'調薪'，已排除"
• ❌ 錯誤："李四的變化是正常的"（無依據）

五、紅線阻斷的資料支撐

紅線觸發時輸出：觸發人數/具體名單(工號+姓名+異常值)/違反規則(ID+名稱)。 報告"結論與建議"結構：總體結論(檢查數+各維度通過/異常數)→各維度詳情表格(檢查數/通過數/異常數/通過率/結論)→異常明細→建議行動(基於具體資料)。

列名容錯

指令碼內建 COLUMN_ALIAS 字典，自動對映 30+ 種常見列名變體。如果列名無法識別，指令碼返回 {"error": "Missing column: XXX"}，LLM 必須原文轉述。

精度處理

金額計算使用 decimal.Decimal，避免浮點誤差累積。公式校驗容差 0.01（1 分錢）。

規則更新

所有規則集中在 references/rules.json。修改規則只需編輯此檔案，無需修改指令碼。為什麼這樣設計：業務規則變化頻繁（如最低工資調整），集中管理避免每次都要改程式碼。

如何擴充套件規則

1. 新增紅線：在 rules.json 的 red_lines 陣列中新增新物件，包含 id、name、condition、field、severity: "BLOCK"
2. 新增黃線：在 yellow_lines 陣列中新增，action: "flag_and_explain"
3. 新增藍線：在 blue_lines 陣列中新增，action: "note_only"
4. 新增政策：在 policies 陣列中新增，包含 condition（觸發條件）和 effect（豁免效果）
5. 新增業務規則：在 business_rules 陣列中新增，支援 field1 <= field2 類雙欄位比較
6. 新增排除條件：在 person_analysis_exclusions 物件中新增新 key，包含 field、condition、note

規則 ID 命名規範：{型別}-{序號}，如 RL-005（第5條紅線）、YL-007（第7條黃線）、POL-006（第6條政策）、BR-005（第5條業務規則）

新增規則後不需要修改任何 Python 程式碼，引擎自動載入。

紅線阻斷

紅線觸發 → 立即阻斷，不繼續後續步驟，不生成報告。為什麼：紅線代表嚴重違規（如負實發、低於最低工資），必須先修正資料再稽核，否則報告無意義。

編排指南：單節點原則（v6.2.1 新增）

本 Skill 被 Workflow Orchestration Skill 編排時，必須作為單節點呼叫。

根因：run_full_pipeline.py 已是端到端流水線，內部按序完成所有 8 步（掃描→規則→紅黃藍線→報告→看板→抽樣→問題清單→總報告）。拆成多節點編排無收益——每個節點仍呼叫同一個 skill，內部全量執行一遍。

唯一例外：當業務確實需要中間狀態可見性或獨立重試時，才使用 run_audit.py 分段模式（7階段+斷點續傳），但仍然是同一 skill 的多次呼叫，不是拆成多個 skill。

常見錯誤場景

目錄結構

payroll-data-audit/
├── SKILL.md
├── _meta.json
├── scripts/
│   ├── data_scan.py               # 資料掃描（SOP 第一步）
│   ├── rules_engine.py            # 統一規則引擎（OOP）
│   ├── generate_report.py         # HTML/Markdown 報告生成器（v5，相容）
│   ├── generate_report_v6.py      # 表格化報告生成器（v6，推薦）
│   ├── generate_kanban.py         # 稽核清單看板生成器（Step 7，靜態）
│   ├── generate_kanban_v6.py      # 動態互動看板生成器（v6，推薦）
│   ├── generate_data_index.py     # 資料支撐索引生成器（v6，三者關聯核心）
│   ├── run_audit.py               # 分段稽核編排器（7階段+斷點續傳）
│   ├── run_full_pipeline.py       # 端到端流水線（含 v6 輸出 + 總報告）
│   ├── generate_master_report.py  # 總稽核報告生成器（v6.2，聚合所有輸出）
│   ├── sampling_verify.py         # 抽樣校驗器（二次確認）
│   ├── deliver_audit_files.py     # 檔案交付清單生成器（v6.3，僅生成清單，已廢棄）
│   ├── deliver_to_feishu.py       # 檔案交付到飛書（v7.4，自動上傳+文件+訊息，推薦）
│   └── tests/                     # pytest 測試套件
│       ├── test_rules_engine.py
│       └── test_parameterized.py
├── references/
│   └── rules.json                 # 所有規則宣告（唯一真相來源）
└── .github/workflows/
    └── test.yml                   # CI/CD

依賴

pip install pandas numpy openpyxl

測試

cd payroll-data-audit
python -m pytest scripts/tests/ -v --cov=scripts.rules_engine --cov-report=term-missing

CI/CD 自動執行：push/PR 時觸發 pytest + coverage（80% 門檻）+ lint。

這個Skill質量不錯，專業度高，能完整稽核工資資料並生成詳細報告。規則覆蓋全面，支援紅線阻斷和異常預警，資料支撐清晰可追溯。主要優點是自動化程度高、流程規範；不足是交付檔案太多（11個），且依賴飛書服務可能存在資料安全風險。普通使用者需要一定培訓才能上手使用。