Overtime Pay Calculator

---
name: overtime-pay-calculator
description: >-
  专注劳动法领域的加班工资智能计算技能。根据用户提供的案件信息、内置计算公式、各地最低工资标准数据及联网检索，精准计算各类工时制下的加班工资，生成规范计算明细表，并附带法条引用与实务法律建议。当用户询问加班费、加班工资怎么算、标准工时制、综合计算工时制、不定时工时制、计件工资制、日工资/小时工资折算、劳动仲裁加班费等场景时触发。输出格式可根据用户需求灵活调整，不强制输出Excel。
metadata:
  version: 1.0.0
---

# 加班工资计算

## 触发场景

当用户描述以下场景时触发本技能：

- 加班费、加班工资怎么算
- 工作日加班、休息日加班、法定节假日加班工资
- 标准工时制、综合计算工时制、不定时工时制加班费
- 计件工资加班费、计件加班工资
- 日工资、小时工资折算、月计薪天数
- 21.75天怎么算、工资折算
- 1.5倍、2倍、3倍加班费计算
- 平时加班、周末加班、节假日加班
- 试用期加班工资
- 加班费计算器、加班工资明细表格
- 拖欠加班费、克扣加班工资维权
- 劳动仲裁加班费、加班费证据规则

## 技能说明

本技能专用于劳动法领域**加班工资**的精准计算。覆盖标准工时制、综合计算工时制、不定时工时制、计件工资制四类工时制度下的加班工资计算，以及日工资/小时工资的折算。

计算加班工资的核心前提是**确定基本工资**（月工资基数）。

调用时须严格遵循以下工作流程。

---

## 数据源优先级（严格执行）

1. **[优先] 政策数据 API**：通过 `calc_engine.py` 请求 `OVERTIME_POLICY_API_URL` 配置的加班工资政策数据 API。API 只返回政策数据，不计算金额。
2. **[按需兜底] web_search 联网检索**（总轮数不超过2轮）：仅当当前计算分支已经明确、且 API 未返回该分支必需的政策字段时触发。
   - 最低工资校验需要 `min_wage`。
   - 工资折算需要 `worktime_params.monthly_paid_days` 和 `worktime_params.hours_per_day`。
   - 综合工时计算需要 `worktime_params.cycle_standard_hours`。
   - 计算结论需要法条依据时需要 `law_basis`。
   - 涉及地方工资基数规则时需要 `local_wage_base_rule`。
3. **[计算说明] References**：`references/formulas.md` 仅用于公式、倍率规则、字段含义和边界说明，不作为优先于 API 的政策数据源。
4. **[禁止] 严禁凭空编造数据**：API、缓存和网络均无法找到当前计算所需政策数据时，告知用户"该地区该项标准暂缺，建议致电当地人社局12333咨询"，绝不套用其他省份数据。

### API 配置

### 配置步骤

1. 前往 [https://open.delilegal.com/personal/keys](https://open.delilegal.com/personal/keys) 注册/登录
2. 创建应用并获取 API Key
3. 将 API Key 填入技能目录下的 `config.json` 文件：
   ```json
   {
     "apikey": "你的API Key"
   }
   ```

> ⚠️ **未配置 API Key 时**，不得执行检索，必须先提示用户：
> "config.json 中的 apikey 尚未配置。请前往 https://open.delilegal.com/personal/keys 创建 API Key，并填入技能目录下的 config.json 文件中。"

### web_search 使用规则

- **硬性上限**：单次计算任务中，web_search 调用**累计不超过2轮**。
- 第1轮检索未命中目标数据时，可换关键词再搜1轮。2轮均未果则停止，按第4条兜底处理。
- 每次检索前须明确当前计算分支缺少的具体政策字段，避免无效搜索。
- API 已返回当前计算分支所需政策数据时，不因“可能有更新”而主动联网检索。
- 用户事实信息缺失时先追问用户，不用 web_search 代替用户提供工资、加班时长、工时制度、是否补休等事实。
- 联网检索只用于补齐政策数据；公式、倍率、金额计算仍交由 `calc_engine.py` 完成。

---

## 交互策略：漏斗式提问与追问机制

### 基本原则

- **不要一次性提问所有内容**，按分支递进采集信息
- 先根据已有信息判断工时制度和加班类型，再有针对性地追问缺失字段
- 如信息严重不足无法计算，先说明能算什么、需要什么，再请用户提供

### 必采信息矩阵

**通用必采（所有案件，首轮确认）：**

- 工时制度类型：
  - 标准工时制（默认）
  - 综合计算工时制
  - 不定时工时制
  - 计件工资制
- 月工资基数（计算核心，详见下方「月工资基数确定」）
- 加班时间信息（至少包含以下之一）：
  - 工作日延长工作时间（小时数/天数）
  - 休息日加班（小时数/天数，是否安排补休）
  - 法定节假日加班（小时数/天数）
- 加班发生的时间段（起止月份，用于计算周期判断）

**月工资基数确定（计算核心，必须确认）：**

月工资基数 = 劳动合同约定工资 + 奖金 + 津贴 + 补贴 + 加班工资

不包含：非常规性福利（如独生子女补贴、交通意外补贴等）

用户可选以下任一方式提供：
- 直接报月工资数
- 提供年薪 ÷ 12
- 提供近12个月工资总额 ÷ 月数
- 提供各月工资明细，由AI计算平均

> **最低工资保障**：月工资基数不得低于当地最低工资标准。计算前须先确认当地标准。

**综合计算工时制追加：**
- 综合计算周期（周/月/季/年）
- 周期内正常工作日总工作小时数
- 周期内总实际工作小时数
- 法定节假日加班小时数（如有）

**计件工资制追加：**
- 计件单价（元/件）
- 正常工作时间完成的定额产量
- 加班期间完成的产量
- 加班类型（工作日/休息日/法定节假日）

**不定时工时制追加：**
- 是否存在法定节假日加班（不定时工时制仅需计算法定节假日3倍工资）
- 法定节假日加班小时数

### 追问触发规则

> **核心：哪个字段影响计算、当前未知，就追问哪个字段。**

| 缺失字段 | 影响模块 | 追问话术示例 |
|---------|---------|------------|
| 工时制度 | 计算方式和适用公式 | "请问您实行的是哪种工时制度？标准工时制（每天8小时/每周40小时）/综合计算工时制/不定时工时制/计件工资制？" |
| 月工资基数 | 所有加班费计算 | "请问您的月工资是多少？（包括基本工资+奖金+津贴+补贴等，不含非常规性福利）" |
| 加班时段/时长 | 确定倍率和计算基数 | "请问加班发生的时间段是？工作日延长（1.5倍）/休息日（2倍）/法定节假日（3倍），各多少小时/天？" |
| 休息日是否补休 | 休息日加班费是否发放 | "休息日加班后，单位是否安排了补休？（已安排补休的，休息日加班无需支付加班费）" |
| 综合工时周期 | 超出法定工作时间的部分 | "请问综合计算工时制的计算周期是多长？（周/月/季/年），周期内总工时多少？" |

**追问时机：**
- 首轮用户信息不全 → 先列出已采集字段，再集中追问**当前分支所需的缺失字段**（不超过3-4个/轮）
- 切勿一次追问全部字段；优先追问影响金额最大的字段
- 追问应简洁，提供选项或示例格式，降低用户填写难度

---

## 核心计算模块

### 政策数据获取与计算说明

`scripts/calc_engine.py` 的计算 action 会在入参包含 `region`、`province` 或 `city` 时通过 `scripts/policy_data.py` 获取政策数据。`policy_data.py` 会先读取本地 `.policy_cache/{normalized_region}__{date}.json` 文件缓存；缓存不存在时再携带 `config.json` 中的 `apikey` 请求统一政策数据 API，并优先使用返回的 `worktime_params`、`min_wage` 和 `law_basis`。也可显式附带 `policy_data` 字段用于测试或外部编排。

`references/formulas.md` 仅作为计算公式、倍率规则和边界说明参考；最低工资和法条依据不再从 references Markdown 读取。

### scripts 可调用操作清单

运行原则：
- `scripts/policy_data.py` 请求统一接口 `POST /api/v1/skill/calculator`，请求体由脚本自动包装为 `{"resource_type":"overtime-pay-calculator","payload":<原payload>}`。
- `scripts/calc_engine.py` 的入参必须包含 `action`；涉及地区最低工资、工时政策或法条依据时，传 `region` 让脚本加载政策数据，或显式传 `policy_data`。
- 月计薪天数、小时工资折算、加班倍率和 Excel 样式由脚本实现；`SKILL.md` 只负责选择 action、补齐输入和输出解释。

`scripts/policy_data.py` 支持：

| action | 用途 | 关键入参 |
|--------|------|----------|
| `api_snapshot` / `fetch_api_snapshot` / `policy_data` | 获取最低工资、工时参数、地方工资基数规则、节假日规则和法条依据 | `region`、`date` |

`scripts/calc_engine.py` 支持：

| action | 用途 | 关键入参 | 是否需要 `policy_data` |
|--------|------|----------|------------------------|
| `wage_conversion` | 月工资折算日工资、小时工资 | `monthly_wage` | 否 |
| `standard_overtime` | 标准工时制加班费 | `hourly_wage`、`weekday_hours`、`restday_hours`、`holiday_hours` | 否 |
| `comprehensive_overtime` | 综合计算工时制加班费 | `hourly_wage`、`cycle_hours`、`actual_hours`、`holiday_hours` | 否 |
| `irregular_overtime` / `irregular_working_hours_overtime` | 不定时工时制加班费 | `hourly_wage`、`holiday_hours`，可选 `region` | 条件需要 |
| `piece_rate_overtime` | 计件工资制加班费 | `piece_price`、`weekday_qty`、`restday_qty`、`holiday_qty` | 否 |
| `min_wage_lookup` | 查询最低工资 | `region`、`date` | 是 |
| `minimum_wage_check` | 校验工资是否低于当地最低工资 | `monthly_wage`；另需 `local_min_wage` 或 `policy_data.min_wage` | 条件需要 |
| `export_to_excel` | 导出加班费明细 Excel | `rows` 或 `detail_rows`，可选 `output_path` | 否 |

### scripts 命令生成规范

生成命令时必须使用仓库根目录相对路径，不要省略 `python3`，不要调用已删除的 references 动态数据文件。

```bash
python3 labor-fee-calculator/overtime-pay-calculator/scripts/policy_data.py '{"action":"api_snapshot","region":"上海市","date":"2025-01-01"}'
```

```bash
python3 labor-fee-calculator/overtime-pay-calculator/scripts/calc_engine.py '{"action":"wage_conversion","monthly_wage":12000}'
```

复杂 JSON 或完整 `policy_data` 优先使用 `@文件`：

```bash
python3 labor-fee-calculator/overtime-pay-calculator/scripts/calc_engine.py @/absolute/path/to/payload.json
```

命令生成校验规则：
- JSON 顶层必须是对象，且必须包含 `action`。
- JSON 使用双引号，整段 JSON 在 shell 中用单引号包裹；布尔值使用 JSON 的 `true` / `false`。
- 需要政策数据的 action，应传 `region` 让脚本自动获取，或把 `policy_data.py` 响应中的 `body` 放入 `calc_engine.py` 入参的 `policy_data` 字段。
- `calc_engine.py` 与 `policy_data.py` 成功时输出均应包含 `"success": true` 和 `"body"`。
- 命令生成后，应优先用 `python3 -m py_compile` 或实际执行命令做冒烟验证。

### 前置模块：月工资基数确定与日工资/小时工资折算

使用 `wage_conversion` 折算日工资和小时工资。涉及最低工资校验时使用 `minimum_wage_check` 或先通过 `min_wage_lookup` 获取当地最低工资。

> 注意：试用期工资不得低于本单位相同岗位最低档工资或劳动合同约定工资的80%，且不得低于当地最低工资标准。

### 模块1：标准工时制加班工资

适用每日8小时、每周40小时的标准工时制度，使用 `standard_overtime`。需区分工作日延长、休息日、法定节假日三类时长。

> **关键规则**：休息日加班，用人单位安排补休的，不再支付加班费；未安排补休的，支付200%加班费。法定节假日加班，不得以补休替代，必须支付300%加班费。

### 模块2：综合计算工时制加班工资

适用经劳动行政部门批准的综合计算工时制度，使用 `comprehensive_overtime`。需确认综合周期、周期法定标准工时、实际工时和法定节假日工时；脚本负责超时部分和节假日部分的计算。

### 模块3：不定时工时制加班工资

适用经劳动行政部门批准的不定时工时制度，使用 `irregular_overtime` 或 `irregular_working_hours_overtime`。需确认是否有地方特殊规定及法定节假日工作时长。

> **注意**：不定时工时制下，仅法定节假日加班需支付3倍工资。但须注意：部分地区（如上海、深圳）对不定时工时制的加班费有地方性特殊规定，如有地方规定应优先适用。计算时须查询用户所在地是否有特殊规定。

### 模块4：计件工资制加班工资

适用实行计件工资且已完成计件定额任务后的加班，使用 `piece_rate_overtime`。需分别提供工作日、休息日、法定节假日的加班产量。

> **前提条件**：计件加班费的适用前提是劳动者**已完成计件定额任务**，超出定额部分的加班产量才按倍率计算。

### 模块5：举证责任与仲裁时效（实务参考）

**举证规则：**
- 加班事实的举证责任原则上由**劳动者**承担
- 劳动者须提供：考勤记录、加班审批单、工作邮件/微信记录、工资条等
- 用人单位掌握考勤记录的（保存期限不少于2年），**用人单位**有举证义务
- 超过2年的加班事实，由劳动者举证

**仲裁时效：**
- 劳动争议申请仲裁的时效期间为**1年**，从当事人知道或者应当知道其权利被侵害之日起计算
- 劳动关系存续期间因拖欠加班费发生争议的，劳动者申请仲裁不受1年时效限制
- 劳动关系终止的，应当自劳动关系终止之日起1年内提出

---

## 加班费计算基数常见问题

月工资基数需结合劳动合同、工资流水、地方规则和用户实际收入组成判断。存在地区特殊规则时，优先使用 `policy_data.local_wage_base_rule`；政策数据缺失且当前分支确需该字段时，再进入最多两轮联网检索，并在输出中注明来源。

一般应重点核实：正常工作时间工资、奖金/津补贴是否计入、加班工资是否应剔除、社保公积金等单位负担项目是否应排除。不要在 `SKILL.md` 中硬编码地区静态表，具体规则以政策数据或检索结果为准。

---

## 输出格式规范

### 核心要素（必须包含，顺序和形式可灵活调整）

1. **计算标准说明**：说明采用的工时制度类型、月工资基数、日工资/小时工资折算过程
2. **计算明细表**（Markdown 表格）：每项加班费独占一行，含「加班类型 | 加班时长 | 计算过程 | 金额（元）| 法条依据」五列
3. **法条依据**：列出支撑各计算项目的核心法条（从 `policy_data.law_basis` 调取）
4. **最终应支付加班费总额**：汇总金额
5. **免责声明**（固定模板，每次必须输出）：

> **免责声明**：以上计算结果仅供参考，所采用的工资基数、计算标准可能随法规修订或地方政策调整而更新。最终加班费金额须根据实际证据情况（考勤记录、工资流水等）及仲裁委员会/人民法院的裁决确定，本计算结果不构成法律意见。

### 灵活调整原则

- **用户仅询问某几项**（如只问法定节假日加班费）：只输出相关模块，不强制展开全部内容
- **用户需要完整报告**：按上述核心要素依次输出，表格之外可附必要文字说明
- **实务建议**（可选，不超过3条）：如案件有特殊情形（如举证困难、时效问题、地方特殊规定等），可在末尾附简要实务提示

### Excel 文件（可选，非强制）

仅在用户明确要求导出 Excel 时生成，使用 Python（calc_engine.py）的 `export_to_excel` 函数。

Excel 样式和列结构由脚本负责，文档输出保持简洁。

**无需 Excel 的情形**：用户仅口头询问估算金额、进行场景讨论、或明确表示不需要文件时，直接在对话中输出 Markdown 明细表即可，无需生成文件。

---

## 防幻觉提示

- 政策数据必须来自政策数据 API/cache 或 web_search 结果，不得凭空填写；`references/formulas.md` 仅用于公式说明
- 月计薪天数固定为 **21.75天**（人社部发〔2025〕2号，计算方式：(365-104)÷12），不得使用其他数值
- 加班费倍率（1.5/2/3）为法定最低标准，实际合同约定高于此标准的，从其约定
- 休息日加班可用补休替代，法定节假日加班不可用补休替代——此规则须在计算结果中明确标注
- web_search 返回的数据须标注来源（如"据XX人社局官网"），便于用户核验