源码学习指南与全景导读

传统框架模式：框架 = 模板（Fork 后修改）
Foundry 模式：框架 = 独立 Crate 依赖（用户项目完全独立）

foundry/
├── crates/                    # 核心框架 Crates（7 个模块）
│   ├── foundry               # [门面] 统一入口与 Prelude
│   ├── foundry_core          # [核心] 上下文、错误、响应、Subsystem trait
│   ├── foundry_storage       # [存储] 数据库、Redis、动态模型
│   ├── foundry_auth          # [认证] 管理员、JWT、RBAC
│   ├── foundry_engine        # [引擎] 路由、Auto-CRUD、审计
│   ├── foundry_extension     # [扩展] 生命周期钩子
│   └── foundry_cli           # [CLI] 项目脚手架工具
├── apps/
│   ├── admin/                # [前端] React 管理后台（独立 SPA）
│   └── server/               # [示例] 参考服务器实现
└── examples/
    └── blog_platform/        # [实战] 博客系统完整示例

┌─────────────────────────────────────────────────────────────┐
│                    用户应用层 (User App)                      │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  main.rs: FoundryApp::builder()                        │ │
│  │    ↓                                                    │ │
│  │  systems/blog/      (BlogSubsystem)                    │ │
│  │  systems/newsletter/(NewsletterSubsystem)              │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                           ↓ 依赖
┌─────────────────────────────────────────────────────────────┐
│               Foundry 框架层 (Framework Crates)              │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  foundry (Facade)                                      │ │
│  │    ├── FoundryApp                                      │ │
│  │    ├── FoundryBuilder                                  │ │
│  │    └── prelude (统一导出)                              │ │
│  └────────────────────────────────────────────────────────┘ │
│  ┌──────────────┬──────────────┬──────────────┬──────────┐ │
│  │ foundry_core │ foundry_     │ foundry_     │ foundry_ │ │
│  │              │ storage      │ auth         │ engine   │ │
│  │ - Context    │ - DB Pool    │ - JWT        │ - Router │ │
│  │ - Error      │ - Redis      │ - Argon2id   │ - CRUD   │ │
│  │ - Subsystem  │ - Models     │ - RBAC       │ - Audit  │ │
│  └──────────────┴──────────────┴──────────────┴──────────┘ │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ foundry_extension (Hooks)                              │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                           ↓ 数据访问
┌─────────────────────────────────────────────────────────────┐
│              基础设施层 (Infrastructure)                      │
│  ┌──────────────────────┬──────────────────────────────────┐│
│  │  多数据库 SPI 驱动     │  Redis 7-8                       ││
│  │  (PostgreSQL/MySQL等) │  (会话 + 缓存)                    ││
│  └──────────────────────┴──────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

pub trait SubsystemModule: Send + Sync {
    fn slug(&self) -> &str;           // 唯一标识（如 "blog"）
    fn name(&self) -> &str;           // 显示名称
    fn description(&self) -> &str;    // 描述

    // 可选：自定义路由
    fn register_routes(&self, router: Router<AppState>) -> Router<AppState> {
        router
    }

    // 可选：自定义管理后台页面
    fn custom_admin_pages(&self) -> Vec<CustomAdminPageSpec> {
        vec![]
    }
}

// 创建动态记录（自动生成 CRUD API）
let record = RecordStore::create(
    &db,
    "blog",          // system_slug
    "articles",      // model_slug
    json!({
        "title": "Hello World",
        "content": "...",
        "views": 0
    })
).await?;

// 自动获得 RESTful 端点：
// POST   /api/v1/s/blog/articles
// GET    /api/v1/s/blog/articles
// GET    /api/v1/s/blog/articles/:id
// PUT    /api/v1/s/blog/articles/:id
// DELETE /api/v1/s/blog/articles/:id

#[async_trait]
impl MutationHook for BlogMutationHook {
    async fn after_create(&self, ctx: &HookContext) -> Result<(), HookError> {
        // 文章创建后发送通知
        if ctx.system_slug == "blog" && ctx.model_slug == "articles" {
            send_notification(&ctx.record).await?;
        }
        Ok(())
    }
}

pub use app::{FoundryApp, FoundryBuilder, FoundryConfig};
pub mod prelude;  // 包含所有常用类型

// 统一错误类型
pub enum AppError {
    NotFound(String),
    Unauthorized,
    ValidationError(String),
    StorageError(String),
    // ...
}

// 统一结果类型
pub type AppResult<T> = Result<T, AppError>;

// 系统上下文
pub struct SystemContext {
    pub system_slug: String,
    pub admin_id: Option<Uuid>,
    pub request_id: String,
}

// 动态模型 CRUD
RecordStore::create(db, system_slug, model_slug, data) -> Record
RecordStore::get_by_id(db, system_slug, model_slug, id) -> Record
RecordStore::list(db, system_slug, model_slug, page, size) -> Vec<Record>
RecordStore::update(db, system_slug, model_slug, id, data) -> Record
RecordStore::delete(db, system_slug, model_slug, id) -> ()

// 配置 KV
ConfigStore::set(db, system_slug, key, value) -> ()
ConfigStore::get(db, system_slug, key) -> Option<String>

pub enum AdminRole {
    SuperAdmin,      // 超级管理员（全局权限）
    Admin,           // 平台管理员
    TopicAdmin,      // 主题管理员（限定子系统）
}

// 密码哈希
PasswordService::hash(password) -> String
PasswordService::verify(password, hash) -> bool

// JWT
JwtService::create_token(admin_id, role) -> String
JwtService::verify_token(token) -> Claims

// RBAC 中间件
require_auth(ExtractAdminClaims)
require_super_admin()

/api/v1
  ├── /auth                   # 认证端点
  ├── /systems                # 子系统管理
  ├── /admins                 # 管理员管理
  ├── /configs                # 配置管理
  ├── /audit-logs             # 审计日志
  └── /s/:system_slug         # Subsystem 动态路由
      ├── /:model_slug        # Auto-CRUD 端点
      └── /custom/*           # 自定义子系统路由

/admin                        # React 前端
/__health                     # 健康检查

#[async_trait]
pub trait MutationHook: Send + Sync {
    async fn before_create(&self, ctx: &HookContext) -> Result<(), HookError> {
        Ok(())
    }
    async fn after_create(&self, ctx: &HookContext) -> Result<(), HookError> {
        Ok(())
    }
    async fn before_update(&self, ctx: &HookContext) -> Result<(), HookError> {
        Ok(())
    }
    async fn after_update(&self, ctx: &HookContext) -> Result<(), HookError> {
        Ok(())
    }
    async fn before_delete(&self, ctx: &HookContext) -> Result<(), HookError> {
        Ok(())
    }
    async fn after_delete(&self, ctx: &HookContext) -> Result<(), HookError> {
        Ok(())
    }
}

// 1. 加载配置
let config = FoundryConfig::from_env();

// 2. 构建应用
let app = FoundryApp::builder()
    .config(config)
    .register_subsystem(BlogSubsystem)     // 注册子系统
    .register_hook(BlogMutationHook)       // 注册钩子
    .build()                                // 初始化（连接数据库、Redis）
    .await?;

// 3. 启动服务器
app.run().await?;  // 绑定端口，开始监听

┌───────────────────────────────────────────────────────────────┐
│ 1. HTTP 请求到达                                               │
│    POST /api/v1/s/blog/articles                               │
│    Authorization: Bearer <JWT>                                 │
│    Body: {"title": "Hello", "content": "..."}                 │
└───────────────────────────────────────────────────────────────┘
                          ↓
┌───────────────────────────────────────────────────────────────┐
│ 2. Axum 路由匹配                                               │
│    foundry_engine::router::subsystem_dynamic_routes()         │
│    → handlers::models::create_record()                        │
└───────────────────────────────────────────────────────────────┘
                          ↓
┌───────────────────────────────────────────────────────────────┐
│ 3. 认证中间件                                                  │
│    foundry_auth::jwt::verify_token()                          │
│    → 解析 JWT，提取 admin_id 和 role                           │
└───────────────────────────────────────────────────────────────┘
                          ↓
┌───────────────────────────────────────────────────────────────┐
│ 4. RBAC 权限检查                                               │
│    foundry_auth::rbac::check_permission()                     │
│    → 验证是否有操作权限                                         │
└───────────────────────────────────────────────────────────────┘
                          ↓
┌───────────────────────────────────────────────────────────────┐
│ 5. before_create 钩子                                          │
│    foundry_extension::hooks::trigger_before_create()          │
│    → BlogMutationHook::before_create()                        │
└───────────────────────────────────────────────────────────────┘
                          ↓
┌───────────────────────────────────────────────────────────────┐
│ 6. 数据库写入                                                  │
│    foundry_storage::models::RecordStore::create()             │
│    → INSERT INTO records (system_slug, model_slug, data, ...) │
└───────────────────────────────────────────────────────────────┘
                          ↓
┌───────────────────────────────────────────────────────────────┐
│ 7. after_create 钩子                                           │
│    foundry_extension::hooks::trigger_after_create()           │
│    → BlogMutationHook::after_create() (发送通知)              │
└───────────────────────────────────────────────────────────────┘
                          ↓
┌───────────────────────────────────────────────────────────────┐
│ 8. 审计日志记录                                                │
│    foundry_engine::middleware::audit::log_action()            │
│    → INSERT INTO audit_logs (...)                             │
└───────────────────────────────────────────────────────────────┘
                          ↓
┌───────────────────────────────────────────────────────────────┐
│ 9. 返回响应                                                    │
│    ApiResponse::success(record)                               │
│    → {"success": true, "data": {...}}                         │
└───────────────────────────────────────────────────────────────┘

// BlogSubsystem 实现
impl SubsystemModule for BlogSubsystem {
    fn register_routes(&self, router: Router<AppState>) -> Router<AppState> {
        router.route("/stats", get(handlers::get_blog_stats))
    }
}

// 请求流程：
// 1. 匹配路由 /api/v1/s/blog/custom/stats
// 2. 执行 handlers::get_blog_stats (自定义逻辑)
// 3. 返回自定义响应

// ❌ 错误：定义了 BlogSubsystem 但忘记注册
let app = FoundryApp::builder()
    .config(config)
    // .register_subsystem(BlogSubsystem) // 缺失！
    .build()
    .await?;

// ✅ 正确：必须显式注册
let app = FoundryApp::builder()
    .config(config)
    .register_subsystem(BlogSubsystem)
    .build()
    .await?;

// ❌ 错误：system_slug 和 model_slug 不一致
RecordStore::create(&db, "blogs", "article", data).await?;
// API 端点：/api/v1/s/blogs/article

// ✅ 正确：确保一致性
RecordStore::create(&db, "blog", "articles", data).await?;
// API 端点：/api/v1/s/blog/articles

// ❌ 不好：循环查询
for article in articles {
    let author = AdminStore::get_by_id(&db, article.author_id).await?;
    // ...
}

// ✅ 更好：批量查询或 JOIN
let authors = AdminStore::get_by_ids(&db, author_ids).await?;

// ❌ 不好：每次都查数据库
let config = ConfigStore::get(&db, "blog", "site_name").await?;

// ✅ 更好：先查缓存
let cache_key = format!("config:blog:site_name");
if let Some(cached) = redis.get(&cache_key).await? {
    return Ok(cached);
}
let config = ConfigStore::get(&db, "blog", "site_name").await?;
redis.set(&cache_key, &config, 3600).await?;