Mabang.Sdk 0.1.0

Mabang SDK

面向 .NET 10 的马帮接口 SDK。首版正在实现中，目标是统一封装马帮公开 API 与已授权网页接口，并支持 DI、直接构造和运行时动态多账号。

当前状态

已完成：

• net10.0 解决方案与双包结构。
• 账号注册表、账号代际和内存会话快照存储。
• 分层身份模型、会话优先身份解析和统一结果模型。
• 统一客户端、账号上下文和首版业务服务契约。
• DI Singleton 注册与基础契约测试。
• 库存 SKU 公开 API 查询、新增的 HMAC-SHA256 请求、响应映射与真实 HTTP 执行器。

库存 SKU 公开 API 查询、新增、授权网页登录、库存 SKU 网页查询和库存分类列表网页接口已经接入；其余网页接口和业务路由仍会返回 CapabilityUnavailable 结果。网页登录会在建立 signed Cookie 后，从 cMKey 换取业务 API 的短期 Bearer token，供已支持的网页业务接口使用。真实网络执行器需要显式注入，避免未配置凭据时意外访问正式环境。

services.AddMabangSdk(options => options.DefaultAccountId = "account-1");

var registry = serviceProvider.GetRequiredService<IAccountRegistry>();
await registry.AddAsync(new AccountRegistration(
    "account-1",
    new AccountIdentity(PublicApi: new PublicApiCredentials("app-key", "app-secret"))));

var result = await serviceProvider
    .GetRequiredService<IMabangClient>()
    .ForAccount("account-1")
    .Stock
    .SearchSkuAsync(new SearchSkuRequest(Page: 1, PageSize: 50));

库存 SKU 网页查询使用已授权 Cookie 会话；请求默认查询正常销售的库存 SKU，并提供语义化链式条件：

var request = new StockSkuQueryRequest()
    .SearchStockSku()
    .LikeStart("MX-ABC-001")
    .StatusNormalSale()
    .OnPage(1)
    .WithRowsPerPage(100)
    .Build();

var result = await client.ForAccount("account-1").Stock.SearchStockSkuAsync(request);

条件参数也可以直接作用于同一个构建器，不需要接收每个链式方法的返回值：

var requestBuilder = new StockSkuQueryRequest();
requestBuilder.SearchStockSku();
if (!string.IsNullOrWhiteSpace(sku))
    requestBuilder.LikeStart(sku);

var request = requestBuilder.StatusAutoCreated().Build();

Build() 会校验当前条件并生成独立的请求快照。

外部会话/账号存储

AddMabangSdk 默认注册线程安全的 Singleton 内存实现；生产应用可以在组合根替换为独立适配器包提供的 Redis、MySQL 或 SQLite 实现。核心包不携带这些驱动依赖：

services.AddSingleton<IAccountRegistry, RedisAccountRegistry>();
services.AddSingleton<IWebSessionStore, RedisWebSessionStore>();
services.AddMabangSdk(options => options.DefaultAccountId = "account-1");

也可以直接安装 Mabang.Sdk.Redis 或 Mabang.Sdk.Sqlite，使用适配器提供的组合根扩展：

services.AddMabangRedisStorage(redisConnectionMultiplexer);
// 或：services.AddMabangSqliteStorage("Data Source=mabang.db");
services.AddMabangSdk(options => options.DefaultAccountId = "account-1");

由于 SDK 使用 TryAddSingleton，上述注册放在 AddMabangSdk 前后都可以。直接构造时，把 IAccountRegistry 作为现有参数传入，并用 MabangClient.Create 的第四个参数传入自定义 IWebSessionStore。适配器必须实现按账号隔离、版本乐观并发和快照无损序列化；详见 ADR-0089。

使用网页接口前，调用方必须拥有相应授权并遵守马帮服务条款、频率限制和数据保护要求。SDK 不绕过验证码、MFA 或风控。

默认客户端和 AddMabangSdk 仍使用 fail-closed 的能力占位执行器。要显式开启网络请求，推荐调用 AddMabangHttpTransports；也可以手动注册 PublicApiRequestExecutor、WebRequestExecutor、ProtocolRequestExecutor 和 IWebSessionAuthenticator。控制台项目包含完整示例。

HTTP 审计切面

外部应用可以注册 IMabangHttpObserver 接收 SDK HTTP 调用前后的快照。快照包含账号、业务操作、组件、ExchangeId、URL、请求/响应 headers、body、状态码和耗时；公开 API、网页接口以及网页登录流程都会进入同一观察接口。默认会脱敏 Authorization、Cookie、token、密码、用户名、AppKey 和 cMKey，body 默认最多记录 64 KiB。

services.AddSingleton<IMabangHttpObserver, AuditObserver>();
services.AddMabangSdk();
services.AddMabangHttpTransports(options =>
{
    options.MaximumBodyLength = 256 * 1024;
    // 只有在受控调试环境中才显式打开完整凭据和 Cookie 采集。
    options.IncludeSensitiveData = false;
});

AddMabangHttpTransports 会注册公开 API、网页 API、协议路由执行器和默认网页登录器，并自动把已注册的 IMabangHttpObserver 注入进去。若应用已经注册自定义 IWebSessionAuthenticator，SDK 会保留自定义实现。观察器抛出的异常会被 SDK 忽略，不会改变实际接口调用结果。若要记录完整 Authorization、Cookie 或网页登录表单，必须明确设置 IncludeSensitiveData = true，并自行确保日志存储符合安全要求。

控制台调试程序

仓库包含一个独立控制台程序，用于导入正式账号并调试 SKU 查询、新增和库存分类列表。add-sku 会产生写操作，请只使用明确授权的测试 SKU。它显式注册公开 API、网页登录和网页接口执行器，单元测试不会因此读取正式凭据。

控制台按 endpoint 拆分调试功能，可通过 --endpoint <name>、--test <name>、逗号分隔名称或 --all 选择运行哪些功能；完整配置、参数和新增 endpoint 的说明见 samples/Mabang.Sdk.Console/README.md。

dotnet user-secrets set "Mabang:DefaultAccountId" "production" --project samples/Mabang.Sdk.Console
dotnet user-secrets set "Mabang:Accounts:production:AppKey" "<app-key>" --project samples/Mabang.Sdk.Console
dotnet user-secrets set "Mabang:Accounts:production:AppSecret" "<app-secret>" --project samples/Mabang.Sdk.Console
dotnet user-secrets set "Mabang:Accounts:production:WebLogin:UserName" "<web-user-name>" --project samples/Mabang.Sdk.Console
dotnet user-secrets set "Mabang:Accounts:production:WebLogin:Password" "<web-password>" --project samples/Mabang.Sdk.Console
dotnet user-secrets set "Mabang:Query:Sku" "<sku>" --project samples/Mabang.Sdk.Console

dotnet run --project samples/Mabang.Sdk.Console
dotnet run --project samples/Mabang.Sdk.Console -- --account production --sku "<sku>" --page-size 20
dotnet run --project samples/Mabang.Sdk.Console -- --endpoint sku-search --account production --sku "<sku>"

可以在 Mabang:Accounts 下配置多个账号；--account 选择本次调用的账号。密钥和密码不通过命令行传入，也不会打印到控制台。AppToken 也可作为 AppSecret 的兼容别名。环境变量可使用 MABANG_Mabang__Accounts__production__AppKey 或 MABANG_Mabang__Accounts__production__WebLogin__Password 这类形式覆盖配置。

控制台样例使用 Serilog 将每个 HTTP 请求、响应和传输异常以脱敏 JSON 快照保存到运行目录的 logs/ 中，按日和 32 MiB 大小滚动，最多保留 30 个文件。详情见 samples/Mabang.Sdk.Console/README.md。

正式账号集成测试

正式账号只用于显式启用的集成测试，普通单元测试不读取或依赖真实凭据。集成测试项目通过 .NET user-secrets 读取以下值：

dotnet user-secrets set "Mabang:Integration:Enabled" "true" --project tests/Mabang.Sdk.IntegrationTests
dotnet user-secrets set "Mabang:Integration:AppKey" "<app-key>" --project tests/Mabang.Sdk.IntegrationTests
dotnet user-secrets set "Mabang:Integration:AppSecret" "<app-secret>" --project tests/Mabang.Sdk.IntegrationTests
dotnet user-secrets set "Mabang:Integration:Sku" "<sku>" --project tests/Mabang.Sdk.IntegrationTests
dotnet test tests/Mabang.Sdk.IntegrationTests --filter "Category=Integration"

测试缺少开关、凭据或 SKU 时会跳过；测试输出不会记录 AppSecret、签名或完整供应商响应。也可以使用环境变量 MABANG_Mabang__Integration__... 覆盖本机 user-secrets。