EnterpriseInfo 域封装企查查、启信宝、天眼查三家企业征信数据供应商。提供企业搜索、工商信息查询、三要素核验、风险扫描、股东与司法案件等查询能力，业务代码不绑定具体厂商。这是典型的”按场景分区查询”域——一个接口、八个方法、五个业务区域。

域结构

Bitzsoft.Integrations.EnterpriseInfo                  ← 抽象层
├── Bitzsoft.Integrations.EnterpriseInfo.Qichacha         ← 企查查
├── Bitzsoft.Integrations.EnterpriseInfo.Qixin            ← 启信宝
├── Bitzsoft.Integrations.EnterpriseInfo.Tianyancha       ← 天眼查
└── Bitzsoft.Integrations.EnterpriseInfo.All              ← 聚合包

标准三层。

统一接口（8 方法，五区）

IEnterpriseInfoProvider 按查询场景分成五个区域。所有方法的入参都用统一社会信用代码或企业名称，接口内部根据厂商规则匹配：

public interface IEnterpriseInfoProvider
{
    string ProviderName { get; }

    // ① 搜索与查询（3）
    Task<EnterpriseSearchResult>     SearchAsync(string keyword, int pageIndex = 1, int pageSize = 20, CancellationToken ct = default);
    Task<EnterpriseBasicInfo>        GetBasicInfoAsync(string creditCodeOrName, CancellationToken ct = default);
    Task<EnterpriseDetailInfo>       GetDetailInfoAsync(string creditCodeOrName, CancellationToken ct = default);

    // ② 核验与风险（2）
    Task<EnterpriseVerificationResult> VerifyAsync(string creditCode, string enterpriseName, string legalPerson, CancellationToken ct = default);
    Task<EnterpriseRiskSummary>         GetRiskSummaryAsync(string creditCodeOrName, CancellationToken ct = default);

    // ③ 人员与司法（3）
    Task<IReadOnlyList<EnterpriseShareholderInfo>> GetShareholdersAsync(string creditCodeOrName, CancellationToken ct = default);
    Task<IReadOnlyList<EnterpriseLegalCase>>       GetLegalCasesAsync(string creditCodeOrName, int pageIndex = 1, int pageSize = 20, CancellationToken ct = default);
    Task<EnterpriseActualController>               GetActualControllerAsync(string creditCodeOrName, CancellationToken ct = default);
}

SearchAsync 返回带分页信息的 EnterpriseSearchResult（Items + TotalCount / PageIndex / PageSize），其余方法直接返回强类型模型。GetShareholdersAsync / GetLegalCasesAsync 返回列表，前者无分页后者有分页。

错误处理：异常路径为主

接口直接返回模型对象，不返回 Result 包装。失败时抛 EnterpriseInfoException：

public class EnterpriseInfoException : IntegrationException
{
    public string  ProviderName    => Provider ?? string.Empty;     // "qichacha" / "qixin" / "tianyancha"
    public new string? ErrorCode    => base.ErrorCode;              // 供应商错误码
    public new string? ProviderMessage => base.ProviderMessage;     // 供应商原始消息

    public EnterpriseInfoException(string providerName, string? errorCode, string? providerMessage)
        : base(domain: "EnterpriseInfo",
               message: $"[{providerName}] {errorCode}: {providerMessage}", ...) { }
}

HTTP 层走 GetAndEnsureSuccessAsync，非 2xx 响应直接抛异常向上冒泡，由 EnterpriseInfoException 捕获后重新包装。

核心返回模型

类型	用途	关键字段
`EnterpriseSearchResult`	搜索结果	`Items` 列表 + `TotalCount` / `PageIndex` / `PageSize`
`EnterpriseBasicInfo`	工商基本信息	名称、信用代码、法人、注册资本、成立日期、经营状态、经营范围、联系方式
`EnterpriseDetailInfo`	详情（含股东、人员、变更）	工商信息 + 关联实体
`EnterpriseVerificationResult`	三要素核验	`IsMatch` + 信用代码 / 企业名 / 法人 + `Message` 详情
`EnterpriseRiskSummary`	风险扫描摘要	异常经营、严重违法等风险标记
`EnterpriseShareholderInfo`	股东信息	出资比例、认缴金额
`EnterpriseLegalCase`	司法案件	案号、案由、裁判日期
`EnterpriseActualController`	实际控制人	控制链路与持股比例

字符串字段统一 = string.Empty 兜底，可空字段用 ? 显式标注。

三要素核验

VerifyAsync 是最常用的通用场景——校验统一社会信用代码、企业名称、法定代表人三者是否匹配，返回 EnterpriseVerificationResult：

public sealed class EnterpriseVerificationResult
{
    public bool   IsMatch        { get; init; }       // 三要素是否一致
    public string CreditCode     { get; init; }       // 核验的信用代码
    public string EnterpriseName { get; init; }       // 核验的企业名
    public string LegalPerson    { get; init; }       // 核验的法人
    public string? Message       { get; init; }       // 核验详情说明
}

IsMatch 为 true 表示三者一致，常用于 KYC（了解你的客户）、入驻审核、合同签署前的主体核验。

厂商清单

厂商	Provider ID	DI 方法	数据覆盖
企查查	`qichacha`	`AddBitzsoftQichachaEnterpriseInfo()`	工商 + 风险 + 司法
启信宝	`qixin`	`AddBitzsoftQixinEnterpriseInfo()`	工商 + 关联关系
天眼查	`tianyancha`	`AddBitzsoftTianyanchaEnterpriseInfo()`	工商 + 风险

三家数据维度相近，但字段丰富度和更新频率各有侧重。企查查司法案件覆盖较全，启信宝关联关系图谱见长，天眼查风险扫描更新及时。

注册

单厂商

// ① 企查查
builder.Services.AddBitzsoftQichachaEnterpriseInfo(builder.Configuration.GetSection("EnterpriseInfo:Qichacha"));

// ② 天眼查
builder.Services.AddBitzsoftTianyanchaEnterpriseInfo(builder.Configuration.GetSection("EnterpriseInfo:Tianyancha"));

多厂商聚合

// 注意：聚合方法名是 AddBitzsoftEnterpriseInfo，不带 All 后缀
builder.Services.AddBitzsoftEnterpriseInfo(builder.Configuration, "EnterpriseInfo");

配置：

{
  "EnterpriseInfo": {
    "Qichacha":   { "AppKey": "...", "AppSecret": "...", "BaseUrl": "..." },
    "Tianyancha": { "Token": "...", "BaseUrl": "..." }
  }
}

消费

工商查询与三要素核验

public class DueDiligenceService(IEnterpriseInfoProvider info)
{
    // ① 查询企业工商基本信息
    public async Task<EnterpriseBasicInfo> LookupAsync(string creditCode)
        => await info.GetBasicInfoAsync(creditCode);

    // ② 三要素核验：信用代码 + 企业名 + 法人是否一致
    public async Task<bool> VerifyCompanyAsync(string creditCode, string name, string legalPerson)
    {
        var result = await info.VerifyAsync(creditCode, name, legalPerson);
        return result.IsMatch;  // 三要素匹配则返回 true
    }

    // ③ 风险扫描：查异常经营、严重违法等
    public async Task<EnterpriseRiskSummary> ScreenRiskAsync(string creditCode)
        => await info.GetRiskSummaryAsync(creditCode);
}

股东与司法案件

public class RelationService(IEnterpriseInfoProvider info)
{
    public async Task<IReadOnlyList<EnterpriseShareholderInfo>> GetShareholdersAsync(string creditCode)
        => await info.GetShareholdersAsync(creditCode);

    public async Task<IReadOnlyList<EnterpriseLegalCase>> GetLegalCasesAsync(string creditCode, int page = 1)
        => await info.GetLegalCasesAsync(creditCode, pageIndex: page, pageSize: 20);
}

多厂商路由

public class InfoRouter(IIntegrationProviderResolver<IEnterpriseInfoProvider> providers)
{
    public async Task<EnterpriseBasicInfo> GetAsync(string source, string creditCode)
    {
        var provider = providers.GetRequired(source);  // "qichacha" / "qixin" / "tianyancha"
        return await provider.GetBasicInfoAsync(creditCode);
    }
}

EnterpriseInfo 企业信息

域结构