Shipeng.Foundation 4.1.1

.NET 10.0

dotnet add package Shipeng.Foundation --version 4.1.1

NuGet\Install-Package Shipeng.Foundation -Version 4.1.1

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="Shipeng.Foundation" Version="4.1.1" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="Shipeng.Foundation" Version="4.1.1" />
                    

                            Directory.Packages.props

<PackageReference Include="Shipeng.Foundation" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add Shipeng.Foundation --version 4.1.1

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: Shipeng.Foundation, 4.1.1"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package Shipeng.Foundation@4.1.1

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=Shipeng.Foundation&version=4.1.1
                    

                            Install as a Cake Addin

#tool nuget:?package=Shipeng.Foundation&version=4.1.1
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Shipeng.Foundation

中文：Shipeng.Foundation 是一个面向 .NET 10 的基础能力库，目标是把业务系统开发中高频、重复、容易出错的能力沉淀为可复用的工具、扩展、基础设施封装和集成组件。它覆盖 HTTP、缓存、Redis、MongoDB、SQL、SqlSugar、EF Core、RabbitMQ、MinIO、Excel、Word、二维码、加解密、序列化、分页、树结构、异常处理、任务队列、JWT、Swagger/OpenAPI、支付、短信、日志、对象映射、动态 API、数据库索引等常见场景。

English: Shipeng.Foundation is a .NET 10 foundation library for reusable application utilities, infrastructure helpers, integration components, and development accelerators. It covers HTTP, caching, Redis, MongoDB, SQL, SqlSugar, EF Core, RabbitMQ, MinIO, Excel, Word, QR codes, cryptography, serialization, pagination, tree structures, exception handling, task queues, JWT, Swagger/OpenAPI, payments, SMS, logging, object mapping, dynamic APIs, database indexes, and other common application scenarios.

The package, assembly, product, project name, and public namespaces are unified under Shipeng.Foundation and Shipeng.Foundation.*. Existing projects that used Shipeng.Util should update their using directives when upgrading to 4.1.1.

当前包名、程序集名、产品名、项目名和公开命名空间都统一为 Shipeng.Foundation / Shipeng.Foundation.*。旧项目如果曾经使用 Shipeng.Util，升级到 4.1.1 时需要同步更新 using。

Package Information / 包信息

Item	Value
Package ID / 包 ID	`Shipeng.Foundation`
Assembly / 程序集	`Shipeng.Foundation`
Target Framework / 目标框架	`net10.0`
Current Version / 当前版本	`4.1.1`
Nullable	`disable` for legacy compatibility / 为兼容旧代码暂时关闭
Implicit Usings	`enable`
Package Readme	`README.md`

Installation / 安装

Install from a local or remote NuGet source:

dotnet add package Shipeng.Foundation --version 4.1.1

If you are referencing this project from the same solution:

<ProjectReference Include="..\Shipeng.Foundation\Shipeng.Foundation.csproj" />

如果你在同一个解决方案中引用源码项目，请使用上面的 ProjectReference。如果你发布到 NuGet 或私有源，请使用 dotnet add package。

Quick Start / 快速开始

Common helpers now use Shipeng.Foundation namespaces:

using Shipeng.Foundation;
using Shipeng.Foundation.Helper;
using Shipeng.Foundation.Cache;

Infrastructure modules use Shipeng.Foundation.* namespaces:

using Shipeng.Foundation.Data.MongoDB.Repositories;
using Shipeng.Foundation.Data.SqlSugar;
using Shipeng.Foundation.Authorization;
using Shipeng.Foundation.DatabaseIndex;

Example:

// String helper, encryption helper, file helper, HTTP helper, and many other APIs
// are available through the unified Shipeng.Foundation namespaces.
var isEmpty = string.IsNullOrWhiteSpace(input);

What This Library Provides / 功能范围

1. Common Helpers / 通用工具

Helper, Util, Extention, Primitives, Model, DTO, Enum, Security, and related folders contain common utilities used by business applications:

String, date, enum, object, collection, stream, JSON, URL, and expression extensions.
File, path, ZIP, MIME, Excel, Word, QR code, image, verification code, and export helpers.
AES, DES, MD5, JWT, certificate, random, ID card, pinyin, sensitive data masking, and encoding helpers.
Pagination, tree data, AJAX result, service result, table metadata, dynamic model, and request/response primitives.
Async-to-sync helper, task queue, lock helper, queue helper, and reflection helper.

中文说明：

提供字符串、日期、枚举、对象、集合、流、JSON、URL、表达式等扩展方法。
提供文件、路径、压缩包、MIME、Excel、Word、二维码、图片、验证码、导入导出等工具。
提供 AES、DES、MD5、JWT、证书、随机数、身份证、拼音、敏感信息脱敏、编码等辅助能力。
提供分页、树结构、统一返回结果、表格元数据、动态模型、请求响应基础模型等基础对象。
提供异步转同步、任务队列、锁、队列、反射等基础开发工具。

2. Data Access / 数据访问

The package includes multiple data access styles so different projects can choose the most suitable abstraction:

Low-level ADO.NET helpers for SQL Server, MySQL, PostgreSQL, and Oracle.
SqlSugar repository and unit-of-work helpers.
MongoDB repository helpers.
EF Core integration modules.
Database table metadata and database index helper modules.
Hybrid MongoDB + SQL Server pagination helper for mixed storage scenarios.

中文说明：

支持 SQL Server、MySQL、PostgreSQL、Oracle 等常见数据库的基础访问封装。
支持 SqlSugar 仓储、工作单元和 IOC 扩展。
支持 MongoDB 仓储封装。
支持 EF Core 基础设施集成。
支持数据库表结构信息、数据库索引初始化和索引配置。
支持 MongoDB 与 SQL Server 混合分页查询场景。

3. Cache and Messaging / 缓存与消息

Cache and messaging related modules include:

Memory cache helpers.
Redis helpers based on CSRedisCore, Caching.CSRedis, and ServiceStack.Redis.
RabbitMQ helper and compatibility wrapper for modern RabbitMQ.Client APIs.
Distributed ID helpers and sequential GUID generators.

中文说明：

提供内存缓存封装。
提供 Redis 字符串、Hash、List、Set、ZSet 等常见操作封装。
提供 RabbitMQ 消息发布、消费和新版客户端兼容处理。
提供分布式 ID、短 ID、顺序 GUID 等 ID 生成能力。

4. Web, API, and ASP.NET Core Infrastructure / Web 与 ASP.NET Core 基础设施

The Shipeng infrastructure modules provide reusable ASP.NET Core capabilities:

Application startup, dependency injection, configurable options, CORS, localization, dynamic API controller, friendly exception, event bridge, task scheduler, and view engine helpers.
Swagger/OpenAPI and MiniProfiler integration.
JWT bearer authentication helpers.
Object mapping modules based on AutoMapper and Mapster.
Logging modules based on Serilog and log4net-related integration.

中文说明：

提供应用启动、依赖注入、配置选项、跨域、本地化、动态 API 控制器、友好异常、事件桥、任务调度、视图引擎等基础设施能力。
提供 Swagger/OpenAPI、MiniProfiler 集成。
提供 JWT Bearer 认证辅助能力。
提供 AutoMapper、Mapster 映射相关封装。
提供 Serilog、log4net 等日志相关集成。

5. Third-Party Integrations / 第三方集成

The library contains helpers for common external systems:

MinIO object storage.
WeChat payment and WeChat message helpers.
SMS providers such as Huawei, Aliyun, Tencent Cloud, and other integrated APIs.
JPush push notification helper.
Logistics query helper.
Office document helpers based on Aspose, NPOI, EPPlus, FreeSpire, and Office interop.
QR code helpers based on QRCoder, ZXing, ThoughtWorks QRCode, and related drawing libraries.

中文说明：

支持 MinIO 对象存储。
支持微信支付、微信消息等常见微信生态接口封装。
支持华为云、阿里云、腾讯云等短信能力封装。
支持极光推送。
支持物流查询。
支持 Aspose、NPOI、EPPlus、FreeSpire、Office Interop 等 Office 文档处理方式。
支持 QRCoder、ZXing、ThoughtWorks QRCode 等二维码生成与解析能力。

Design Principles / 设计原则

Compatibility First / 兼容优先

The package keeps many legacy namespaces, method names, and DTO shapes because existing projects may already reference them. Renaming every public API would make the library cleaner internally but would break callers. Public compatibility is therefore treated as a first-class requirement.

本库保留了很多历史命名空间、方法名和 DTO 结构，因为已有项目可能已经引用这些 API。一次性重命名所有公开 API 会让内部更整齐，但会破坏调用方。因此兼容性是首要设计目标之一。

Practical Performance / 实用性能优化

The library avoids obvious performance problems where possible:

Reuses HttpClient-based patterns where available to reduce connection setup cost and socket exhaustion risk.
Uses blocking/async primitives instead of busy waiting for queue-like workflows.
Uses modern MongoDB, RabbitMQ, and cryptography APIs instead of removed or obsolete APIs.
Keeps heavy integrations optional at call-site level so applications only execute the features they actually use.
Uses repository and helper abstractions to reduce repeated reflection, repeated parsing, and duplicated configuration code in business projects.

本库尽量避免明显性能问题：

尽可能复用 HttpClient 相关模式，减少连接创建成本和 Socket 耗尽风险。
队列类逻辑使用阻塞/异步原语，避免空转等待。
使用新版 MongoDB、RabbitMQ、加密 API，替代已删除或过时 API。
重型集成按调用方实际使用触发，避免业务系统启动时无意义执行。
通过仓储和工具封装减少业务项目中重复反射、重复解析和重复配置代码。

Clear Operational Boundaries / 清晰的运行边界

Some APIs are platform-specific or dependency-heavy. For example, System.Drawing.Common, Office interop, and some image/font features are best suited for Windows environments. Server-side Linux deployments should prefer cross-platform image libraries and avoid Office interop at runtime.

部分 API 具有平台限制或依赖较重。例如 System.Drawing.Common、Office Interop、部分图片和字体能力更适合 Windows 环境。Linux 服务端部署时建议优先选择跨平台图片库，并避免运行时依赖 Office Interop。

Platform Notes / 平台说明

Target framework is net10.0; callers should use a compatible .NET SDK/runtime.
ASP.NET Core infrastructure features require Microsoft.AspNetCore.App.
Some Office and drawing APIs are Windows-oriented.
Some provider helpers require external service credentials and network availability.
Database helpers require the corresponding database driver and correct connection string configuration.

中文说明：

目标框架为 net10.0，调用方需要使用兼容的 .NET SDK/runtime。
ASP.NET Core 基础设施功能依赖 Microsoft.AspNetCore.App。
部分 Office 和绘图 API 更偏 Windows 环境。
第三方服务类工具需要对应服务密钥和网络环境。
数据库工具需要正确的驱动、连接字符串和数据库权限。

NuGet Publishing Checklist / NuGet 发布检查清单

Before publishing a package, run:

dotnet restore Shipeng.Foundation\Shipeng.Foundation.csproj
dotnet build Shipeng.Foundation\Shipeng.Foundation.csproj -t:Rebuild -v:q -clp:ErrorsOnly
dotnet build Shipeng.Foundation\Shipeng.Foundation.csproj -c Release -v:q -clp:ErrorsOnly
dotnet pack Shipeng.Foundation\Shipeng.Foundation.csproj -c Release --no-build -v:q -clp:ErrorsOnly
dotnet list Shipeng.Foundation\Shipeng.Foundation.csproj package --outdated
dotnet list Shipeng.Foundation\Shipeng.Foundation.csproj package --vulnerable --include-transitive

发布前建议确认：

编译结果必须为 0 errors。
尽量保持 0 warnings，除非某些兼容性警告已经明确评估并在项目文件中集中说明。
NuGet 包必须没有已知漏洞。
包版本、发布说明、README、依赖版本需要同步。
如果修改了公开 API，需要在发布说明中写清楚兼容性影响。
如果新增平台相关功能，需要在文档中说明 Windows/Linux/macOS 差异。

Version 4.0.0 Release Notes / 4.0.0 发布说明

English:

Upgraded the library to net10.0.
Renamed the project and NuGet package identity to Shipeng.Foundation.
Unified public namespaces under Shipeng.Foundation / Shipeng.Foundation.*.
Added reusable infrastructure modules under Shipeng.Foundation.*.
Added MongoDB + SQL Server hybrid pagination helper.
Added ID string helper for comma-separated database ID fields.
Updated NuGet dependencies to current versions available from the configured sources.
Removed or replaced vulnerable package versions where possible.
Updated MongoDB, RabbitMQ, JWT, cryptography, and other APIs for modern .NET compatibility.
Verified project build, Release build, package generation, outdated package check, and vulnerable package check.

中文：

升级目标框架到 net10.0。
项目名和 NuGet 包身份统一为 Shipeng.Foundation。
公开命名空间统一迁移到 Shipeng.Foundation / Shipeng.Foundation.*。
新增 Shipeng.Foundation.* 基础设施模块。
新增 MongoDB + SQL Server 混合分页查询辅助类。
新增逗号分隔 ID 字段处理辅助类。
按当前 NuGet 源升级依赖到可用的较新版本。
尽量移除或替换存在漏洞的旧依赖版本。
更新 MongoDB、RabbitMQ、JWT、加密等 API，使其适配现代 .NET。
已验证项目编译、Release 编译、NuGet 打包、过期包检查和漏洞包检查。

Naming and Compatibility / 命名与兼容

Shipeng.Foundation is the package identity and the namespace root. New and upgraded projects should reference the package and update source code to use Shipeng.Foundation namespaces:

using Shipeng.Foundation;
using Shipeng.Foundation.Helper;
using Shipeng.Foundation.Cache;
using Shipeng.Foundation.Data.MongoDB.Repositories;
using Shipeng.Foundation.Data.SqlSugar;

中文说明：

Shipeng.Foundation 是包身份，也是统一命名空间根节点。新项目和升级后的旧项目应引用 Shipeng.Foundation 包，并将源码中的命名空间更新为：

using Shipeng.Foundation;
using Shipeng.Foundation.Helper;
using Shipeng.Foundation.Cache;
using Shipeng.Foundation.Data.MongoDB.Repositories;
using Shipeng.Foundation.Data.SqlSugar;

Suggested Usage Guidelines / 使用建议

Prefer small, focused helpers for application code instead of placing all business logic inside utility classes.
Keep credentials, connection strings, and provider secrets outside source code.
Validate external inputs before passing them to file, database, payment, or network helpers.
For high-throughput services, benchmark hot paths before adding heavy Office, image, reflection, or dynamic compilation features.
For public APIs, wrap provider-specific exceptions into business-level errors before returning responses to clients.

中文建议：

工具类只负责通用能力，不建议把业务规则堆进工具类。
密钥、连接字符串、第三方服务凭证不要写死在源码中。
文件、数据库、支付、网络请求相关工具在调用前应校验外部输入。
高并发服务中使用 Office、图片、反射、动态编译等重型能力前，建议做性能压测。
对外 API 不建议直接暴露第三方 SDK 异常，应转换为业务可理解的错误信息。

License Notes / 许可说明

This project references multiple third-party packages. Some packages may have their own commercial, redistribution, or runtime restrictions. Please review the license of each dependency before publishing a product that includes this package.

本项目引用了多个第三方包。部分包可能有商业授权、再分发或运行时限制。将本包用于正式产品发布前，请核查每个依赖包的许可证。

Support / 支持

For internal projects, keep the package version aligned with the solution version. For public distribution, publish immutable versions and document breaking changes clearly.

内部项目建议保持包版本与解决方案版本一致。公开发布时建议使用不可变版本，并清楚记录破坏性变更。

API Reference / API 索引

nuget.org 当前只会直接渲染包的 README 和 Release Notes，不会把包内 docs/API_REFERENCE.md 自动显示成一个独立页面标签。完整公开 API 索引已经随 NuGet 包打入 docs/API_REFERENCE.md，也可以在源码仓库中查看。

如果你正在 NuGet 页面阅读本文，请优先看本 README 的“主要类型”和示例；下载包后可在包内容中打开 docs/API_REFERENCE.md 查看完整公开类型、方法、属性和构造函数签名。

Product	Compatible and additional computed target framework versions.
.NET	net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net10.0
- Abp.AutoMapper (>= 10.4.0)
- AspectCore.Abstractions (>= 2.4.0)
- Aspose.Cells (>= 26.6.0)
- Aspose.Words (>= 26.6.0)
- Autofac (>= 9.3.0)
- AutoMapper (>= 16.1.1)
- AutoMapper.Collection (>= 13.0.0)
- Azure.Identity (>= 1.21.0)
- Ben.Demystifier (>= 0.4.1)
- Caching.CSRedis (>= 3.8.807)
- Castle.Core.AsyncInterceptor (>= 2.1.0)
- ce.office.extension (>= 2.0.0)
- CSRedisCore (>= 3.8.807)
- DotNettySocket (>= 1.2.0)
- DotNetZip.Original (>= 2025.2.15)
- EFCore.Sharding.PostgreSql (>= 9.0.10)
- EFCore.Sharding.SqlServer (>= 9.0.10)
- EPPlus (>= 8.6.1)
- FreeSpire.Office (>= 8.2.0)
- IdHelper.Zookeeper (>= 1.5.1)
- JPushSDK (>= 1.0.0)
- log4net (>= 3.3.2)
- MailKit (>= 4.17.0)
- Mapster (>= 10.0.10)
- Microsoft.AspNetCore.Mvc.NewtonsoftJson (>= 10.0.9)
- Microsoft.AspNetCore.OpenApi (>= 10.0.9)
- Microsoft.AspNetCore.Razor.Language (>= 6.0.36)
- Microsoft.CodeAnalysis.CSharp (>= 5.3.0)
- Microsoft.Data.SqlClient (>= 7.0.2)
- Microsoft.Data.Sqlite (>= 10.0.9)
- Microsoft.EntityFrameworkCore (>= 10.0.9)
- Microsoft.EntityFrameworkCore.Sqlite (>= 10.0.9)
- Microsoft.EntityFrameworkCore.SqlServer (>= 10.0.9)
- Microsoft.Extensions.DependencyModel (>= 10.0.9)
- Microsoft.Office.Interop.Word (>= 15.0.4797.1004)
- Minio (>= 7.0.0)
- MiniProfiler.AspNetCore.Mvc (>= 4.5.4)
- MongoDB.Bson (>= 3.9.0)
- MongoDB.Driver (>= 3.9.0)
- MySqlConnector (>= 2.6.1)
- Newtonsoft.Json (>= 13.0.4)
- NodaTime (>= 3.3.2)
- Npgsql (>= 10.0.3)
- Npgsql.EntityFrameworkCore.PostgreSQL (>= 10.0.2)
- NPOI (>= 2.8.0)
- OnceMi.AspNetCore.OSS (>= 1.2.0)
- Oracle.EntityFrameworkCore (>= 10.23.26200)
- Oracle.ManagedDataAccess.Core (>= 23.26.200)
- PinYinConverterCore (>= 1.0.2)
- Pomelo.EntityFrameworkCore.MySql (>= 9.0.0)
- QRCoder (>= 1.8.0)
- Quartz (>= 3.18.2)
- RabbitMQ.Client (>= 7.2.1)
- Serenity.Web (>= 3.14.5)
- ServiceStack.Redis (>= 10.0.8)
- SharpCompress (>= 0.49.1)
- Snappier (>= 1.3.1)
- SQLitePCLRaw.lib.e_sqlite3 (>= 3.50.3)
- SqlSugar.IOC (>= 2.0.1)
- SqlSugarCore (>= 5.1.4.215)
- Swashbuckle.AspNetCore (>= 10.2.3)
- System.Data.SqlClient (>= 4.9.1)
- System.Drawing.Common (>= 10.0.9)
- System.Linq.Dynamic.Core (>= 1.7.2)
- System.Management (>= 10.0.9)
- System.ServiceModel.Primitives (>= 10.0.652802)
- ThoughtWorks.QRCodeCore (>= 1.0.0)
- ToolGood.Words (>= 3.1.0.3)
- XmpCore (>= 6.1.10.1)
- Yitter.IdGenerator (>= 1.0.14)
- ZKWeb.System.Drawing (>= 4.0.1)
- ZXing.Net.Bindings.ImageSharp.V2 (>= 0.16.18)
- ZXing.Net.Bindings.ZKWeb.System.Drawing (>= 0.16.9)

NuGet packages (7)

Showing the top 5 NuGet packages that depend on Shipeng.Foundation:

Package	Downloads
Shipeng.Data.SqlSugar SqlSugar data access package with repository, paging, stored procedure, unit of work, transaction filter, and dependency injection helpers.	176
Shipeng.Data.MongoDB MongoDB data access package with context, repository, collection, query, paging, and dependency injection helpers.	169
Shipeng.Payment Payment integration package with unified payment provider abstractions, built-in WeChat Pay V3 implementation, refund and callback helpers, multi-channel extension points for Alipay, UnionPay, Cloud QuickPass and bank gateways, and profit-sharing models.	167
Shipeng.Authentication.JwtBearer JWT Bearer authentication integration for ASP.NET Core, including token creation, validation, refresh, claim handling, and service registration helpers.	164
Shipeng.EntityFrameworkCore Entity Framework Core integration package with DbContext, repository, dynamic query, multi-provider, and helper extensions for enterprise applications.	115

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
4.1.1	337	6/30/2026
4.1.0	353	6/30/2026
4.0.0	95	6/27/2026

4.1.1 / 2026-06-30

English:
- Split the original monolithic foundation library into focused Shipeng.* NuGet packages so applications can reference only the capabilities they actually need.
- Added Shipeng.DatabaseMaintenance for SQL Server and MongoDB database maintenance. It supports non-destructive cleanup preview, SqlSugar entity scanning, MongoDB collection scanning from configuration or source declarations, keep lists, ignored prefixes, empty-scan protection, missing table preview, controlled SqlSugar CodeFirst table creation, SQL Server schema difference preview, safe missing-column creation, safe changed-column synchronization, explicit execution switches, and confirmation-code protected destructive/schema-changing execution.
- Improved Shipeng.Payment with a unified payment abstraction for WeChat, Alipay, UnionPay, Cloud QuickPass, bank gateways, and profit-sharing scenarios. WeChat Pay V3 remains the concrete built-in implementation; other channels expose stable provider contracts and explicit placeholders so applications can add real vendor SDK implementations without changing business code.
- Centralized common NuGet metadata in Directory.Build.props: target framework, version, authors, repository, license, README, XML documentation, warning policy, and release notes.
- Every package includes README.md, XML IntelliSense documentation, and docs/API_REFERENCE.md inside the generated nupkg.
- Updated README files to explain that nuget.org renders README and Release Notes directly but does not expose packaged docs/API_REFERENCE.md as a separate page tab.
- Release build validation: all projects build and pack successfully for net10.0 with 0 warnings and 0 errors.

中文：
- 将早期单体基础库拆分为职责更清晰的 Shipeng.* NuGet 包，业务项目可以按需引用认证、MongoDB、SqlSugar、EF Core、数据库索引、数据库维护、第三方集成、日志、映射、支付和混合分页能力。
- 新增 Shipeng.DatabaseMaintenance，用于 SQL Server 和 MongoDB 数据库维护。支持冗余表/集合预览清理、SqlSugar 实体扫描、MongoDB 配置集合扫描、源码集合声明扫描、保留名单、忽略前缀、空扫描保护、缺失表预览、受控 CodeFirst 自动建表、SQL Server 结构差异预览、缺失字段补齐、安全字段同步、显式执行开关和确认码保护。
- 增强 Shipeng.Payment，新增统一支付抽象，覆盖微信、支付宝、银联、云闪付、银行网关和分账场景。微信支付 V3 是当前内置可用实现；其他通道提供稳定 Provider 契约和明确占位实现，方便业务项目接入真实厂商 SDK。
- 将公共 NuGet 元数据统一集中到 Directory.Build.props，避免各项目 PropertyGroup 重复和不一致。
- 每个包都打入 README.md、XML IntelliSense 文档和 docs/API_REFERENCE.md。
- 所有 README 都补充说明：nuget.org 会直接显示 README 和 Release Notes，但不会把包内 docs/API_REFERENCE.md 自动显示为独立标签页。
- 已验证 Release 构建和打包，目标框架 net10.0，0 警告，0 错误。