Payroll Data Audit

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条——可信度完全不同。

二、异常结论的数据支撑

必须列出具体人员、工号、异常值、预期值、违反的规则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。