如何开发人事及OA管理系统的薪酬管理板块？（附架构图+流程图+代码参考）

diff
+----------------------------------------------------------+
|                        前端 (Vue/React)                  |
|  - 企业薪酬看板  - 个人薪酬看板  - 导入/发起计算页面      |
+----------------------------------------------------------+
|                   API 网关 (鉴权/限流/日志)              |
+----------------------------------------------------------+
|                      后端服务层（微服务）                |
|  - 员工服务 (HR Master)                                  |
|  - 薪酬核算服务 (Salary Engine)                          |
|  - 导入服务 (Excel/CSV)                                  |
|  - 审批服务 (OA Flow)                                    |
|  - 报表/看板服务                                         |
|  - 支付/对账服务                                         |
+----------------------------------------------------------+
|                      存储层                              |
|  - 关系 DB (MySQL/Postgres)    - 报表/OLAP (ClickHouse)   |
|  - 对象存储 (S3)               - 缓存 (Redis)            |
+----------------------------------------------------------+
|                      外部系统                            |
|  - 考勤系统、ERP/财务、银行接口、社保/公积金局接口        |
+----------------------------------------------------------+

markdown
1. 系统管理员/HR 配置：薪资项、社保规则、个税规则、薪资模板
2. HR 导入本期数据：考勤、加班、奖金（Excel/接口）
3. HR 发起模拟计算（Salary Engine） -> 生成模拟结果供校验
4. HR 调整异常项 -> 发起正式计算 -> 生成工资批次
5. 审批流：HR -> 部门经理 -> 财务（可配置并行或串行）
6. 发放：导出银行文件 / 对接支付 -> 标记为已支付
7. 归档：生成工资条 PDF，保存到对象存储并写入 salary_lines.payslip_url
8. 报表更新：同步到 OLAP，用于看板展示

sql
-- 员工主数据
CREATE TABLE employees (
  id BIGSERIAL PRIMARY KEY,
  emp_no VARCHAR(64) UNIQUE NOT NULL,
  name VARCHAR(128) NOT NULL,
  dept_id BIGINT,
  bank_account VARCHAR(64),
  tax_id VARCHAR(64),
  insurance_base NUMERIC(12,2), -- 五险一金基数
  special_deductions JSONB, -- 专项附加扣除明细
  salary_template_id BIGINT, -- 指向薪资模板
  created_at TIMESTAMP DEFAULT now(),
  updated_at TIMESTAMP DEFAULT now()
);
-- 薪资项定义
CREATE TABLE salary_items (
  id BIGSERIAL PRIMARY KEY,
  code VARCHAR(64) UNIQUE NOT NULL, -- e.g. BASIC, PERF, OVERTIME
  name VARCHAR(128) NOT NULL,
  type VARCHAR(16) NOT NULL, -- 'income'|'deduction'
  calc_expr TEXT, -- 表达式或引用脚本
  sort_order INT DEFAULT 0,
  created_at TIMESTAMP DEFAULT now()
);
-- 员工薪资结构（模板/绑定）
CREATE TABLE employee_salary_struct (
  id BIGSERIAL PRIMARY KEY,
  emp_id BIGINT REFERENCES employees(id),
  salary_item_code VARCHAR(64),
  amount NUMERIC(12,2),
  is_variable BOOLEAN DEFAULT false,
  created_at TIMESTAMP DEFAULT now()
);
-- 工资批次
CREATE TABLE salary_batches (
  id BIGSERIAL PRIMARY KEY,
  batch_no VARCHAR(128) UNIQUE NOT NULL,
  month DATE NOT NULL, -- 工资月份
  status VARCHAR(32) DEFAULT 'draft', -- draft|simulated|pending_approval|approved|paid
  created_by BIGINT,
  created_at TIMESTAMP DEFAULT now()
);
-- 工资明细
CREATE TABLE salary_lines (
  id BIGSERIAL PRIMARY KEY,
  batch_id BIGINT REFERENCES salary_batches(id),
  emp_id BIGINT REFERENCES employees(id),
  gross_amount NUMERIC(12,2),
  total_deduction NUMERIC(12,2),
  net_amount NUMERIC(12,2),
  details JSONB, -- 各薪资项明细 [{code, name, amount}]
  payslip_url TEXT,
  status VARCHAR(32) DEFAULT 'draft',
  created_at TIMESTAMP DEFAULT now()
);
-- 审计日志
CREATE TABLE audit_logs (
  id BIGSERIAL PRIMARY KEY,
  user_id BIGINT,
  action VARCHAR(128),
  target_type VARCHAR(64),
  target_id BIGINT,
  payload JSONB,
  created_at TIMESTAMP DEFAULT now()
);

js
// routes/salaryItems.js
const express = require('express');
const router = express.Router();
const { SalaryItem } = require('../models');
router.post('/', async (req, res) => {
  const { code, name, type, calc_expr } = req.body;
  const item = await SalaryItem.create({ code, name, type, calc_expr });
  res.json({ success: true, item });
});
router.get('/', async (req, res) => {
  const items = await SalaryItem.findAll({ order: [['sort_order','ASC']] });
  res.json(items);
});
module.exports = router;

js
// 给指定员工添加固定项
await EmployeeSalaryStruct.create({ emp_id: 1001, salary_item_code: 'BASIC', amount: 8000, is_variable: false });
// 更新专项附加扣除（JSON）
await Employee.update({ special_deductions: JSON.stringify({ children_education: 1000 }) }, { where: { id: 1001 }});

js
const xlsx = require('xlsx');
function parseImport(filePath) {
  const wb = xlsx.readFile(filePath);
  const sheet = wb.Sheets[wb.SheetNames[0]];
  const rows = xlsx.utils.sheet_to_json(sheet);
  // columns: emp_no, overtime_hours, bonus, deduction
  return rows;
}
// Express 接口
router.post('/import-and-calc', async (req, res) => {
  const { filePath, month } = req.body;
  const rows = parseImport(filePath);
  const batch = await SalaryBatch.create({ batch_no: `BATCH-${Date.now()}`, month, status: 'draft', created_by: req.user.id });
  // 异步触发计算（可以用队列）
  salaryEngine.calculateBatch(batch.id, rows);
  res.json({ success: true, batchId: batch.id });
});

js
// salaryEngine.js
const { Employee, EmployeeSalaryStruct, SalaryLine, SalaryBatch } = require('./models');
function round2(v){ return Math.round(v*100)/100; }
// 简化个税计算（演示用，不要直接用于生产）
function calcIndividualTax(taxable) {
  if (taxable <= 0) return 0;
  if (taxable <= 3000) return taxable * 0.03;
  if (taxable <= 12000) return taxable * 0.1 - 210;
  if (taxable <= 25000) return taxable * 0.2 - 1410;
  if (taxable <= 35000) return taxable * 0.25 - 2660;
  return taxable * 0.3;
}
async function calculateEmployeeSalary(emp, importRow, socialConfig) {
  let details = [];
  let gross = 0;
  // 基本工资
  const base = await EmployeeSalaryStruct.findOne({ where: { emp_id: emp.id, salary_item_code: 'BASIC' }});
  const basic = base ? parseFloat(base.amount) : 0;
  gross += basic; details.push({ code: 'BASIC', name: '基础工资', amount: basic });
  // 绩效
  const perf = (await EmployeeSalaryStruct.findOne({ where: { emp_id: emp.id, salary_item_code: 'PERF' }}))?.amount || 0;
  gross += parseFloat(perf); details.push({ code: 'PERF', name: '绩效', amount: parseFloat(perf) });
  // 加班按小时计算示例
  const overtimeHours = parseFloat(importRow.overtime_hours || 0);
  const overtimePay = overtimeHours * ((basic/21.75)/8) * 1.5; // 示例公式
  gross += overtimePay; details.push({ code: 'OVERTIME', name: '加班费', amount: round2(overtimePay) });
  // 奖金
  const bonus = parseFloat(importRow.bonus || 0); gross += bonus; details.push({ code: 'BONUS', name: '奖金', amount: bonus });
  // 社保/公积金（个人部分）
  const insBase = emp.insurance_base || basic;
  const pension = insBase * (socialConfig.pension_person || 0);
  const medical = insBase * (socialConfig.medical_person || 0);
  const housing = insBase * (socialConfig.housing_person || 0);
  const totalInsurance = round2(pension + medical + housing);
  details.push({ code: 'SOCIAL_PERSON', name: '个人社保', amount: -totalInsurance });
  // 专项附加扣除
  const special = parseFloat(emp.special_deductions?.total || 0);
  if (special) details.push({ code: 'SPECIAL', name: '专项附加扣除', amount: -special });
  // 应纳税所得额：应税 = gross - 个人社保 - 专项 - 免税额（示例免税额3500）
  const taxFree = socialConfig.tax_free_quota || 3500;
  const taxable = gross - totalInsurance - special - taxFree;
  const tax = round2(calcIndividualTax(taxable));
  details.push({ code: 'TAX', name: '个人所得税', amount: -tax });
  const net = round2(gross - totalInsurance - special - tax);
  return { gross_amount: round2(gross), total_deduction: round2(totalInsurance + special + tax), net_amount: net, details };
}
async function calculateBatch(batchId, importRows) {
  const batch = await SalaryBatch.findByPk(batchId);
  // 假设 socialConfig 从系统设置获取
  const socialConfig = { pension_person: 0.08, medical_person: 0.02, housing_person: 0.07, tax_free_quota: 5000 };
  for (const row of importRows) {
    const emp = await Employee.findOne({ where: { emp_no: row.emp_no }});
    if (!emp) continue;
    const result = await calculateEmployeeSalary(emp, row, socialConfig);
    await SalaryLine.create({
      batch_id: batchId, emp_id: emp.id, gross_amount: result.gross_amount,
      total_deduction: result.total_deduction, net_amount: result.net_amount, details: JSON.stringify(result.details), status: 'simulated'
    });
  }
  await batch.update({ status: 'simulated' });
}
module.exports = { calculateBatch, calculateEmployeeSalary };
要点：
在真实场景中，建议用队列分批处理（如用 RabbitMQ / Bull / Celery），并行计算大量员工。
每次计算时记录使用的社保与税率配置版本 ID。

js
const PDFDocument = require('pdfkit');
const fs = require('fs');
function generatePayslip(salaryLine, outPath) {
  const doc = new PDFDocument({ margin: 40 });
  doc.pipe(fs.createWriteStream(outPath));
  doc.fontSize(16).text(`工资条 - ${salaryLine.emp_name}`, { align: 'center' });
  doc.moveDown();
  doc.fontSize(12).text(`月份: ${salaryLine.pay_month}`);
  doc.text(`部门: ${salaryLine.dept_name}`);
  doc.moveDown();
  doc.text('明细：');
  salaryLine.details.forEach(it => {
    const sign = it.amount >= 0 ? '' : '-';
    doc.text(`${it.name} (${it.code}): ${it.amount.toFixed(2)}`);
  });
  doc.moveDown();
  doc.text(`实发工资: ${salaryLine.net_amount.toFixed(2)}`, { align: 'right' });
  doc.end();
}