iTool.DataFabric.Provider 4.0.0

iTool.DataFabric.Provider

iTool.DataFabric.Provider 同时提供两条明确的基础能力：

1. 兼容现有 Orleans Grain 的单写、多读热状态通道（HotStateWriterGrain / HotStateReaderGrain）；
2. 面向业务数据的统一 StateMode、ListMode、AggregateMode、BatchMode 契约（IDataFabricProvider）。统一数据操作以业务数据库为唯一事实源，列表直接走索引查询，聚合读取预计算表，批量作业使用集合 SQL。

热状态通道用于低延迟状态读取，不应被当作列表或统计数据库。新业务的列表、聚合、批量变更必须使用统一数据契约，避免再扩展 QueryGrain。

Provider 首发版本与 iTool.ShareLibrary.Framework 当前版本保持一致，由仓库根目录的 iTool.SharedVersion.props 统一控制。

Silo 注册

先由宿主框架注册共享的 IConnectionMultiplexer，再注册 DataFabric。宿主可以直接在 IServiceCollection 中注册（Runtime 基础层默认会做这一步），或使用 Orleans Silo 扩展：

// 连接由宿主创建和释放；DataFabric 不会自行 Connect/Dispose。
silo.Services.AddSingleton<IConnectionMultiplexer>(_ =>
    ConnectionMultiplexer.Connect("redis.example:6379,password=***"));
silo
    .UseDevelopFrameworks([IPEndPoint.Parse("127.0.0.1:7000")])
    .AddDataFabricProvider(options =>
    {
    options.ProviderName = "DataFabric";
    options.KeyPrefix = "itool:datafabric";
        options.Database = 0;
        options.ReaderUpdateDebounce = TimeSpan.FromMilliseconds(200);
        // 热状态逐读监控默认关闭，避免监控写入限制内存优先的读路径。
        // options.EnableHotStateMonitoring = true;
});

统一数据库操作还需要宿主注册逻辑 Provider 对应的 keyed executor：

services.AddKeyedDatabaseOperationExecutor("orders-db");
services.AddDataFabricOperations();
services.AddDataFabricMonitor(options =>
{
    options.RetentionWindow = TimeSpan.FromHours(24);
    options.MaxSlowQueryRecords = 500;
});

业务开发规范和四种模式的完整契约见 docs/data-fabric-business-development-manual.zh-CN.md。

DataFabric 不会读取连接字符串、创建连接池或 Dispose 共享连接。

在 iTool.MyScriptRuntimes 宿主中，推荐使用 builder.UseSharedRedisConnection(connectionString)；它注册一个由 DI 所有的共享 IConnectionMultiplexer。UseRedisEphemeralServices 也会复用这条连接。Redis 在这里仅 承载 DataFabric 的热点状态/Revision/Change Feed，以及 presence/cache 等明确的短期数据； 源码和配置通过以 Git repository/SHA/path 定位的 iDB 文件协议访问，Git refs/SHA 仍是内容身份； Runtime 执行日志、订阅、触发器和发布指针由 Orleans Grain State/Stream/Reminder 管理， 声明性数据丢失时从固定 Git/iDB commit 冷启动，资产和构建对象由 S3 负责。SQL Server 仅作为宿主显式选择的兼容性 authority，不是 Runtime 的隐含第二权威。

生产宿主应为 DataFabric 配置独立 Redis database（默认 0），并将 Runtime 的 RedisEphemeralRuntimeOptions.Database（默认 1）用于 presence/cache，避免缓存清理触及 HotState 权威键空间。

Writer

业务 Grain 只重写 WriteStateAsync(TState, CancellationToken)，并在业务端口调用基类提供的 WriteStateAsync()：

[StorageProvider(ProviderName = "DataFabric")]
public sealed class OrderGrain : HotStateWriterGrain<OrderState>, IOrderGrain
{
    protected override ValueTask WriteStateAsync(
        OrderState state,
        CancellationToken cancellationToken = default)
    {
        state.Status = "Paid";
        return ValueTask.CompletedTask;
    }

    public Task PayAsync() => WriteStateAsync();
}

基类在已提交状态副本上执行一次业务变更，并立即通过 Redis Lua 完成 CAS 原子提交。调用成功即表示权威状态已确认；RequestId、Revision、Change Feed 和 Outbox 由基础层内部维护。业务代码只需要调用 Orleans 兼容的 WriteStateAsync / ClearStateAsync，不需要调用 Redis API。

多状态注入

Provider 同时实现 Orleans 官方 IGrainStorage，因此一个 Grain 可以注入多个相互独立的状态：

private readonly IPersistentState<ProfileState> _profile;
private readonly IPersistentState<CartState> _cart;

public UserGrain(
    [PersistentState("profile", "profileStore")] IPersistentState<ProfileState> profile,
    [PersistentState("cart", "cartStore")] IPersistentState<CartState> cart)
{
    _profile = profile;
    _cart = cart;
}

public async Task SetProfileAsync(string displayName)
{
    _profile.State.DisplayName = displayName;
    await _profile.WriteStateAsync();
}

宿主注册对应的命名 Provider：

silo.AddDataFabricProvider("profileStore");
silo.AddDataFabricProvider("cartStore");

每个状态独立进行 CAS、RequestId 幂等、Change Feed 和 Reader 失效通知，因此多个状态不会共享可变对象，也不会互相覆盖。

Reader

public sealed class OrderReaderGrain
    : HotStateReaderGrain<OrderState>, IOrderReaderGrain
{
    public async Task<OrderState> GetAsync()
    {
        await ReadStateAsync();
        return State;
    }
}

Reader 基类使用 StatelessWorker 放置，同一业务 key 可以在多个 activation 中维护热副本。Redis Pub/Sub 消息只是低成本的 Revision 提示，不携带状态、事件或业务载荷；Reader 使用 Rx.NET Subject 和 Throttle 合并中间提示，从 durable Change Feed 追赶缺失 Revision，并以最新 Redis Snapshot 对账。读取先执行轻量 Revision 检查，版本一致时直接返回内存状态，落后或无法确认时立即回源 Snapshot，不能返回未经确认的旧值。Reader 注销时订阅、Rx 管道和内存副本一起释放。热状态逐读监控默认关闭（EnableHotStateMonitoring = false），需要审计每次状态读时再打开；统一数据库作业的 IDataFabricOperationPipeline 监控不受影响。

Writer 与 Reader 的默认状态键由 TState 和 Grain primary key 组成，因此两类 Grain 使用同一个 primary key 即可共享状态；复杂场景可以覆盖 DataFabricStateKey。