Bitzsoft.Integrations.Fxiaoke 1.0.0-alpha.10

Bitzsoft.Integrations.Fxiaoke

纷享销客 OpenAPI v2 多租户只读连接器，提供对象元数据、受控对象查询、深分页和 可恢复同步，支持 net5.0、net8.0 与 net10.0。

安装

dotnet add package Bitzsoft.Integrations.Fxiaoke

已实现能力

• 企业自建应用 appId + appSecret + permanentCode 令牌交换；
• 按租户、endpoint profile、凭据和企业云隔离的 single-flight token 缓存；
• 官方纷享、华为、阿里、香港华为、法兰克福和北美企业云；
• authorization、x-fs-ea、x-fs-userid 公共参数；
• 对象清单、对象描述、预设对象和自定义对象查询；
• 固定 _id 排序的 keyset 深分页；
• Full 与基于 last_modified_time 的 Incremental Sync；
• token 过期码 20016 下，仅对只读调用刷新并重放一次。

凭据与权限

生产宿主必须提供加密、按租户解析的 IIntegrationCredentialResolver，凭据字段为：

AppId
AppSecret
PermanentCode

ActingUserId 是非密钥业务身份，应写入请求上下文或同步 profile，不应与应用密钥混存。 应用权限、数据范围和代调用员工权限均由纷享销客租户配置决定；首次上线需用目标角色 验证对象与字段可见性。

注册

services.AddBitzsoftFxiaoke(
    new FxiaokeEndpoint(FxiaokeCloud.Standard),
    new[]
    {
        new FxiaokeObjectSyncProfile(
            streamName: "Accounts",
            objectApiName: "AccountObj",
            actingUserId: "1001",
            fieldProjection: new[] { "name", "last_modified_time" })
    });

端点或同步 profile 随租户变化时，实现 IFxiaokeEndpointResolver 与 IFxiaokeObjectSyncProfileResolver，使用 AddBitzsoftFxiaoke<TEndpointResolver, TSyncProfileResolver>()。

查询示例

var context = new FxiaokeRequestContext(
    tenantId: "customer-a",
    actingUserId: "1001",
    profileId: "production",
    credentialName: "fxiaoke-app");

var objects = await client.ListObjectsAsync(context, cancellationToken);
var metadata = await client.DescribeObjectAsync(
    context,
    "AccountObj",
    cancellationToken: cancellationToken);

var page = await client.QueryObjectsAsync(
    context,
    new FxiaokeObjectQuery(
        objectApiName: "AccountObj",
        pageSize: 100,
        fieldProjection: new[] { "name", "last_modified_time" }),
    cancellationToken);

分页边界由响应的记录 ID 生成，调用方不要自行改写 _id 排序或混用不同对象、租户、 profile、字段形状的游标。自定义过滤必须使用 FxiaokeQueryFilter，连接器不接受任意 供应商查询 JSON。

同步语义

• Full 在运行开始固定 _id 上界，避免无限追逐新写入；
• Incremental 使用闭合 last_modified_time 上界；
• 下界使用 GTE，因此属于至少一次投递，Sink 必须按 Id + Revision 幂等；
• 可见的 is_deleted 转为 tombstone；
• continuation 只推进当前运行，完整结束后才提交新的 delta 水位；
• 不同 StreamName 应分别表示客户、联系人、订单或自定义对象。

纷享销客没有通用对象删除变更流。对象从查询结果彻底消失时无法仅靠增量发现，生产任务 必须周期性执行 Full reconcile。

安全、日志与限制

• OAuth token 请求和响应正文显式禁止进入审计日志；
• 普通业务请求和响应正文完整传递，不设置连接器级或 RequestLogging 强制大小上限；
• 错误只暴露稳定错误码、分类和可安全诊断信息，不保留供应商原始错误正文；
• 自动重放只用于 token 失效后的只读请求；
• 当前不包含写操作、Webhook 或通用幂等写入；
• 厂商没有通用幂等键的业务单据，必须按具体对象设计结果核对和补偿，不能盲目重试。

官方契约

• https://developer.fxiaoke.com/openapi_v2/en/start/auth/app-info.html
• https://developer.fxiaoke.com/openapi_v2/en/start/example/public.html
• https://developer.fxiaoke.com/openapi_v2/en/start/guide/cloud.html
• https://developer.fxiaoke.com/openapi_v2/en/FAQ/deep-paging.html
• https://developer.fxiaoke.com/openapi_v2/en/common/system/object-describe/list.html
• https://developer.fxiaoke.com/openapi_v2/en/common/system/object-describe/describe.html