Bitzsoft.Integrations.Finance.Payroll 1.0.0-alpha.10

Bitzsoft.Integrations.Finance.Payroll

薪酬社保服务抽象层 -- 定义薪资计算、个税计算、薪资代发、社保管理、工资单推送等统一接口与基础模型。

功能特性

• 一站式薪酬能力：单接口 IPayrollProvider 覆盖薪资计算、个税计算、薪资代发、社保（参保 / 停保 / 申报）、工资单推送五大场景
• 代发批次模型：SalaryDisbursementRequest 支持多员工批次代发，SalaryDisbursementResult 暴露总笔数 / 成功 / 失败计数与 DisbursementStatus 状态机
• 累计预扣个税：TaxCalculationRequest 支持累计收入、专项附加扣除、社保公积金扣除与免征额（默认 5000），返回税率与速算扣除数
• 社保全周期：参保（EnrollAsync）、停保（SuspendAsync）、申报（DeclareAsync）统一为 SocialInsuranceRequest / Result
• 能力降级约定：受限于供应商 API，部分操作可能抛 NotSupportedException，调用方按需确认能力
• 领域异常：PayrollException 派生自 FinanceException，统一携带供应商名称与错误码

安装

.NET CLI

dotnet add package Bitzsoft.Integrations.Finance.Payroll

PackageReference

<PackageReference Include="Bitzsoft.Integrations.Finance.Payroll" Version="1.0.0" />

配置

本包为抽象层，不定义 Options 类，不读取配置节。各供应商的配置项由实现包定义。

注册服务

本包为抽象层，ServiceCollectionExtensions 仅作命名空间占位，不提供具体注册方法。具体供应商的注册由实现包或聚合包提供：

// 薪酬社保聚合包（详见聚合包文档）
using Bitzsoft.Integrations.Finance.Payroll.All;

services.AddBitzsoftPayrollAll(configuration);

或直接使用专用集成包，如 Bitzsoft.Integrations.Xft（薪福通）。

使用示例

计算薪资

using Bitzsoft.Integrations.Finance.Payroll.Interfaces;
using Bitzsoft.Integrations.Finance.Payroll.Models;

public class PayrollService
{
    private readonly IPayrollProvider _payroll;

    public PayrollService(IPayrollProvider payroll) => _payroll = payroll;

    public async Task<PayrollCalculationResult> RunAsync(string employeeId, string period)
    {
        var request = new PayrollCalculationRequest
        {
            EmployeeId = employeeId,
            Period = period,                 // 格式 yyyy-MM
            BaseSalary = 10000m,
            PerformanceBonus = 2000m,
            AdditionalItems =
            [
                new() { Name = "交通补贴", Amount = 500m }
            ]
        };

        var result = await _payroll.CalculateAsync(request);
        // result.GrossAmount           -- 应发金额
        // result.NetAmount             -- 实发金额
        // result.TaxAmount             -- 个人所得税额
        // result.SocialInsuranceAmount -- 社保个人部分
        // result.HousingFundAmount     -- 公积金个人部分
        return result;
    }
}

薪资代发并轮询结果

var disburse = await _payroll.DisburseAsync(new SalaryDisbursementRequest
{
    BatchId = "B2026070001",
    Period  = "2026-07",
    Items =
    [
        new() { EmployeeId = "E001", EmployeeName = "张三",
                BankAccount = "6222...", BankName = "工商银行", Amount = 11500m }
    ]
});

// 轮询批次状态
var status = await _payroll.GetDisbursementStatusAsync(disburse.BatchId);
// status.Status       -- DisbursementStatus（Submitted/Processing/Completed/...）
// status.SuccessCount -- 成功笔数

社保参保

await _payroll.EnrollAsync(new SocialInsuranceRequest
{
    EmployeeId     = "E001",
    EmployeeName   = "张三",
    IdCardNumber   = "110...",
    CityCode       = "440100",   // 广州
    BaseAmount     = 8000m,      // 社保基数
    OperationMonth = "202607"    // 格式 yyyyMM
});

核心类型一览

接口（位于 Interfaces/）

IPayrollProvider 方法分组

模型与枚举（位于 Models/）

依赖

相关包

• Bitzsoft.Integrations.Finance.Payroll.All -- 薪酬社保聚合包
• Bitzsoft.Integrations.Xft -- 薪福通一站式人财事数字开放平台集成客户端（直接集成）
• Bitzsoft.Integrations.Finance -- 财税管理公共基础
• Bitzsoft.Integrations.Finance.All -- 财税管理全量聚合包