存储引擎架构与多数据库规划

flowchart TD
    subgraph DevLayer ["1. 业务与开发者层 (Developer API)"]
        Dev["业务控制器 / 领域逻辑服务 / AutoCRUD 引擎"]
        Call["统一方法调用: db.records().create(...) / db.records().list(...)"]
        Dev --> Call
    end

    subgraph FacadeLayer ["2. 统一门面与接口契约 (foundry_storage::traits)"]
        Call --> Facade["统一门面 Database"]
        Facade --> RecordEngine["RecordStoreEngine (动态记录契约)"]
        Facade --> ModelEngine["ModelStoreEngine (模型元数据契约)"]
        Facade --> SysEngine["SystemStoreEngine (子系统管理契约)"]
        Facade --> ConfigEngine["ConfigStoreEngine (全局配置契约)"]
        Facade --> AdminEngine["AdminStoreEngine (管理员与RBAC契约)"]
        Facade --> AuditEngine["AuditStoreEngine (审计日志契约)"]
    end

    subgraph SPILayer ["3. SPI 注册中心与调度 (foundry_storage::spi)"]
        Facade -.->|"连接串协议自动探测 / 环境变量"| Registry["StorageRegistry (驱动工厂注册中心)"]
        Registry --> ProviderTrait["trait StorageDriverProvider"]
    end

    subgraph BuiltinEngines ["4. 已落地数据库策略引擎"]
        ProviderTrait --> PgEng["1. PostgresProvider (PostgreSQL 14+, 已完成)"]
        ProviderTrait --> MySqlEng["2. MySqlProvider (MySQL 8.0+, 已完成)"]
        ProviderTrait --> MariaEng["3. MariaDbProvider (MariaDB 10.5+, 已完成)"]
        ProviderTrait --> MongoEng["4. MongoProvider (MongoDB 6.0+, 已完成)"]
    end

    subgraph FutureEngines ["5. 未来预留扩展插槽 (Future Targets)"]
        ProviderTrait -.->|"零改动核心代码扩充"| SqliteEng["SqliteProvider (单文件嵌入式)"]
        ProviderTrait -.->|"零改动核心代码扩充"| MssqlEng["MssqlProvider (SQL Server)"]
    end

crates/foundry_storage/
├── Cargo.toml                         # Feature Flags 控制 (postgres, mysql, mariadb, mongodb)
├── migrations/                        # 各引擎特化的全量初始化与方言迁移脚本
│   ├── postgres/                      # PostgreSQL 方言脚本 (BIGSERIAL, JSONB, GIN, PL/pgSQL)
│   │   └── init.sql
│   ├── mysql/                         # MySQL 方言脚本 (AUTO_INCREMENT, JSON, 复合索引)
│   │   └── init.sql
│   └── mariadb/                       # MariaDB 方言脚本 (AUTO_INCREMENT, JSON, 复合索引)
│       └── init.sql
└── src/
    ├── lib.rs                         # 统一导出门面 Database 与全部业务 Store Traits
    ├── facade.rs                      # Database 结构体与统一 API 暴露
    ├── entities.rs                    # 通用实体模型 (System, Model, Record, Admin, AuditLog)
    ├── traits/                        # 【业务契约层】面向开发者的方法 Trait
    │   ├── mod.rs
    │   ├── records.rs                 # RecordStoreEngine: list, get_by_id, create, update, delete
    │   ├── models.rs                  # ModelStoreEngine: list_models, get_model, create_model...
    │   ├── systems.rs                 # SystemStoreEngine: list, get_by_slug, stats...
    │   ├── configs.rs                 # ConfigStoreEngine: list, get_aggregated, update...
    │   ├── admins.rs                  # AdminStoreEngine: list, get_by_username, create...
    │   └── audit.rs                   # AuditStoreEngine: insert, list...
    ├── spi/                           # 【SPI 扩展层】驱动发现与接入契约
    │   ├── mod.rs
    │   ├── provider.rs                # StorageDriverProvider trait 定义
    │   └── registry.rs                # StorageRegistry: 驱动注册与根据连接串查找
    ├── orm/                           # 【ORM 优先架构层】Prisma 风格强类型模型与查询构建器
    │   ├── mod.rs
    │   ├── compiler.rs                # 动态方言 DDL 编译器 (PostgreSQL, MySQL, MariaDB)
    │   ├── dialect.rs                 # 方言枚举与参数占位符 ($1 vs ?)
    │   ├── models.rs                  # 7 大核心平台表的 EntitySchema 规范定义
    │   ├── query.rs                   # 封装的 CRUD 查询构建器 (OrmSelect, OrmInsert, OrmUpdate, OrmDelete)
    │   └── registry.rs                # 线程安全全局 ORM 模型注册表 (OrmRegistry)
    └── engines/                       # 【具体策略实现层】各个数据库的特化方言与驱动实现
        ├── mod.rs
        ├── postgres/                  # PostgreSQL 引擎实现
        │   ├── mod.rs
        │   ├── provider.rs            # PostgresProvider (ORM 编译 DDL)
        │   ├── records.rs             # ORM 查询构建器 CRUD、GIN 索引与 JSONB 操作
        │   └── stores.rs              # models, systems, admins 等实现
        ├── mysql/                     # MySQL 引擎实现
        │   ├── mod.rs
        │   ├── provider.rs            # MySqlProvider (ORM 编译 DDL)
        │   ├── records.rs             # ORM 查询构建器 CRUD、自增主键与延迟关联分页
        │   └── stores.rs              # 各基础表实现
        ├── mariadb/                   # MariaDB 专属引擎实现
        │   ├── mod.rs
        │   └── provider.rs            # MariaDbProvider (ORM 编译 DDL)
        └── mongodb/                   # MongoDB 原生文档引擎 (Fallback 策略)
            ├── mod.rs
            ├── provider.rs            # MongoProvider (init.js 脚本)
            ├── records.rs             # 原生 BSON 文档 CRUD 与 Wildcard 动态索引
            ├── counters.rs            # 保证外部 i64 主键兼容的原子计数器序列
            └── stores.rs              # 集合存储实现

#[async_trait]
pub trait StorageDriverProvider: Send + Sync {
    /// 驱动标识，如 "postgres", "mysql", "mariadb", "mongodb"
    fn driver_name(&self) -> &'static str;

    /// 判断连接字符串是否归当前 Provider 处理 (例如 starts_with("mysql://"))
    fn supports(&self, connection_url: &str) -> bool;

    /// 初始化连接池并构建全套仓储引擎
    async fn create_engines(
        &self,
        connection_url: &str,
        max_connections: u32,
    ) -> AppResult<StorageEngineSet>;

    /// 执行该数据库特有的初始化与方言迁移脚本
    async fn run_migrations(&self, connection_url: &str) -> AppResult<()>;

    /// 获取由代码 ORM 动态编译或内嵌在二进制驱动中的基准方言 DDL / 初始化脚本
    fn get_baseline_ddl(&self) -> String;

    /// 默认迁移脚本文件名 (如 init.sql 或 init.js)
    fn default_migration_filename(&self) -> &'static str {
        "init.sql"
    }
}

#[async_trait]
pub trait RecordStoreEngine: Send + Sync {
    async fn list(
        &self,
        system_slug: &str,
        model_slug: &str,
        query: RecordQuery,
    ) -> AppResult<PaginatedData<ModelRecordEntity>>;

    async fn get_by_id(
        &self,
        system_slug: &str,
        model_slug: &str,
        id: i64,
    ) -> AppResult<ModelRecordEntity>;

    async fn create(
        &self,
        system_slug: &str,
        model_slug: &str,
        data: serde_json::Value,
    ) -> AppResult<ModelRecordEntity>;

    async fn update(
        &self,
        system_slug: &str,
        model_slug: &str,
        id: i64,
        data: serde_json::Value,
    ) -> AppResult<ModelRecordEntity>;

    async fn delete(
        &self,
        system_slug: &str,
        model_slug: &str,
        id: i64,
    ) -> AppResult<()>;
}

#[derive(Clone)]
pub struct Database {
    records: Arc<dyn RecordStoreEngine>,
    models: Arc<dyn ModelStoreEngine>,
    systems: Arc<dyn SystemStoreEngine>,
    configs: Arc<dyn ConfigStoreEngine>,
    admins: Arc<dyn AdminStoreEngine>,
    audit: Arc<dyn AuditStoreEngine>,
}

impl Database {
    pub async fn connect(url: &str, max_connections: u32, auto_migrate: bool) -> AppResult<Self>;

    pub fn records(&self) -> &dyn RecordStoreEngine { self.records.as_ref() }
    pub fn models(&self) -> &dyn ModelStoreEngine { self.models.as_ref() }
    pub fn systems(&self) -> &dyn SystemStoreEngine { self.systems.as_ref() }
    pub fn configs(&self) -> &dyn ConfigStoreEngine { self.configs.as_ref() }
    pub fn admins(&self) -> &dyn AdminStoreEngine { self.admins.as_ref() }
    pub fn audit(&self) -> &dyn AuditStoreEngine { self.audit.as_ref() }
}

[阶段 0: 核心 SPI 与 PostgreSQL (已完成)] ➔ [阶段 1: MySQL 8.0+ 引擎 (已完成)]
                                                 │
[阶段 4: 生态发布与 CLI 工具链] ⬅ [阶段 3: MongoDB (已完成)] ⬅ [阶段 2: MariaDB (已完成)]