Bitzsoft.Integrations.Beisen 1.0.0-alpha.7

Bitzsoft.Integrations.Beisen

北森 HR 系统集成客户端 — REST API 封装、OAuth Token 管理、双管道认证（Token + Cookie）、多租户配置。

功能特性

• 全模块 API 覆盖 — 聚合组织人事、员工花名册、任职记录、职位/职务、合同协议、假勤管理（打卡/考勤/休假/加班/出差/公出/调休假/工时/排班/日历）、数据源、元数据等 25 个操作接口
• 双管道认证 — 核心业务接口使用 Token 认证，元数据接口使用 Cookie 认证，由 SDK 自动路由
• 多租户支持 — 通过 IBeisenOptionsProvider 按租户动态解析配置，IBeisenClientFactory.Create(tenantId) 创建租户隔离的客户端
• 滚动分页 — StreamEmployeesByTimeWindowAsync、StreamOrgUnitsByTimeWindowAsync 等方法基于 IAsyncEnumerable，内置安全上限防止无限循环
• Resilience 管道 — 两个 HttpClient 管道均内置标准重试与熔断策略
• 员工全生命周期 — 新增、入职、调动、离职、退休、转正、子集管理等写操作
• 第三方请求日志 — 内置 RequestLogging DelegatingHandler，记录所有出站 HTTP 请求与响应，便于问题排查
• 结构化异常 — BeisenException 携带 BeisenErrorCode、HTTP 状态码、API 原始错误码和请求 URL

安装

dotnet add package Bitzsoft.Integrations.Beisen

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

配置

{
  "Beisen": {
    "BaseUrl": "https://openapi.italent.cn",
    "MetadataBaseUrl": "https://open.italent.cn",
    "AppKey": "{{BEISEN_APP_KEY}}",
    "AppSecret": "{{BEISEN_APP_SECRET}}",
    "Cookie": "{{BEISEN_COOKIE}}",
    "TimeoutMs": 30000,
    "TokenCacheMinutes": 110,
    "DefaultScrollCapacity": 100,
    "MaxScrollItems": 50000
  }
}

注册服务

using Bitzsoft.Integrations.Beisen;

// 基本注册（单租户）
services.AddTNTBeisen(options =>
{
    options.AppKey = "your-app-key";
    options.AppSecret = "your-app-secret";
    options.Cookie = "your-cookie-for-metadata";
});

// 必须注册 IBeisenTokenStore 和 IBeisenCookieStore 实现
services.AddSingleton<IBeisenTokenStore, RedisBeisenTokenStore>();
services.AddSingleton<IBeisenCookieStore, RedisBeisenCookieStore>();

// 多租户场景：不传 configure，注册自定义 IBeisenOptionsProvider
services.AddTNTBeisen();
services.AddSingleton<IBeisenOptionsProvider, TenantBeisenOptionsProvider>();
services.AddSingleton<IBeisenTokenStore, RedisBeisenTokenStore>();
services.AddSingleton<IBeisenCookieStore, RedisBeisenCookieStore>();

第三方请求日志

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

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

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

使用示例

同步员工数据

using Bitzsoft.Integrations.Beisen;

public class EmployeeSyncService
{
    private readonly IBeisenClientFactory _factory;

    public EmployeeSyncService(IBeisenClientFactory factory)
    {
        _factory = factory;
    }

    public async Task SyncAsync(DateTime startTime, DateTime stopTime, CancellationToken ct)
    {
        using var client = _factory.Create();

        // 按时间窗口流式拉取员工数据（滚动分页，内存友好）
        var input = new EmployeeTimeWindowInput
        {
            StartTime = startTime,
            StopTime = stopTime,
            Columns = ["Name", "Email", "MobilePhone", "Status", "OrgUnit"]
        };

        await foreach (var employee in client.StreamEmployeesByTimeWindowAsync(input, ct))
        {
            // 逐条处理员工数据
            Console.WriteLine($"员工: {employee}");
        }
    }

    public async Task<StaffSearchResult?> FindByEmailAsync(string email, CancellationToken ct)
    {
        using var client = _factory.Create();

        var result = await client.GetStaffByEmailAsync(email, ct);
        return result;
    }
}

查询考勤记录

using Bitzsoft.Integrations.Beisen;

using var client = _factory.Create();

// 查询考勤数据
var attendance = await client.GetAttendanceRecordsAsync(
    new AttendanceQueryInput
    {
        UserIds = [10001, 10002],
        StartDate = "2024-12-01",
        EndDate = "2024-12-31"
    });

foreach (var record in attendance)
{
    Console.WriteLine($"用户: {record.UserId}, 日期: {record.Date}, 状态: {record.Status}");
}

// 查询休假数据
var leaves = await client.GetLeavesAsync(
    new LeaveQueryInput
    {
        UserIds = [10001],
        StartDate = "2024-12-01",
        EndDate = "2024-12-31"
    });

foreach (var leave in leaves)
{
    Console.WriteLine($"用户: {leave.UserId}, 类型: {leave.LeaveType}, 开始: {leave.StartTime}");
}

// 查询假期余额
var balances = await client.GetLeaveBalancesByUserIdAsync(userId: 10001);
foreach (var balance in balances)
{
    Console.WriteLine($"假期: {balance.LeaveName}, 余额: {balance.Balance}");
}

多租户使用

using Bitzsoft.Integrations.Beisen;

// 通过工厂创建指定租户的客户端
using var client = _factory.Create(tenantId: "tenant-001");

// 搜索部门
var departments = await client.SearchDepartmentsAsync(
    new DepartmentSearchInput { PageSize = 100 });

// 流式搜索全部员工
await foreach (var staff in client.StreamStaffsAsync(
    new StaffSearchInput { PageSize = 200, Status = 1 }))
{
    Console.WriteLine($"员工: {staff.Name}");
}

相关包