Payroll Data Audit

SKILL.md

---
name: payroll-data-audit
version: 5.0.1
description: 工资数据审核系统，基于确定性规则引擎 + Python 脚本执行。
  Use when user asks to 工资数据审核、薪资校验、算薪逻辑验证、薪酬合规检查、
  工资单审核、月度薪资校验、发薪前数据检查、payroll audit、salary check、
  wage verification、payroll compliance.
  不适用于非薪酬类数据审核、纯算薪操作（非审核）、外部薪酬调研、个税/社保计算.
  此技能需手动触发.
---

# Payroll Data Audit v5.0.0

**架构原则**：确定性操作下沉到代码，模糊推理留给 LLM。AI 不做计算和判断，只做路由决策和报告翻译。

## 概述

工资数据审核系统，全量对齐《工资审核标准流程 SOP》6 步流程，对飞书/SAP/ADP 导出的工资表执行自动化合规校验。SOP 覆盖率 95%（41/43 项）。

### 功能范围

- 字段完整性检查（30+ 列名容错映射）
- 姓名/工号重复检测
- 公式校验（Decimal 精度，0.01 容差）
- 红线校验（实发≤0、加班超36h、低于最低工资、社保未缴）
- 黄线校验（绩效异常、出勤超限、工资波动）
- 蓝线校验（跨月趋势，仅提示）
- 政策校验（实习生豁免、离职当月社保、道旅国际社保/公积金豁免）
- 人数对比分析（新入职/离职/波动>5%）
- 总额环比分析（12项计薪科目，±10%阈值自动标记）
- 分主体/部门对比（按公司主体分组环比）
- 按人深入分析（连续在职筛选+排除逻辑+六类变化分类+核实标记）
- HTML/Markdown 审核报告生成

**不覆盖**：实际算薪操作、薪酬市场调研、个税计算、社保核算。

## 使用

### 决策路由

先判断用户需求属于哪类场景，再执行对应流程：

| 用户说的 | 匹配场景 | 执行 |
|---------|---------|------|
| "帮我审核本月工资数据" | 完整审核 (Step 1→6) | `run_full_audit` |
| "快速看看有没有问题" | 红线校验 | `--step red_lines` |
| "发薪前帮我理一下数据" | 字段检查 | `--step fields` |
| "帮我验一下公式对不对" | 公式校验 | `--step formulas` |
| "帮我出个审核报告" | 报告生成 | `generate_report.py` |

### 场景一：完整审核（Step 1 → 6）

**第一步：获取数据** — 要求用户提供本月工资数据文件（CSV/Excel），可选上月数据用于跨月对比。

**第二步：执行审核**

```bash
python3 -m scripts.rules_engine \
  --data <本月工资数据.csv> \
  --prev <上月工资数据.csv> \
  --output /tmp/audit_result.json
```

**第三步：确认门** — 如果 `summary.blocked == true`（触发红线），**不要生成报告**，先输出红线清单并要求用户确认数据修正后再继续。

**第四步：生成报告** — 通过红线后，用脚本输出 JSON 生成人类可读报告：

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

**输出文件**：`report.html` + `report.md` 在工作目录。

### 场景二：快速红线校验

```bash
python3 -m scripts.rules_engine \
  --data <工资数据.csv> \
  --step red_lines \
  --output /tmp/red_lines_result.json
```

适用于发薪前快速检查，只需 10 秒。

### 场景三：数据梳理（字段检查）

```bash
python3 -m scripts.rules_engine \
  --data <工资数据.csv> \
  --step fields \
  --output /tmp/fields_result.json
```

检查必填字段是否缺失、格式是否正确。

### 场景四：公式校验

```bash
python3 -m scripts.rules_engine \
  --data <工资数据.csv> \
  --step formulas \
  --output /tmp/formulas_result.json
```

验证应发/实发计算是否与公式一致。

### 场景五：报告生成

```bash
# 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
```

## 补充说明

### 数据来源

- **优先**：飞书多维表格导出 CSV / SAP HCM 导出 Excel / ADP 导出
- **降级**：要求用户提供 CSV/Excel 文件
- **兜底**：无任何数据源时拒绝执行，回复："请提供工资数据文件（CSV 或 Excel 格式），我才能进行审核。"

### 列名容错

脚本内置 `COLUMN_ALIAS` 字典，自动映射 30+ 种常见列名变体。
如果列名无法识别，脚本返回 `{"error": "Missing column: XXX"}`，LLM 必须原文转述。

### 精度处理

金额计算使用 `decimal.Decimal`，避免浮点误差累积。公式校验容差 0.01（1 分钱）。

### 规则更新

所有规则集中在 `references/rules.json`。修改规则只需编辑此文件，无需修改脚本。
**为什么这样设计**：业务规则变化频繁（如最低工资调整），集中管理避免每次都要改代码。

### 红线阻断

红线触发 → 立即阻断，不继续后续步骤，不生成报告。
**为什么**：红线代表严重违规（如负实发、低于最低工资），必须先修正数据再审核，否则报告无意义。

### 常见错误场景

| 场景 | 处理 |
|------|------|
| 数据源字段缺失 | 列出缺失字段清单，要求用户补充后重试 |
| 日期格式混乱 | 脚本自动尝试多种格式解析，失败则返回错误 |
| 无上月数据 | 跨月对比/按人分析跳过，在报告中标注"无基准数据" |
| Python 环境无 pandas | 提示用户 `pip install pandas numpy openpyxl` |
| 红线触发 | 立即阻断，输出红线清单，要求用户修正后重跑 |

### 依赖安装

```bash
pip install pandas numpy openpyxl pytest
```

### 测试

```bash
cd payroll-data-audit
python3 -m pytest scripts/tests/ -v
```

56 个测试全部通过。CI/CD 自动运行：push/PR 时触发 pytest + coverage（80% 门槛）+ lint。

### 踩坑记录

- **fillna(None) 不兼容新版 pandas** → 所有 fillna 统一用 `fillna(0)`
- **df[mask] 索引不对齐** → mask 创建时必须用 `pd.Series(..., index=df.index)` 确保索引一致
- **空数据阻塞流程** → `run_full_audit` 开头增加空数据快速返回
- **YL-005 规则字段名不匹配** → 使用 `实际计薪出勤天数 > 应计薪出勤天数` 而非 `班天数合计`
- **RL-004 字段缺失时仍触发** → 字段不存在时跳过，不报误判