Integration Core

public sealed class IntegrationProviderDescriptor
{
    public IntegrationProviderDescriptor(
        string providerId,
        string displayName,
        string domain,
        IEnumerable<Type> capabilityTypes,
        IntegrationProviderStability stability,
        string? vendor = null,
        string? apiVersion = null,
        string? authenticationType = null,
        IEnumerable<string>? regions = null,
        IEnumerable<string>? environments = null,
        IEnumerable<string>? limitations = null,
        DateTimeOffset? lastContractValidatedAt = null);
}

// ① 泛型形式，最常用
if (!descriptor.Supports<IPaymentProvider>())
    throw new ArgumentException("Descriptor does not declare this capability.");

// ② Type 形式，适合反射场景
bool ok = descriptor.Supports(typeof(IPaymentProvider));

public enum IntegrationProviderStability
{
    Experimental = 0,  // 仅设计验证或项目级适配，不作生产能力声明
    Preview = 1,       // 有真实实现与测试，公共契约仍可能调整
    Stable = 2,        // 已通过契约测试，可作为受支持能力使用
    Deprecated = 3     // 仍兼容但不建议新项目使用
}

public interface IIntegrationProviderCatalog
{
    IReadOnlyCollection<IntegrationProviderDescriptor> Providers { get; }
    bool TryGet(string providerKey, out IntegrationProviderDescriptor descriptor);
    bool TryGet(string domain, string providerId, out IntegrationProviderDescriptor descriptor);
    IntegrationProviderDescriptor GetRequired(string providerKey);
}

public interface IIntegrationProviderResolver<TCapability> where TCapability : class
{
    IReadOnlyCollection<TCapability> Providers { get; }
    bool TryResolve(string providerId, out TCapability capability);
    TCapability GetRequired(string providerId);
}

public interface IContextualIntegrationProviderResolver<TCapability> where TCapability : class
{
    IReadOnlyCollection<IntegrationProviderDescriptor> Providers { get; }
    bool TryResolve(IntegrationProviderSelection selection, out TCapability? provider);
    TCapability GetRequired(IntegrationProviderSelection selection);
}

public sealed class IntegrationContext
{
    public IntegrationContext(
        string tenantId,
        string? region = null,
        string? environment = null,
        string? correlationId = null);

    public string TenantId { get; }
    public string? Region { get; }
    public string Environment { get; }        // 默认 Production
    public string? CorrelationId { get; }

    public IntegrationContext With(
        string? region = null,
        string? environment = null,
        string? correlationId = null);
}

public interface IIntegrationContextAccessor
{
    IntegrationContext? Current { get; }
    IDisposable Push(IntegrationContext context);
}

// ③ 建立短生命周期作用域，using 保证释放
using (accessor.Push(new IntegrationContext("tenant-001", region: "CN")))
{
    await payment.CreateOrderAsync(request);
}

public sealed class IntegrationCredential : IDisposable
{
    public IntegrationCredential(
        IEnumerable<KeyValuePair<string, string>> secrets,
        string name = IntegrationCredentialNames.Default,
        string? authenticationType = null,
        DateTimeOffset? expiresAt = null);

    public string Name { get; }
    public string? AuthenticationType { get; }
    public DateTimeOffset? ExpiresAt { get; }
    public IReadOnlyCollection<string> SecretNames { get; }   // 仅字段名，不含值
    public bool IsDisposed { get; }

    public bool IsExpiredAt(DateTimeOffset instant);
    public bool TryGetSecret(string secretName, out string? value);
    public bool ContainsSecret(string secretName);
    public string GetRequiredSecret(string secretName);
    public TResult UseSecret<TResult>(string secretName, Func<ReadOnlyMemory<char>, TResult> callback);
}

// ① UseSecret 在 char[] 有效期内计算 HMAC，不产生中间 string
byte[] signature = credential.UseSecret("RequestSigningSecret", secret =>
{
    var key = Encoding.UTF8.GetBytes(secret.ToArray());
    using var hmac = new HMACSHA256(key);
    return hmac.ComputeHash(canonical);
});

var store = new InMemoryIntegrationCredentialStore();
store.Store(new IntegrationCredentialKey("tenant-001", "Payment:Alipay"),
    new IntegrationCredential(new[]
    {
        new KeyValuePair<string, string>("AppId", "2021..."),
        new KeyValuePair<string, string>("PrivateKey", "..."),
    }, authenticationType: "RSA2"));

public class IntegrationException : Exception
{
    public IntegrationException(
        string domain,
        string message,
        string? provider = null,
        string? errorCode = null,
        string? providerMessage = null,
        IntegrationFailureKind failureKind = IntegrationFailureKind.Provider,
        int? httpStatusCode = null,
        string? requestId = null,
        bool isTransient = false,
        TimeSpan? retryAfter = null,
        Exception? innerException = null);
}

public sealed class IntegrationProviderResolutionException : InvalidOperationException
{
    public IntegrationProviderResolutionException(
        string providerId, Type capabilityType, string message);

    public string ProviderId { get; }
    public Type CapabilityType { get; }
}

// ① 注册基础设施：Resolver<>、ContextualResolver<>、Catalog、ContextAccessor
services.AddBitzsoftIntegrationCore();

services.AddInMemoryIntegrationCredentials();

services.AddIntegrationProviderDescriptor(AlipayProviderDescriptor.Instance);

// ② 类型形式
services.AddIntegrationProviderCapability<IPaymentProvider, AlipayPaymentProvider>(
    AlipayProviderDescriptor.Instance,
    implementationLifetime: ServiceLifetime.Transient,
    registerLegacyAlias: true);

// ③ 工厂形式（Provider 构造函数含 internal Adapter 时必须用）
services.AddIntegrationProviderCapability<IPaymentProvider, AlipayPaymentProvider>(
    AlipayProviderDescriptor.Instance,
    serviceProvider => new AlipayPaymentProvider(
        serviceProvider.GetRequiredService<AlipayHttpClient>(),
        serviceProvider.GetRequiredService<IAlipayConfigProvider>(),
        serviceProvider.GetRequiredService<ILogger<AlipayPaymentProvider>>()));

public sealed class CheckoutService(IPaymentProvider payment)
{
    public Task<PaymentResult<PaymentOrderResult>> PayAsync(PaymentOrderRequest req)
        => payment.CreateOrderAsync(req);
}

public sealed class PaymentRouter(IIntegrationProviderResolver<IPaymentProvider> providers)
{
    public IPaymentProvider Resolve(string providerId)
        => providers.GetRequired(providerId);  // ④ 按稳定 ID 解析
}