XiHan.Framework.Persistence.Abstractions 5.0.0-preview.1

XiHan.Framework.Persistence.Abstractions

持久化契约（Ring 2）。能力 persistence.relational@1、persistence.document@1 由 Provider 提供。

builder.Services.AddRepository<Order, Guid>();          // 应用登记实体
builder.AddXiHan(x => x.UseFeature<InMemoryPersistenceFeature>());   // 或任一 Provider 的特性

是否已开数据库事务

数据库事务延迟开启：工作单元开始时不开，第一次写入才开。所以 State == Active 说明不了开没开，IUnitOfWork.HasTransaction（ADR-0109）报告这一点：

• 可写工作单元里仓储的单条写入或集合非空的批量写入一经调用即为真（不论这次写入的结果），Provider 的直接写入入口 EnsureTransactionAsync 同样；查找、查询、计数与空批量不开事务。
• 提交（成功或返回失败）与回滚之后为假；未开始、已提交、已回滚都为假；只读工作单元恒为假。
• 多连接时一个值，任一连接开着事务即为真；绑定命名连接的工作单元只报告那个连接，不同服务作用域的工作单元各报各的。
• 内存实现没有数据库事务，第一次写入调用起同样为真，直到提交或回滚：覆盖层从此可能有未提交、随回滚丢弃的变更。
• 不经仓储、也不经 EnsureTransactionAsync 直接对客户端执行的写入不在事务里，也不让它变真。

调用里要立即对外产生、不随回滚撤回的副作用（立即推送、调用外部系统）之前据此判断：

// 本工作单元写过数据时立即推送会描述可能回滚的数据；还没写入的调用（只读操作、先推送后写库）照常立即发出
if (services.GetService<IUnitOfWork>() is { HasTransaction: true })
{
    throw new InvalidOperationException("The push is sent immediately and cannot follow a write in the same call; send it after the commit.");
}

只读工作单元与嵌套调用

UnitOfWorkMiddleware 按本次调用的操作契约开工作单元（ADR-0073、ADR-0081）：动词 get / list 或声明了 ReadOnly = true 的操作开只读工作单元，写操作与不带操作描述的调用（消息处理器、作业、直接交给 App.InvokeAsync 的处理器）开可写工作单元。

• 只读工作单元不开数据库事务，查找、查询、计数照常。
• 仓储的新增、更新、删除（含批量，空集合除外）返回 PERSISTENCE_UNEXPECTED_001（消息键 persistence.unit_of_work.read_only，HTTP 500：只读操作写数据是代码缺陷，不是调用方的输入或权限），并把工作单元记为失败：处理器忽略这次失败而返回成功时，提交返回同一错误，调用以它结束。
• Provider 的直接写入入口（EF Core / SqlSugar 工作单元的 EnsureTransactionAsync）在只读工作单元里抛出携带同一码的 FrameworkException，Transaction 阶段回滚并转为同码结果。
• 嵌套调用（在调用里经管道再调操作）新建服务作用域（CreateAsyncScope() + App.CreateContext），内层按自己的契约开自己的工作单元：只读不传播，只读操作里调用的写操作在自己的事务里提交。用同一个服务作用域再经管道时，作用域的工作单元已经开始过，内层以 PERSISTENCE_VALIDATION_002（消息键 persistence.unit_of_work.nested）结束、处理器不执行。
• 管道外自己开的工作单元由 UnitOfWorkOptions(TenantId, IsReadOnly, Connection) 决定，UnitOfWorkOptions.Default 可写、不绑定连接。ReadsPrimary 让只读工作单元读主库，其余仍是只读的语义，没有从库的 Provider 上没有作用（ADR-0122）。

命名连接

一部分平台数据要放在另一个库里、并在业务事务进行中另行提交（ADR-0084）。SQLite 只有一个写者，业务事务写过之后同一个库文件上的另一个事务要等它结束，工作流的租约行因此要放在另一个库文件。

• 实体落点：AddRepository<TEntity, TKey>(connection) 把实体登记到命名连接（null 是 Provider 的缺省落点，非空不能是空白）；RepositoryRegistrations.ConnectionOf(type) 与 RegisteredEntity.Connection 取它。同一实体登记到两个连接（含一次为空、一次非空）抛 ArgumentException。普通工作单元里这样的实体照常参与整体事务，只是落在那个连接上，建表也建在那里。
• 绑定连接的工作单元：UnitOfWorkOptions(Connection: name) 只在这个连接上读写——实体必须落在它上面（否则 PERSISTENCE_VALIDATION_004），事务只开在它上面，不牵动作用域里的其他连接（包括默认连接）。连接名空白抛 ArgumentException。
• Provider：SqlSugar 是客户端里同名 ConfigId 的连接（方式一在 XiHan:Persistence:SqlSugar:Connections:<name> 声明）；EF Core 在 XiHan:Persistence:EntityFrameworkCore:Connections:<name> 声明，一个 DbContext 一个连接，绑定连接的工作单元把本作用域的 DbContext 建在那个连接上，登记到命名连接的实体只能在这样的工作单元里读写（普通工作单元里取用 PERSISTENCE_UNAVAILABLE_008，ADR-0087）；内存实现不支持，登记到命名连接在装配时、绑定连接的工作单元在 BeginAsync 抛出携带 PERSISTENCE_UNAVAILABLE_008 的 FrameworkException。

索引声明

框架自己的表（发件箱、审计、授予、翻译、调度、工作流）与应用实体一样，用本包的 [EntityIndex] 声明索引，不直接标 SqlSugar 的 [SugarIndex] 或 EF Core 的 [Index]：实体只依赖本包，换 Provider 不改实体（RFC-0005「索引声明」，ADR-0072）。

[EntityIndex(nameof(TenantId), nameof(Code), IsUnique = true)]   // UX_Order_TeId_Co
[EntityIndex(nameof(Status), nameof(CreatedAt))]                 // IX_Order_St_CrAt
public sealed class Order : IEntity<Guid>, IMultiTenant, ISoftDeletable { … }

• 命名：IX_（唯一 UX_）+ 表名 + 每列的缩写（属性名每个词取前两个字符：TenantId → TeId、NextFireAt → NeFiAt），下划线连接；表名里字母、数字、下划线以外的字符换成下划线。全名不超过 EntityIndexes.MaxNameLength（63，PostgreSQL 的标识符上限），超过即报错、不截断。
• 软删除：软删除实体（ISoftDeletable）的唯一索引只约束未删除的行（部分唯一索引：列就是声明的列，条件 IsDeleted = false，ADR-0081）——同一业务键删除、重建、再删除任意多次都不冲突，未删除的行之间唯一。只有 PostgreSQL、SQLite、SQL Server 支持部分唯一索引，其余数据库（MySQL、Oracle 等）上有这样的声明即启动失败（PERSISTENCE_UNAVAILABLE_008），不退化成普通唯一索引；在那些数据库上要唯一约束，就把 IsDeleted 显式写进列（普通唯一索引，同一业务键最多一行已删除），或不声明唯一。EntityIndex.ExcludesDeleted 标出这类索引。
• 唯一索引里有可空列时，PostgreSQL、SQLite、MySQL 不约束含 NULL 的行（SQL Server 把 NULL 当相等；EF Core 在 SQL Server 上给这种唯一索引自动加 IS NOT NULL 过滤）；要让"全局"这类空值参与唯一性，存成非空的哨兵值（如授予表的空字符串租户）。
• 写入撞上唯一索引：关系型 Provider 在写入失败后核对（同一批里两项同键、库里另一行同键；更新把键改成已有的值同样算；部分唯一索引只比较未删除的行），返回 PERSISTENCE_CONFLICT_003（消息键 persistence.entity.unique_key_conflict，参数 entity、index），这次写入的项统一报告，工作单元随后只能回滚、调用以同一错误结束（与写入阶段才发现的标识重复相同）。核对不到的（大小写不敏感排序规则下只差大小写、SqlSugar 上与本工作单元先前未提交的行冲突、键含空值）异常原样抛出。
• 声明错误（没有列、列名空白或重复、列不是公开实例属性、名字超长、同一实体两个索引同名或同列）在 Provider 建模 / 建表时抛 InvalidOperationException。内存实现不建索引、不校验唯一性。

运行时数据源

应用按自己的记录连外部库（代码生成的外部数据源、零代码运行时等），由单例 DataSourceRegistry 管（RFC-0005「运行时数据源」，ADR-0078）。支持它的持久化 Provider 经 AddDataSourceProvider<T>(configuration) 登记自己的 IDataSourceProvider（目前是 SqlSugar）；EF Core 与内存实现只登记注册表，取用与测试连接返回 PERSISTENCE_UNAVAILABLE_008。运行时数据源与应用自己的连接互不相干：不进作用域客户端、不参与实体落点、不进工作单元，约定连接 default / shard 与租户分片照旧。

var definition = new DataSourceDefinition("codegen-42", DatabaseTypes.PostgreSql, decryptedConnectionString);
var tested = await registry.TestAsync(definition, ct);           // 测试连接：不登记、不占名额
var source = await registry.GetOrAddAsync(definition, ct);       // 同定义复用，定义变了替换并释放旧的
await registry.RemoveAsync([definition.Name], ct);               // 记录改了、停用或删了：显式失效（批量）

• 定义：名字 ^[a-z0-9][a-z0-9-]{0,63}$（default 保留给缺省连接）；数据库类型不区分大小写，常用名在 DatabaseTypes，Provider 认得哪些由 Provider 决定；Describes 比名字、类型（不区分大小写）与连接串（区分大小写）。
• 失效：显式 RemoveAsync 加定义比对，不用配置变化令牌（定义来自应用的库）。注册表是进程内的，多实例时别的实例在下一次以新定义 GetOrAddAsync 时替换；所以每次使用都以记录里当前的定义 GetOrAddAsync，不要只按名字 GetAsync。
• 容量：XiHan:Persistence:DataSources:MaxCount（缺省 64，1–1024），满了再登记新名字返回 PERSISTENCE_UNAVAILABLE_007，不淘汰已有的；替换同名的不占名额。
• 健康：每个数据源一条 persistence.datasource.<name>（数据 databaseType、provider），按 XiHan:Persistence:DataSources:HealthProbeIntervalSeconds（缺省 15，也是单次探测超时）在后台探连通性（关系型 Provider 走一次数据库往返，ADR-0123）；尚未探过 Started，成功 Ready，失败或超时 Degraded（PERSISTENCE_UNAVAILABLE_006），不影响 readiness。
• 失败：连不上 PERSISTENCE_UNAVAILABLE_006（参数 name、reason）；数据库类型不认识或连接串格式错 PERSISTENCE_VALIDATION_006（同名的已登记实例不受影响）；GetAsync 没有登记 PERSISTENCE_NOTFOUND_002。
• 机密：DataSourceDefinition.ToString() 不含连接串；reason 取驱动异常的消息链，经 ConnectionStrings.Redact / Describe 把整串连接串与口令类键（键名含 password、pwd、secret、token、key）的值换成 ***；主机名、端口、库名、用户名不算机密，驱动消息里有就保留（脱敏范围已定，ADR-0084；选项打印遮蔽登录用户名不扩到这里，ADR-0093）。日志只记名字与数据库类型。

库结构读取与实体目录

ISchemaReader 读关系库的结构，IEntityCatalog 枚举已登记的实体（RFC-0005「库结构读取与实体目录」，ADR-0078）。SqlSugar 实现两者；EF Core 与内存实现只实现实体目录，读结构返回 PERSISTENCE_UNAVAILABLE_008。

var page = await schema.ListTablesAsync(dataSource: null, new TableListQuery { Keyword = "order", Take = 50 }, ct);   // null = 应用的缺省连接
var tables = await schema.GetTablesAsync(definition, ["LegacyOrder", "Sys_Customer"], ct);                       // 运行时数据源：先按定义登记再读
var entities = await catalog.ListAsync(ct);                                                                       // 已登记实体的表、列、协议、索引

• 列表：按名字排序，Keyword 在名字与注释里包含匹配，Skip / Take 分页，返回过滤后的总数。分页越界不在构造 TableListQuery 时抛出：读结构的 Provider 先经 TableListQuery.Validate() 核对，Skip 为负或 Take 小于 1 返回 PERSISTENCE_VALIDATION_007，Take 超过 1000 返回 PERSISTENCE_VALIDATION_005（都是 400 的结果，不连库、不登记数据源；ADR-0084）。
• 批量读结构：一次最多 SchemaLimits.MaxTablesPerRead（100）张，超过整批 PERSISTENCE_VALIDATION_005；逐项结果与入参一一对应，找不到的表该项 PERSISTENCE_NOTFOUND_003；连接或读取失败整批 PERSISTENCE_UNAVAILABLE_006（原因已脱敏）；空集合不连库。GetTableAsync 是单项特例。
• 列：类型名（不含长度与精度）、序号、主键（一律不可空）、自增、可空、长度（只给字符与二进制类型的声明长度；没有上限的与其余类型为 null）、精度与小数位（decimal / numeric / number / money 族）、注释、缺省值原文；数据库没有的项为 null。
• 分表：已登记的分表实体（SqlSugar [SplitTable]）按表名模板把物理表折叠成一张逻辑表（Order_{year}{month}{day} → Order），PhysicalTables 新到旧，列取最新的物理表。
• 实体目录：每个登记的实体一条（重复登记只一条），表名与列名是映射声明的写法，分表是逻辑名；Protocols 标出聚合根、创建 / 修改时间、并发戳、软删除、多租户；Indexes 是 [EntityIndex] 推出的索引。

雪花标识

Profile 缺省只有 GuidV7；要 long 标识的应用显式装配 SnowflakeIdFeature：

// 机器位经分布式锁租约分配：装配任一 caching.distributed 的 Provider（先后不限）
builder.AddXiHan(x => x.UseFeature<InMemoryCachingFeature>().UseFeature<SnowflakeIdFeature>());
// 或配置 XiHan:Persistence:Snowflake:WorkerId=7 固定机器位，不需要缓存 Provider

警告：上例的 InMemoryCachingFeature 只在一个进程内加锁，只适合单实例。多实例部署时每个实例都会租到机器位 0，生成重复的标识。多实例要装配跨进程的 caching.distributed Provider（如 Caching.Redis），或给每个实例配置互不相同的 WorkerId（如 StatefulSet 序号）。

• 位布局：符号位 0，41 位自 epoch 起的毫秒（约 69.7 年）、10 位机器位、12 位序列；单实例每毫秒最多 4096 个，用尽等下一毫秒；线程安全。
• 机器位租约：没有配置 WorkerId 时启动期从 0 起逐个尝试锁 persistence:snowflake:worker:<n>，取第一个空位；锁不续约，续约 = 释放再获取同一机器位，空位被别的实例拿走或锁存储不可达都按丢失处理并重新分配；本地按获取时刻 + 存活时间判定有效，到期未续上即没有机器位。容器里没有 IDistributedLock、或 1024 个机器位都被占用时启动失败，不做随机机器位。健康项 persistence.snowflake.worker：持有 Ready，没有 Degraded（PERSISTENCE_UNAVAILABLE_005）。
• 启停顺序：清单声明可选依赖 caching.distributed@1，装配了缓存 Provider 时它先于雪花特性启动、后于雪花特性停止，租约在锁存储可用时取得与释放，与 UseFeature 的先后无关；固定机器位又没有任何 caching.distributed Provider 时按可选依赖缺失，特性是 Degraded（生成不受影响）。
• 失败：NewId() 返回 long，失败只能抛出 FrameworkException——回拨超过阈值 PERSISTENCE_UNAVAILABLE_004（等时钟追上后自动恢复），没有机器位 PERSISTENCE_UNAVAILABLE_005；两者都是 UNAVAILABLE。调用里抛出时由本特性登记在 Resilience 阶段末尾的中间件转为同码的结果（消息键 persistence.snowflake.clock_moved_backwards / persistence.snowflake.worker_unavailable），HTTP 映射为可重试的 503、gRPC 为 Unavailable；它在幂等与工作单元之外，工作单元已回滚、幂等标记已清除。管道之外直接调用生成器仍是异常（ADR-0063）。时钟早于 epoch 是配置错误，启动即失败。
• 排障：generator.Parse(id) 或 SnowflakeId.Parse(id, epoch) 还原生成时刻、机器位与序列。
• 线格式与前端精度：标识在 JSON 里保持 number（后端标准类型，不加字符串转换器）。超过 2^53（约 9.007 × 10^15）的整数在 JavaScript 的 number 里会丢精度，而雪花标识从 epoch 之后约 25 天起就全部超过 2^53——前端必须用能保留大整数的方式解析（JSON.parse 的 BigInt reviver、按字符串读取原文）并以字符串或 BigInt 保存与回传，不能 Number() 换算。

依赖方向

依赖 XiHan.Framework.Kernel、XiHan.Framework.Domain 与 XiHan.Framework.Caching.Abstractions（雪花机器位租约用它的 IDistributedLock）。被 Persistence.InMemory、Persistence.EntityFrameworkCore、Persistence.SqlSugar 等实现包引用。

状态

P2：可用。