TurboHR/docs/payroll-batch-algorithm.md

多批次工资发放算法

一、整体流程

创建批次 → 拉入员工/复制数据 → 计算每个员工薪资 → 编辑调整 → 归档批次 → 生成工资条

一个月份可以有多个批次（如第1批常规发薪、第2批离职结算、第3批奖金），每个批次独立计算，归档后汇总生成一张工资条。

核心约束：当月存在未归档（DRAFT）的批次时，不允许创建新批次，确保个税按批次累计计算。

二、批次类型

类型	code	社保公积金	个税方式
常规发薪	REGULAR	正常扣缴	累计预扣法
离职结算	TERMINATION	正常扣缴	累计预扣法
年终奖/奖金	BONUS	不扣	单独计税
补偿金	SEVERANCE	不扣	累计预扣法

三、创建批次（POST /batches）

3.1 前置校验

• 当月存在 DRAFT 状态的批次时，拒绝创建，返回错误"当月存在未归档的批次，请先归档后再创建新批次"
• 确保新批次创建时，之前所有批次均已归档（已生成工资条），保证个税累计计算正确

3.2 确定批次号

取当月最大 batchNo + 1，避免删除批次后 count 不准导致唯一键冲突（@@unique([orgId, month, batchNo])）。

3.3 四种初始化模式

模式	说明
copy_last	拉入在职员工，从上月工资条复制基本工资/津贴/扣款，自动取当月加班费
blank_employees	拉入在职员工，所有金额为0，仅从员工档案取基本工资
blank_all	空批次，不拉入员工，后续手动添加
copy_batch	从指定已归档批次复制员工和薪资数据

3.4 员工范围

• 常规发薪（REGULAR）：status = ACTIVE + 当月离职员工（status = RESIGNED 且 updatedAt 在当月）
• 离职结算/补偿金（TERMINATION/SEVERANCE）：当月有离职记录（terminationDate 在当月）的员工

3.5 社保公积金扣缴逻辑（按员工个人、按实际金额）

对每个员工独立判断：
  1. 计算当月应缴社保公积金全额（基于社保基数和配置）
  2. 查询该员工当月已归档的常规/离职批次中已扣的社保公积金累计金额
  3. 本批次应扣 = max(0, 应缴全额 - 已扣金额)
     - 已扣金额 = 0 → 本批次扣全额
     - 已扣金额 < 应缴全额 → 本批次补扣差额
     - 已扣金额 ≥ 应缴全额 → 本批次扣0（足额）

规则：

• 按员工个人维度、按实际金额计算，而非全局判断是否扣过
• 第1批：员工A扣全额社保 → 归档后 → 第2批中员工A已扣金额=全额，应扣=0；员工B未在第1批中，已扣=0，应扣=全额
• BONUS 和 SEVERANCE 批次本身不扣社保
• 用户可手动编辑覆盖社保值

四、单条目计算（calcBatchEntry）

4.1 应发合计

totalPay = baseSalary + overtimePay + allowance + bonus - deduction

4.2 社保公积金计算

基数：优先用员工核定基数（employee.socialInsBase / employee.housingFundBase），否则用基本工资

社保（calcSocialInsurance）：

• 养老/失业/工伤：基数 × 各自比例
• 医疗/生育：独立基数（medicalBaseMin/Max，fallback 到统一基数）
• 附加险种：支持固定金额或按比例

公积金（calcHousingFund）：

• 基数 × housingEmp%（个人）/ housingOrg%（单位）

跳过条件：

• batchType = BONUS 或 SEVERANCE → 不扣
• skipSocial = true（同月已有归档常规批次）→ 不扣
• overrideSocial 手动覆盖 → 用用户输入值

4.3 个税计算

年终奖批次（BONUS）— 单独计税：

monthlyBonus = bonus / 12
→ 查税率表确定 rate 和 quickDeduction
→ tax = bonus × rate - quickDeduction

月均奖金	税率	速算扣除数
≤3000	3%	0
≤12000	10%	210
≤25000	20%	1410
≤35000	25%	2660
≤55000	30%	4410
≤80000	35%	7160
>80000	45%	15160

其他批次（REGULAR/TERMINATION/SEVERANCE）— 累计预扣法：

1. 查询该员工当年所有已归档批次的 BatchEntry（不依赖工资条是否已生成）
2. 累计收入 = Σ 已归档批次.totalPay + 本批次.totalPay
3. 累计社保 = Σ 已归档批次.socialEmp + 本批次.socialEmp
4. 累计公积金 = Σ 已归档批次.housingEmp + 本批次.housingEmp
5. 累计专项扣除 = employee.specialDeduction × 月份序号
6. 累计应纳税所得额 = max(0, 累计收入 - 5000×月份 - 累计社保 - 累计公积金 - 累计专项扣除)
7. 累计税额 = calcTax(累计应纳税所得额)  // 查7级超额累进税率表
8. 当月应预扣 = max(0, 累计税额 - Σ 已归档批次.tax)

7级超额累进税率表：

累计应纳税所得额	税率	速算扣除数
≤36000	3%	0
≤144000	10%	2520
≤300000	20%	16920
≤420000	25%	31920
≤660000	30%	52920
≤960000	35%	85920
>960000	45%	181920

4.4 实发工资

netPay = totalPay - socialEmp - housingEmp - tax

五、添加/删除员工后更新汇总

添加或删除员工后，重新查询所有条目并汇总更新批次：

employeeCount = 条目数
totalPay = Σ entry.totalPay
totalNetPay = Σ entry.netPay
totalTax = Σ entry.tax
totalSocialEmp = Σ entry.socialEmp
totalSocialOrg = Σ entry.socialOrg
totalHousingEmp = Σ entry.housingEmp
totalHousingOrg = Σ entry.housingOrg

六、编辑条目后重算

• 合并用户修改的输入项（baseSalary/overtimePay/allowance/deduction/bonus）
• 重新调用 calcBatchEntry（含 skipSocial 逻辑）
• 如果用户手动输入了社保值，用 overrideSocial 优先
• 更新条目后重新汇总批次

七、归档批次（POST /batches/:batchId/archive）

• 将批次状态改为 ARCHIVED，记录 archivedAt
• 归档后批次锁定不可编辑、不可删除
• 当月存在未归档批次时，不允许创建新批次

八、取消归档（POST /batches/:batchId/unarchive）

• 将批次状态从 ARCHIVED 恢复为 DRAFT，清除 archivedAt
• 只能依次取消：只能取消最后一个归档批次（按 batchNo 倒序），确保个税累计链不断裂
• 取消归档后处理工资条：
  • 当月已无归档批次 → 删除该月所有相关员工的工资条（完全撤销个税累计）
  • 当月仍有归档批次 → 基于剩余归档批次重新生成工资条（更新累计数据）

九、生成工资条（POST /payslips/generate）

8.1 汇总归档批次

1. 获取当月所有 ARCHIVED 批次
2. 按员工ID分组，累加所有批次的各项金额：
   baseSalary, overtimePay, allowance, deduction, bonus,
   socialEmp, socialOrg, housingEmp, housingOrg, tax, totalPay, netPay

8.2 生成/更新工资条

upsert(employeeId + month)：
  - 各项金额 = 多批次汇总值
  - ytdIncome = Σ 历史工资条.totalPay + 当月汇总.totalPay
  - ytdTaxDeducted = Σ 历史工资条.tax + 当月汇总.tax
  - ytdSocialEmp, ytdHousingEmp 同理
  - status = PUBLISHED

8.3 唯一约束

Payslip 有 @@unique([employeeId, month])，同一员工同月只有一条工资条，多次生成会覆盖更新。

九、多批次场景示例

场景1：常规工资 + 奖金

步骤	批次1（REGULAR）	批次2（BONUS）
创建	拉入员工，复制上月数据	空白批次，手动添加人员
社保	正常扣缴	不扣
个税	累计预扣（含历史工资条）	单独计税
归档	归档	归档
生成工资条	汇总批次1+2 → 一张工资条

场景2：常规工资 + 补发常规工资

步骤	批次1（REGULAR）	批次2（REGULAR）
创建	拉入员工，正常计算	拉入员工，skipSocial=true
社保	正常扣缴	跳过（同月已有归档常规批次）
个税	累计预扣（含历史）	累计预扣（含历史+批次1的工资条）
归档	归档	归档
生成工资条	汇总批次1+2 → 一张工资条，社保只算一次，个税累计

场景3：常规工资 + 离职结算

步骤	批次1（REGULAR）	批次2（TERMINATION）
创建	拉入在职员工	拉入当月离职员工
社保	正常扣缴	跳过（同月已有归档常规批次）
个税	累计预扣	累计预扣（含批次1的工资条）
归档	归档	归档
生成工资条	汇总批次1+2 → 一张工资条

十、关键代码位置

模块	文件	行号
创建批次	backend/src/routes/payroll2.routes.ts	220
单条目计算	backend/src/services/payroll.service.ts	126
社保计算	backend/src/services/payroll.service.ts	37
公积金计算	backend/src/services/payroll.service.ts	69
累计预扣个税	backend/src/services/payroll.service.ts	97
年终奖计税	backend/src/services/payroll.service.ts	108
编辑条目	backend/src/routes/payroll2.routes.ts	435
添加员工	backend/src/routes/payroll2.routes.ts	504
删除员工	backend/src/routes/payroll2.routes.ts	585
归档批次	backend/src/routes/payroll2.routes.ts	662
生成工资条	backend/src/services/payroll.service.ts	275