sz_orm_core/

lib.rs

//! # SZ-ORM — 鲜视达 ORM
//!
//! Rust 异步 ORM 工作空间（原型阶段），兼容 ThinkORM 风格。
//!
//! ## 架构概览
//!
//! SZ-ORM 工作空间由 **43 个成员** 组成（41 个 sz-orm-* lib + cli + examples）：
//!
//! ### 核心引擎 (sz-orm-core)
//! | 模块 | 功能 |
//! |------|------|
//! | `model` | `Model` trait — 定义表名、主键、时间戳、软删除、关联关系 |
//! | `query` | `QueryBuilder<M>` — 链式 API，支持 SELECT/INSERT/UPDATE/DELETE/聚合/分页/JOIN |
//! | `dialect` | 多数据库方言 — MySQL (反引号)、PostgreSQL (双引号)、SQLite、Oracle 23ai |
//! | `pool` | 异步连接池 — 可配置大小、超时、空闲回收、健康检查、最大生命周期 |
//! | `transaction` | ACID 事务 — 隔离级别、保存点、`TransactionManager` 多事务管理 |
//! | `migration` | 文件迁移系统 — up/down/rollback/reset/refresh，含 `SchemaBuilder` |
//! | `cache` | 多级缓存 — `MemoryCache`、`MultiLevelCache`，支持 TTL |
//! | `value` | 统一值类型 — 20 种变体 (整数/浮点/字符串/字节/UUID/日期/JSON/数组) |
//! | `db_type` | 数据库类型枚举 — MySQL、PostgreSQL、SQLite、Oracle、Redis、MongoDB 等 11 种 |
//! | `error` | 错误类型体系 — `DbError`(20 变体)、`PoolError`、`CacheError`、`TxError` |
//!
//! ### 数据库适配器
//! - **sz-orm-sqlx** — sqlx 适配器，连接真实 MySQL/PostgreSQL/SQLite/Oracle
//! - **sz-orm-sql-validator** — SQL 校验与注入检测
//!
//! ### 扩展生态包 (18 个)
//! | 包名 | 功能 |
//! |------|------|
//! | sz-orm-crypto | 加密原语 (AES-256-GCM, PBKDF2, HMAC-SHA256) |
//! | sz-orm-auth | JWT 鉴权 (HS256) |
//! | sz-orm-scheduler | Cron 定时任务调度 |
//! | sz-orm-mqtt | MQTT 客户端 (rumqttc) |
//! | sz-orm-websocket | WebSocket 服务端 (tokio-tungstenite) |
//! | sz-orm-queue | 消息队列 (RabbitMQ/lapin, Kafka, NATS, ActiveMQ, RocketMQ, Pulsar) |
//! | sz-orm-storage | 对象存储 (S3/阿里云/腾讯云/华为云/七牛/又拍云/本地) |
//! | sz-orm-ai | AI 集成 (Embedding, RAG, Vector) |
//! | sz-orm-grpc | gRPC 服务/客户端 |
//! | sz-orm-graphql | GraphQL 查询支持 |
//! | sz-orm-es | Elasticsearch 集成 |
//! | sz-orm-tracing | 分布式追踪 |
//! | sz-orm-logger | 日志系统 |
//! | sz-orm-swagger | API 文档生成 |
//! | sz-orm-masking | 数据脱敏 |
//! | sz-orm-health | 健康检查 |
//! | sz-orm-audit | 审计日志 |
//! | sz-orm-batch | 批量操作 |
//!
//! ### 高级特性包 (6 个)
//! | 包名 | 功能 |
//! |------|------|
//! | sz-orm-dtx | 分布式事务 |
//! | sz-orm-rw | 读写分离 |
//! | sz-orm-sharding | 分库分表 |
//! | sz-orm-limit | 限流控制 |
//! | sz-orm-config | 配置管理 |
//! | sz-orm-mig | 迁移管理增强 |
//!
//! ### 平台支持
//! - **sz-orm-wasm** — WebAssembly 编译目标
//! - **sz-orm-lc** — 本地/边缘计算
//! - **sz-orm-back** — 备份与恢复
//!
//! ## 快速入门
//!
//! ```rust,ignore
//! use sz_orm_core::*;
//!
//! // 1. 定义模型
//! #[derive(Clone)]
//! struct User {
//!     id: i64,
//!     name: String,
//!     email: String,
//! }
//!
//! impl Model for User {
//!     type PrimaryKey = i64;
//!     fn table_name() -> &'static str { "users" }
//!     fn pk(&self) -> Self::PrimaryKey { self.id }
//!     fn set_pk(&mut self, pk: Self::PrimaryKey) { self.id = pk; }
//! }
//!
//! // 2. 构建查询
//! let dialect = get_dialect(DbType::MySQL).unwrap();
//! let sql = QueryBuilder::<User>::new(dialect)
//!     .table("users")
//!     .select(vec!["id", "name", "email"])
//!     .where_eq("status", Value::String("active".to_string()))
//!     .order_by("created_at")
//!     .order_desc("id")
//!     .limit(10)
//!     .build_select();
//!
//! // 3. 执行前校验
//! QueryBuilder::<User>::new(get_dialect(DbType::MySQL).unwrap())
//!     .table("users")
//!     .select(vec!["id", "name"])
//!     .validate()?; // 校验 SQL 语法、注入、括号平衡
//!
//! // 4. 其他操作
//! let mut data = std::collections::HashMap::new();
//! data.insert("name".to_string(), Value::String("Alice".to_string()));
//! data.insert("age".to_string(), Value::I64(25));
//!
//! let insert_sql = QueryBuilder::<User>::new(dialect)
//!     .table("users")
//!     .build_insert(&data);
//!
//! let update_sql = QueryBuilder::<User>::new(get_dialect(DbType::MySQL).unwrap())
//!     .table("users")
//!     .where_eq("id", Value::I64(1))
//!     .build_update(&data);
//!
//! let delete_sql = QueryBuilder::<User>::new(get_dialect(DbType::MySQL).unwrap())
//!     .table("users")
//!     .where_eq("id", Value::I64(1))
//!     .build_delete();
//! ```
//!
//! ## 支持的数据库
//!
//! | 数据库 | 方言实现 | 真实连接 | 引用方式 |
//! |--------|---------|---------|---------|
//! | MySQL | `MySqlDialect` (`` ` `` 反引号) | sz-orm-sqlx | ✅ |
//! | PostgreSQL | `PostgreSqlDialect` (`"` 双引号) | sz-orm-sqlx | ✅ |
//! | SQLite 3.35+ | `SqliteDialect` (`"` 双引号) | sz-orm-sqlx | ✅ |
//! | Oracle 23ai | `OracleDialect` (类型自动映射) | sz-orm-sqlx | ✅ |
//!
//! 通过 `get_dialect(DbType::MySQL)` 获取方言实例。每个方言处理：
//! - 标识符引用风格
//! - 字符串转义规则
//! - 分页语法 (LIMIT/OFFSET vs OFFSET/FETCH)
//! - JSON 提取函数 (JSON_EXTRACT vs #>> vs json_extract vs JSON_VALUE)
//! - 全文搜索 (MATCH AGAINST vs to_tsvector vs CONTAINS)
//! - 布尔转整数 (IF/CASE)
//! - 自增关键字 (AUTO_INCREMENT/GENERATED BY DEFAULT AS IDENTITY)
//!
//! ## 核心功能详解
//!
//! ### QueryBuilder API
//!
//! 大部分查询方法返回 `Self`，支持链式调用；`select`/`having` 等校验类方法
//! 返回 `Result<Self>`（审计 M-5/M-6 后列名/聚合表达式经标识符校验）：
//!
//! ```rust,ignore
//! // 基础查询
//! QueryBuilder::<M>::new(dialect)
//!     .table("users")
//!     .select(vec!["id", "name"])?                 // 列名校验 + quote
//!     .where_eq("status", Value::String("active".to_string()))    // AND
//!     .or_where_eq("role", Value::String("admin".to_string()))     // OR
//!     .where_in("id", vec![Value::I64(1), Value::I64(2)])
//!     .where_between("age", Value::I64(18), Value::I64(30))
//!     .where_null("deleted_at")
//!     .order_by("created_at")
//!     .order_desc("id")
//!     .group_by("status")
//!     .having(AggExpr::CountStar, HavingOp::Gt, Value::I64(5))?   // 参数化 HAVING
//!     .limit(20)
//!     .offset(40)
//!     .page(3, 20)                       // page=3, page_size=20
//!     .join_inner("posts", "users.id", "posts.user_id")
//!     .join_left("profiles", "users.id", "profiles.user_id")
//!     .build_select();
//!
//! // 聚合函数
//! builder.build_count();    // SELECT COUNT(*)
//! builder.build_exists();   // SELECT EXISTS(...)
//! builder.build_max("score");
//! builder.build_min("price");
//! builder.build_sum("amount");
//! builder.build_avg("value");
//! ```
//!
//! ### SQL 校验
//!
//! ```rust,ignore
//! // 编译时 + 运行时双重校验
//! builder.validate()?;              // 校验 SELECT
//! builder.validate_insert(&data)?;  // 校验 INSERT（含空数据检测）
//! builder.validate_update(&data)?;  // 校验 UPDATE（含空数据检测）
//! builder.validate_delete()?;       // 校验 DELETE
//!
//! // 校验内容包括：SQL 语法、注入检测、括号平衡、
//! // 表名/列名合法性、JOIN 列名校验
//! ```
//!
//! ### Model Trait
//!
//! ```rust,ignore
//! pub trait Model: Send + Sync + Sized + 'static {
//!     type PrimaryKey: Send + Sync + Debug + Display + Clone + Default;
//!
//!     fn table_name() -> &'static str;          // 表名（必需）
//!     fn pk_name() -> &'static str { "id" }     // 主键列名
//!     fn pk(&self) -> Self::PrimaryKey;         // 获取主键值
//!     fn set_pk(&mut self, pk: Self::PrimaryKey); // 设置主键值
//!     fn foreign_key(relation: &str) -> String; // 外键命名 "user_id"
//!     fn timestamp_fields() -> Option<TimestampFields>; // 自动时间戳
//!     fn soft_delete_field() -> Option<&'static str>;   // 软删除字段
//! }
//!
//! // ModelExt 扩展
//! pub trait ModelExt: Model {
//!     fn columns() -> Vec<&'static str>;     // 所有列
//!     fn fillable() -> Vec<&'static str>;    // 可填充列
//!     fn guarded() -> Vec<&'static str>;     // 保护列（默认含主键）
//!     fn hidden() -> Vec<&'static str>;      // 隐藏列（不序列化）
//!     fn relations() -> HashMap<&str, Relation>; // 关联关系
//!     fn fill(&mut self, data: HashMap<String, Value>); // 批量赋值
//!     fn to_json(&self) -> serde_json::Value; // 序列化
//! }
//!
//! // 四种关联关系
//! // BelongsTo   — 多对一（Order → User）
//! // HasMany     — 一对多（User → Orders）
//! // HasOne      — 一对一（User → Profile）
//! // BelongsToMany — 多对多（User ↔ Role，通过中间表）
//! ```
//!
//! ### 连接池
//!
//! ```rust,ignore
//! // 通过 Builder 配置
//! let config = PoolConfigBuilder::new()
//!     .max_size(100)       // 最大连接数
//!     .min_idle(10)        // 最小空闲连接
//!     .acquire_timeout(30) // 获取超时（秒）
//!     .idle_timeout(600)   // 空闲超时（秒）
//!     .max_lifetime(1800)  // 最大生命周期（秒）
//!     .build()?;
//!
//! let pool = Pool::new(config, factory)?;
//! let conn = pool.acquire().await?;  // 获取连接（带超时）
//! pool.release(conn).await;         // 归还连接
//! pool.status().await;               // PoolStatus { idle, active, max, min }
//! pool.reap_idle().await;           // 回收空闲连接
//! pool.close_all().await;           // 关闭所有连接
//! ```
//!
//! ### 事务
//!
//! ```rust,ignore
//! // 事务选项
//! let opts = TransactOptions::default()
//!     .with_isolation(IsolationLevel::Serializable)
//!     .read_only()
//!     .with_timeout(Duration::from_secs(30));
//!
//! let mut tx = Transaction::new(conn, opts);
//! tx.execute("INSERT INTO users VALUES (1)").await?;
//! tx.query("SELECT * FROM users").await?;
//!
//! // 保存点（嵌套事务）
//! let sp = tx.savepoint().await?;         // SAVEPOINT sp_N
//! tx.rollback_to_savepoint(&sp).await?;   // ROLLBACK TO SAVEPOINT sp_N
//! tx.release_savepoint(&sp).await?;       // RELEASE SAVEPOINT sp_N
//!
//! tx.commit().await?;
//! // tx.rollback().await?;
//!
//! // TransactionManager：管理多个命名事务
//! let mgr = TransactionManager::new();
//! mgr.begin("tx1", conn, opts).await?;
//! mgr.commit("tx1").await?;
//! mgr.list().await;        // ["tx1"]
//! mgr.state("tx1").await;  // Some(TransactionState::Committed)
//! ```
//!
//! ### 迁移系统
//!
//! ```rust,ignore
//! // 文件命名：<version>_<name>_up.sql / <version>_<name>_down.sql
//! // 示例：001_create_users_up.sql, 001_create_users_down.sql
//!
//! let resolver = FileMigrationResolver::new(PathBuf::from("./migrations"));
//! let migrations = resolver.resolve(DbType::MySQL)?;
//!
//! let mut migrator = Migrator::new(MigrationContext::default())
//!     .add_migrations(migrations);
//!
//! migrator.migrate().await?;                     // 执行所有待迁移
//! migrator.up(Some("003")).await?;               // 执行到指定版本
//! migrator.down(Some("001")).await?;             // 回滚到指定版本
//! migrator.rollback("002").await?;               // 回滚单个迁移
//! migrator.reset().await?;                       // 全部回滚 + 重新执行
//! migrator.refresh().await?;                     // 同 reset
//! migrator.progress();                            // MigrationProgress { total, applied, pending }
//!
//! // SchemaBuilder：程序化建表
//! let sql = SchemaBuilder::new("users")
//!     .add_column(ColumnDef::new("id", "INT").not_null().auto_increment())
//!     .add_column(ColumnDef::new("name", "VARCHAR").length(255).not_null())
//!     .add_index(IndexDef::new("idx_name", vec!["name"]).unique())
//!     .add_foreign_key(
//!         ForeignKeyDef::new("fk_role", "role_id", "roles", "id")
//!             .on_delete("CASCADE")
//!     )
//!     .build(DbType::MySQL);
//! ```
//!
//! ### 值类型 (Value)
//!
//! ```rust,ignore
//! // 20 种变体，覆盖所有数据库类型
//! Value::Null | Bool(bool) | I8..I64 | U8..U64 | F32 | F64
//! | String(String) | Bytes(Vec<u8>) | Uuid(String) | Date(String)
//! | DateTime(String) | Time(String) | Json(String) | Array(Vec<Value>)
//!
//! // 类型转换
//! value.as_str()    // Option<&str>
//! value.as_i64()    // Option<i64>（支持 F32/F64/Bool/String→i64 转换）
//! value.as_f64()    // Option<f64>
//! value.as_bool()   // Option<bool>（支持 "true"/"1"/"yes"/"on" 等）
//! value.as_bytes()  // Option<&[u8]>
//! value.to_param()  // Cow<str> — SQL 参数格式
//!
//! // From 实现
//! let v: Value = 42i64.into();
//! let v: Value = "hello".into();
//! let v: Value = vec![1u8, 2u8].into();
//! ```
//!
//! ## 错误处理
//!
//! 统一错误类型体系，每种错误携带唯一错误码：
//!
//! ```rust,ignore
//! // DbError — 20 种变体，错误码 DB001-DB020
//! DbError::QueryError("...")
//! DbError::ConnectionRefused("...")
//! DbError::ConnectionTimeout("...")
//! DbError::NotFound("...")
//! DbError::ConstraintViolation("...")
//! // ... 等
//!
//! // PoolError — 6 种变体，错误码 PL001-PL006
//! PoolError::Exhausted | Timeout | AlreadyAcquired | InvalidConfig | ...
//!
//! // CacheError — 6 种变体，错误码 CH001-CH006
//! // TxError — 6 种变体（NotStarted, CommitFailed, SavepointError 等）
//!
//! // 便捷方法
//! DbError::query("test failed")        // 创建查询错误
//! DbError::connection("timeout")       // 创建连接错误
//! DbError::not_found("user #42")       // 创建未找到错误
//! err.is_retryable()                   // 是否可重试
//! err.error_code()                     // "DB001"
//! ```
//!
//! ## 验证方法
//!
//! SZ-ORM 通过 **7 线验证体系** 保证质量：
//!
//! | 验证方法 | 描述 | 测试文件 |
//! |---------|------|---------|
//! | **TDD** | 核心模块 115+ 单元测试 | `core.rs` |
//! | **集成** | 真实 MySQL/PG/SQLite/Oracle 端到端 | `integration_mysql.rs`, `integration_pg.rs`, `integration_sqlite.rs` |
//! | **Jepsen** | 29 并发正确性测试 + 10 真实 DB Jepsen | `jepsen.rs`, `real_db_jepsen.rs` |
//! | **Fuzz** | 11 边界/边缘案例发现 | `fuzz.rs` |
//! | **Stress** | 77 性能基准测试 | `stress.rs`, `core_bench.rs` |
//! | **Chaos** | 16 故障鲁棒性测试 | `chaos.rs` |
//! | **Formal** | 14 形式化验证不变量 | `formal.rs` |
//!
//! **总计：1,723 测试**（1,317 `#[test]` + 406 `#[tokio::test]`；部分需真实服务）
//!
//! ## 类型别名与常量
//!
//! ```rust,ignore
//! // 类型别名
//! pub type Shared<T> = Arc<T>;
//! pub type Boxed<T> = Box<T>;
//! pub type DbResult<T> = Result<T, DbError>;
//! pub type PoolResult<T> = Result<T, PoolError>;
//! pub type CacheResult<T> = Result<T, CacheError>;
//! pub type TxResult<T> = Result<T, TxError>;
//!
//! // 默认常量
//! pub const DEFAULT_BATCH_SIZE: usize = 1000;
//! pub const DEFAULT_ACQUIRE_TIMEOUT: u64 = 30;   // 秒
//! pub const DEFAULT_IDLE_TIMEOUT: u64 = 600;      // 秒
//! pub const DEFAULT_MAX_LIFETIME: u64 = 1800;     // 秒
//! pub const DEFAULT_MIN_IDLE: u32 = 5;
//! pub const DEFAULT_MAX_SIZE: u32 = 100;
//! ```
//!
//! ## 导出清单
//!
//! `use sz_orm_core::*;` 将导入以下模块的全部公共符号：
//!
//! - `async_trait` (重导出)、`bytes::Bytes`、`chrono::{DateTime, Utc}`、`serde::{Deserialize, Serialize}`
//! - `cache::*` — `Cache`, `MemoryCache`, `MultiLevelCache`, `CacheStats`
//! - `db_type::*` — `DbType` 枚举 (11 种数据库)
//! - `dialect::*` — `Dialect`, `MySqlDialect`, `PostgreSqlDialect`, `SqliteDialect`, `OracleDialect`, `get_dialect()`
//! - `error::*` — `DbError`, `PoolError`, `CacheError`, `TxError`
//! - `migration::*` — `Migration`, `Migrator`, `SchemaBuilder`, `ColumnDef`, `IndexDef`, `ForeignKeyDef`
//! - `model::*` — `Model`, `ModelExt`, `Relation`, `BelongsTo`, `HasMany`, `HasOne`, `BelongsToMany`
//! - `pool::*` — `Pool`, `PoolConfig`, `PoolConfigBuilder`, `Connection`, `ConnectionFactory`, `PoolStatus`
//! - `query::*` — `QueryBuilder<M>` (链式 SQL 构造器)
//! - `transaction::*` — `Transaction`, `TransactionManager`, `TransactOptions`, `IsolationLevel`
//! - `value::*` — `Value` 枚举 (20 种变体)

// 文档完整性：全局启用 missing_docs lint（v3.6.0 已补齐全部 pub API 文档）
#![warn(missing_docs)]

// v3.9.0 M1-T3：derive(Validate) 宏生成 sz_orm_core 绝对路径，
// crate 内部测试需 self 别名使该路径解析到当前 crate
#[cfg(all(test, feature = "data-validation"))]
extern crate self as sz_orm_core;

use std::sync::Arc;

/// Re-export async traits
pub use async_trait::async_trait;

/// Re-export common types
pub use bytes::Bytes;
pub use chrono::{DateTime, Utc};
pub use serde::{Deserialize, Serialize};

pub mod access_control;
pub mod accessors;
pub mod active_model;
pub mod behaviors;
#[cfg(feature = "benchmark-suite")]
pub mod benchmark;
pub mod bloom;
mod cache;
pub mod circuit_breaker;
#[cfg(feature = "type-safe-columns")]
pub mod column;
#[cfg(feature = "zero-copy")]
pub mod columnar;
pub mod cursor_stream;
pub mod cycle_detection;
pub mod data_permission;
mod db_type;
pub mod dialect;
#[cfg(feature = "prod-dialect-security")]
pub mod dialect_security;
pub mod dirty_attributes;
#[cfg(feature = "dist-cache")]
pub mod dist_cache;
pub mod dynamic_filter;
pub mod dynamic_sql;
pub mod eager_loader;
pub mod entity_graph;
mod error;
pub mod find_with_related;
#[cfg(feature = "compile-governance")]
pub mod governance;
pub mod guard;
pub mod hooks;
pub mod hydration_plugin;
pub mod i18n;
pub mod join_dsl;
pub mod json_query;
#[cfg(feature = "l1-cache")]
pub mod l1_cache;
pub mod l2_cache;
pub mod lambda;
pub mod migration;
#[cfg(feature = "migration-dry-run")]
pub mod migration_dry_run;
pub mod mock;
mod model;
pub mod n1_eliminator;
pub mod nested_active_model;
pub mod observer;
pub mod optimistic_lock;
pub mod paginator;
pub mod partial_model;
pub mod phinx_migration;
#[cfg(feature = "plan-cache")]
pub mod plan_cache;
mod pool;
#[cfg(feature = "auto-prewarm")]
pub mod prewarm;
#[cfg(feature = "prod-ready")]
pub mod prod_ready_check;
mod query;
#[cfg(feature = "data-validation")]
pub mod validation;
/// 重导出 QueryBuilder 供外部使用
pub use query::QueryBuilder;
#[cfg(feature = "cache-coherence")]
pub mod cache_coherence;
#[cfg(feature = "cache-warmup-protection")]
#[allow(missing_docs)]
pub mod cache_warmup_protection;
#[cfg(feature = "connection-level-tenant")]
pub mod connection_tenant;
#[cfg(feature = "forward-compat-sandbox")]
#[allow(missing_docs)]
pub mod forward_compat_sandbox;
#[cfg(feature = "migration-branch")]
pub mod migration_branch;
#[cfg(feature = "process-l1-cache")]
pub mod process_l1_cache;
#[cfg(feature = "qb-migration-tool")]
pub mod qb_migration_fix;
#[cfg(feature = "qb-migration-tool")]
pub mod qb_migration_lint;
pub mod queryable;
pub mod quick_query;
pub mod rate_limiter;
pub mod relation_trait;
pub mod repository;
pub mod result_map;
pub mod retry;
#[cfg(feature = "zero-downtime-rollback")]
pub mod rollback_zero_downtime;
#[cfg(feature = "schema-diff-viz")]
pub mod schema_diff_viz;
pub mod schema_gen;
pub mod schema_sync;
#[cfg(feature = "data-seeding")]
pub mod seeding;
pub mod select_types;
pub mod shadow;
#[cfg(feature = "simd")]
pub mod simd;
pub mod smart_eager_loader;
pub mod sql_buffer;
pub mod sql_safety;
#[cfg(feature = "sql-verify-proc")]
pub mod sql_verify;
pub mod stream_api;
#[cfg(feature = "streaming-export")]
pub mod streaming_export;
pub mod telemetry;
#[cfg(feature = "multi-tenant-enhanced")]
pub mod tenant_context;
#[cfg(feature = "tenant-quota-rls-enhanced")]
#[allow(missing_docs)]
pub mod tenant_quota_rls;
#[cfg(feature = "multi-tenant-enhanced")]
pub mod tenant_security;
mod transaction;
pub mod type_handler;
pub mod typed;
pub mod typed_ast;
#[cfg(feature = "typed-relation")]
pub mod typed_relation;
mod value;
#[cfg(feature = "zero-copy")]
pub mod value_borrowed;

// Re-export proc macros
pub use queryable::Query;
pub use queryable::QueryAs;
pub use sz_orm_macros::query;
pub use sz_orm_macros::query_as;
pub use sz_orm_macros::schema;
pub use sz_orm_macros::sql_string;
pub use sz_orm_macros::typed_query;
// FromQueryResult derive 宏（与 value.rs 中同名 trait 通过显式 use 遮蔽 glob 导出）
#[cfg(feature = "n1-lint")]
pub use sz_orm_macros::detect_n_plus_one;
pub use sz_orm_macros::FromQueryResult;
pub use sz_orm_macros::RelationTrait;
#[cfg(feature = "data-validation")]
pub use sz_orm_macros::Validate;

pub use cache::*;
pub use cycle_detection::{CycleDetector, CyclePolicy};
pub use db_type::*;
#[allow(ambiguous_glob_reexports)]
pub use dialect::*;
pub use eager_loader::NestedEagerResult;
pub use error::*;
#[allow(ambiguous_glob_reexports)]
pub use migration::*;
pub use model::*;
pub use nested_active_model::CascadeStrategy;
pub use pool::*;
#[allow(unused_imports)]
pub use query::*;
pub use schema_sync::{Confirm, DataMigrationHook, DestructiveSyncResult};
pub use transaction::*;
pub use value::*;

/// Alias for `Arc<T>`
pub type Shared<T> = Arc<T>;

/// Alias for `Box<T>`
pub type Boxed<T> = Box<T>;

/// Alias for Result<T, DbError>
pub type DbResult<T> = Result<T, DbError>;

/// Result type for pool operations
pub type PoolResult<T> = Result<T, PoolError>;

/// Result type for cache operations
pub type CacheResult<T> = Result<T, CacheError>;

/// Result type for transaction operations
pub type TxResult<T> = Result<T, TxError>;

/// Default batch size for bulk operations
pub const DEFAULT_BATCH_SIZE: usize = 1000;

/// Default connection timeout in seconds
pub const DEFAULT_ACQUIRE_TIMEOUT: u64 = 30;

/// Default idle timeout in seconds
pub const DEFAULT_IDLE_TIMEOUT: u64 = 600;

/// Default max lifetime in seconds
pub const DEFAULT_MAX_LIFETIME: u64 = 1800;

/// Default minimum idle connections
pub const DEFAULT_MIN_IDLE: u32 = 5;

/// Default maximum pool size
pub const DEFAULT_MAX_SIZE: u32 = 100;

#[cfg(test)]
mod tests {
    use super::*;
    use std::error::Error;

    #[test]
    fn test_db_type() {
        assert_eq!(DbType::MySQL.as_str(), "mysql");
        assert_eq!(DbType::PostgreSQL.as_str(), "postgres");
        assert_eq!(DbType::Sqlite.as_str(), "sqlite");
    }

    #[test]
    fn test_value() {
        let v = Value::Null;
        assert!(v.is_null());

        let v = Value::I64(42);
        assert!(v.is_i64());

        let v = Value::String("hello".to_string());
        assert!(v.is_string());
    }

    #[test]
    fn test_db_error_display() {
        let err = DbError::QueryError("test query failed".to_string());
        assert_eq!(format!("{}", err), "Query error: test query failed");

        let err = DbError::ConnectionRefused("localhost".to_string());
        assert_eq!(format!("{}", err), "Connection refused: localhost");
    }

    #[test]
    fn test_db_error_source() {
        let err = DbError::PoolError(PoolError::Timeout);
        assert!(err.source().is_some());
    }

    #[tokio::test]
    async fn test_async_trait_export() {
        fn _check_send_sync<T: Send + Sync>() {}

        struct TestImpl;
        #[async_trait]
        trait AsyncFoo: Send + Sync {
            async fn foo(&self);
        }

        #[async_trait]
        impl AsyncFoo for TestImpl {
            async fn foo(&self) {}
        }

        let impl_ = TestImpl;
        impl_.foo().await;
        _check_send_sync::<TestImpl>();
    }

    // ---- compile-time SQL validation macro tests ----

    /// Valid SQL should compile and be usable as a string
    #[test]
    fn test_sql_string_valid_select() {
        let sql = sql_string!("SELECT * FROM users WHERE id = 1");
        assert!(sql.contains("SELECT"));
        assert!(sql.contains("FROM"));
    }

    #[test]
    fn test_sql_string_valid_insert() {
        let sql = sql_string!("INSERT INTO users (name) VALUES ('alice')");
        assert!(sql.contains("INSERT"));
    }

    #[test]
    fn test_sql_string_valid_update() {
        let sql = sql_string!("UPDATE users SET name = 'bob' WHERE id = 1");
        assert!(sql.contains("UPDATE"));
    }

    #[test]
    fn test_sql_string_valid_delete() {
        let sql = sql_string!("DELETE FROM users WHERE id = 1");
        assert!(sql.contains("DELETE"));
    }

    #[test]
    fn test_sql_string_valid_create() {
        let sql = sql_string!("CREATE TABLE test (id INT PRIMARY KEY)");
        assert!(sql.contains("CREATE"));
    }

    #[test]
    fn test_sql_string_with_params() {
        let sql = sql_string!("SELECT * FROM users WHERE id = ?"; params: 1);
        assert!(sql.contains("?"));
    }

    #[test]
    fn test_sql_string_complex_query() {
        let sql = sql_string!(
            "SELECT u.*, o.total FROM users u LEFT JOIN orders o ON u.id = o.user_id WHERE u.status = 'active'"
        );
        assert!(sql.contains("LEFT JOIN"));
    }

    #[test]
    fn test_sql_string_nested_parens() {
        let sql = sql_string!("SELECT * FROM (SELECT * FROM users) t");
        assert!(sql.contains("SELECT"));
    }
}