Bitzsoft.Integrations.EkuaiBao 1.0.0-alpha.7

Bitzsoft.Integrations.EkuaiBao

合思易快报费控系统集成客户端 — REST API 封装、OAuth Token 自动注入、批量操作分片。

功能特性

• REST API 全覆盖 — 封装 68+ 个端点，涵盖员工、部门、角色、自定义档案、费用报销、供应商、发票、附件、支付管理、借款管理、凭证汇率、审批流等模块
• OAuth Token 自动注入 — 内置 DelegatingHandler 自动获取并附加 AccessToken，调用方无需手动管理认证
• 批量操作自动分片 — 超过 BatchSize 的批量请求自动拆分执行，遵守合思 API 单次上限
• Resilience Pipeline — 基于 Microsoft.Extensions.Http.Resilience 内置标准重试与熔断策略
• Typed Client 模式 — 通过 IHttpClientFactory 管理 HttpClient 生命周期，避免端口耗尽
• DataAnnotations 验证 — 配置选项支持声明式校验，启动时即发现配置错误
• 第三方请求日志 — 内置 RequestLogging DelegatingHandler，记录所有出站 HTTP 请求与响应，便于问题排查
• 自定义 Token 存储 — 通过 IEkuaiBaoTokenProvider 抽象 Token 缓存与凭证获取，宿主层自由选择存储方案

安装

dotnet add package Bitzsoft.Integrations.EkuaiBao

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

配置

{
  "EkuaiBao": {
    "BaseUrl": "https://app.ekuaibao.com",
    "TimeoutSeconds": 30,
    "BatchSize": 190
  }
}

注册服务

using Bitzsoft.Integrations.EkuaiBao;
using Bitzsoft.Integrations.EkuaiBao.DependencyInjection;

// 方式一：使用默认配置
services.AddBitzsoftEkuaiBao();

// 方式二：自定义配置
services.AddBitzsoftEkuaiBao(options =>
{
    options.BaseUrl = "https://app.ekuaibao.com";
    options.TimeoutSeconds = 60;
    options.BatchSize = 100;
});

// 方式三：同时扩展 HttpClient 管道
services.AddBitzsoftEkuaiBao(
    configureOptions: options => options.TimeoutSeconds = 60,
    configureClient: builder =>
    {
        builder.AddHttpMessageHandler<MyCustomHandler>();
    });

// 必须注册 IEkuaiBaoTokenProvider 实现
services.AddScoped<IEkuaiBaoTokenProvider, MyTokenProvider>();

注意：AddBitzsoftEkuaiBao 会注册 IEkuaiBaoClient（Typed Client）和 EkuaiBaoOptions（支持 DataAnnotations 验证）。调用前需先注册 IEkuaiBaoTokenProvider 实现。

IEkuaiBaoTokenProvider

宿主层必须实现此接口以提供 Token 缓存与凭证获取能力：

public interface IEkuaiBaoTokenProvider
{
    Task<string?> GetCachedTokenAsync(string tenantId, CancellationToken ct = default);
    Task SetTokenAsync(string tenantId, string token, CancellationToken ct = default);
    Task<(string AppKey, string AppSecret)> GetCredentialsAsync(string tenantId, CancellationToken ct = default);
    string GetCurrentTenantId();
}

第三方请求日志

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

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

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

使用示例

批量创建员工

using Bitzsoft.Integrations.EkuaiBao;
using Bitzsoft.Integrations.EkuaiBao.Inputs;

public class EmployeeSyncService
{
    private readonly IEkuaiBaoClient _client;

    public EmployeeSyncService(IEkuaiBaoClient client)
    {
        _client = client;
    }

    public async Task SyncEmployeesAsync(CancellationToken ct)
    {
        // 构建员工列表（超过 BatchSize 时自动分片执行）
        var employees = new List<StaffsCreateInput.Staff>
        {
            new()
            {
                Name = "张三",
                Code = "EMP001",
                Cellphone = "13800138001",
                Email = "zhangsan@example.com",
                DefaultDepartment = " dept-001",
                Departments = new List<string> { "dept-001" }
            },
            new()
            {
                Name = "李四",
                Code = "EMP002",
                Cellphone = "13800138002",
                Email = "lisi@example.com",
                DefaultDepartment = "dept-002",
                Departments = new List<string> { "dept-002" }
            }
        };

        // 自动按 BatchSize 分片，无需手动拆分
        var result = await _client.BatchCreateStaffsAsync(employees, ct);

        Console.WriteLine($"成功创建 {result.Count} 名员工");
    }
}

分页查询费用报销单

using Bitzsoft.Integrations.EkuaiBao;

public class ExpenseQueryService
{
    private readonly IEkuaiBaoClient _client;

    public ExpenseQueryService(IEkuaiBaoClient client)
    {
        _client = client;
    }

    public async Task QueryRecentExpensesAsync(CancellationToken ct)
    {
        var page = 1;
        var pageSize = 50;
        var offset = EkuaiBaoPaging.ToOffset(page, pageSize);

        // 按创建时间倒序查询报销单
        var result = await _client.GetApplyListAsync(
            start: offset,
            count: pageSize,
            userId: null,
            type: "expense",
            orderByCreateTime: true,
            ct: ct);

        Console.WriteLine($"共 {result.Count} 条报销单，当前页 {result.Items.Count} 条");

        // 获取单据详情
        if (result.Items.Any())
        {
            var detail = await _client.GetApplyDetailAsync("flowId-001", ct);
        }
    }
}

发票验真与 OCR 识别

using Bitzsoft.Integrations.EkuaiBao;
using Bitzsoft.Integrations.EkuaiBao.Inputs;

public class InvoiceService
{
    private readonly IEkuaiBaoClient _client;

    public InvoiceService(IEkuaiBaoClient client)
    {
        _client = client;
    }

    public async Task ValidateAndOcrAsync(CancellationToken ct)
    {
        // 发票 OCR 识别
        var ocrResult = await _client.RecognizeInvoiceOcrAsync(
            "https://example.com/invoice.pdf", ct);

        // 发票验真
        var validateResult = await _client.ValidateInvoiceAsync(
            new InvoiceValidateInput
            {
                // 填入验真参数
            },
            ct);
    }
}

审批单据

using Bitzsoft.Integrations.EkuaiBao;
using Bitzsoft.Integrations.EkuaiBao.Inputs;

public class ApprovalService
{
    private readonly IEkuaiBaoClient _client;

    public ApprovalService(IEkuaiBaoClient client)
    {
        _client = client;
    }

    public async Task ApproveAsync(string flowId, CancellationToken ct)
    {
        // 审批通过
        var result = await _client.ApproveFlowsAsync(
            flowIds: flowId,
            input: new FlowApprovalInput
            {
                // 填入审批参数
            },
            ct: ct);
    }
}

API 一览

相关包

• Bitzsoft.Integrations.TencentCcc — 腾讯云呼叫中心集成客户端
• Bitzsoft.Integrations.Beisen — 北森 HRP 系统集成客户端
• Bitzsoft.Integrations.All — 全部集成包聚合引用