Bitzsoft.Integrations.Xft 1.0.0-alpha.7

Bitzsoft.Integrations.Xft

薪福通（XFT）一站式人财事数字开放平台集成客户端。

功能特性

本包对接招商银行薪福通开放平台，提供以下业务域的完整 API 访问能力：

• 国密签名：内置 XftSignHandler 自动使用 SM2/SM3/SM4 算法签名，调用方无需处理签名细节
• 第三方请求日志：内置 RequestLogging DelegatingHandler，记录所有出站 HTTP 请求与响应，便于问题排查
• 事件回调解析：XftEventParser 解析薪福通平台推送的事件回调

Phase 1: 公共服务 (5 APIs)

• XftPublicServiceProvider — 公共服务

Phase 2: HR 基础域 (84 APIs)

• XftOrganizationProvider — 组织管理
• XftUserProvider — 用户管理
• XftEmployeeProvider — 员工管理
• XftPermissionProvider — 权限管理

Phase 3: 薪资社保域 (98 APIs)

• XftPayrollProvider — 薪资管理
• XftSmartSalaryProvider — 智能薪资
• XftAttendanceProvider — 考勤管理
• XftBatchAccountProvider — 批量账户
• XftElectronicPayslipProvider — 电子工资单

Phase 4: 财务税务域 (169 APIs)

• XftFinanceProvider — 财务管理
• XftTaxFilingProvider — 税务申报
• XftTaxCloudProvider — 税务云

Phase 5: 费控与办公域 (225 APIs)

• XftExpenseControlProvider — 费控管理
• XftApprovalProvider — 审批流程
• XftMessageProvider — 消息通知
• XftUnionBenefitProvider — 工会福利

Phase 6: 其他域 + 事件回调 (28 APIs)

• XftCustomerProvider — 客户管理
• XftPartnerProvider — 合作伙伴
• XftLowCodeProvider — 低代码
• XftOpenServiceProvider — 开放服务
• XftEventParser — 事件回调解析（Singleton）

安装

dotnet add package Bitzsoft.Integrations.Xft

<PackageReference Include="Bitzsoft.Integrations.Xft" Version="*" />

配置

{
  "Xft": {
    "AppKey": "薪福通提供的 AppKey",
    "AppSecret": "双方约定的 AppSecret",
    "BaseUrl": "https://open.xft.cmbchina.com",
    "EnterpriseId": "企业 ID"
  }
}

注册服务

using Bitzsoft.Integrations.Xft;

services.AddBitzsoftXft(configuration);

或使用代码配置：

services.AddBitzsoftXft(options =>
{
    options.AppKey = "your-app-key";
    options.AppSecret = "your-app-secret";
    options.BaseUrl = "https://open.xft.cmbchina.com";
    options.EnterpriseId = "your-enterprise-id";
});

第三方请求日志

内置 Bitzsoft.Integrations.RequestLogging 出站请求记录管道，默认使用 NullRequestLogStore 不持久化。

// ① 默认：启用记录管道但不持久化（日志丢弃）
services.AddBitzsoftXft(options => { /* ... */ });

// ② 持久化：宿主注册 IRequestLogStore 实现后，所有出站请求自动落库
services.AddRequestLogging<MyRequestLogStore>(opts =>
{
    opts.MaxBodyLength = 8192;
    opts.SensitiveFields.Add("mySecret");
});
services.AddBitzsoftXft(options => { /* ... */ });

签名机制

本包自动处理薪福通 API 的签名流程：

• 使用 SM2/SM3/SM4 国密算法进行签名
• 通过 XftSignHandler 自动为请求添加签名
• 支持 XftHttpClient 的 Typed HttpClient 模式

事件回调

使用 XftEventParser 解析薪福通平台推送的事件回调：

var eventParser = serviceProvider.GetRequiredService<XftEventParser>();
var xftEvent = await eventParser.ParseAsync(requestBody);

目标框架

• .NET 5.0
• .NET 8.0
• .NET 10.0

相关包

外部依赖

• BouncyCastle.Cryptography — 国密算法支持（SM2/SM3/SM4）