认证、RBAC 权限与安全完全指南

flowchart TD
    subgraph Roles["管理员角色等级"]
        SuperAdmin["超级管理员 (super_admin)\n拥有平台全局最高权限\n可创建系统、分配管理员、查看所有业务数据"]
        Admin["普通管理员 (admin)\n拥有特定业务子系统的完全读写权限"]
        TopicAdmin["专题受限管理员 (topic_admin)\n仅能访问被显式授权的单个或多个子系统"]
    end

    subgraph AuthMethods["认证认证方式"]
        PasswordLogin["账号 + 密码登录 (Argon2id 校验)"]
        EmailLogin["邮箱 + 6位动态验证码登录 (SMTP 驱动)"]
    end

    subgraph Token["无状态令牌"]
        JWT["JWT 令牌 (Bearer Token)\n携带: id, username, role, allowed_systems"]
    end

    subgraph Middlewares["安全拦截中间件"]
        M1["require_admin_auth\n校验 JWT 签名有效性与是否过期"]
        M2["require_topic_access\n核验 claims.allowed_systems 是否包含目标 system_slug"]
    end

    subgraph Resources["受保护资源与业务 API"]
        AdminAPI["平台管理 API (/api/v1/admin/*)"]
        TopicAdminAPI["专题管理 API (/api/v1/admin/s/{slug}/*)"]
        CustomExtAPI["自定义业务扩展 API (/api/v1/s/{slug}/ext/*)"]
    end

    AuthMethods --> JWT
    JWT --> M1
    M1 --> AdminAPI
    M1 --> M2
    M2 --> TopicAdminAPI
    M2 --> CustomExtAPI

use foundry::prelude::*;

// 1. 生成安全密码哈希（存储到数据库）
let raw_password = "MySecurePassword2026!";
let password_hash = hash_password(raw_password)?;
// 输出形如: $argon2id$v=19$m=19456,t=2,p=1$vB8...$4Q8...

// 2. 校验明文密码是否匹配
let is_valid = verify_password(raw_password, &password_hash)?;
assert!(is_valid);

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AdminClaims {
    /// 管理员在数据库中的唯一主键 ID
    pub sub: i64,
    /// 管理员用户名
    pub username: String,
    /// 角色标识: "super_admin" | "admin" | "topic_admin"
    pub role: String,
    /// 被允许访问的业务子系统 slug 列表（如 ["shop", "blog"]）
    /// 若 role == "super_admin"，此列表可为空，默认通配全部子系统
    pub allowed_systems: Vec<String>,
    /// 令牌过期时间戳 (UTC 秒)
    pub exp: usize,
}

sequenceDiagram
    autonumber
    actor Admin as 管理员浏览器
    participant API as Foundry Auth API
    participant SMTP as SMTP 邮件中继 (lettre)
    participant Store as 数据库 / 缓存

    Admin->>API: POST /api/v1/admin/auth/email/send-code\n{ "email": "admin@company.com" }
    Note over API: 1. 检索绑定该邮箱的管理员账号<br/>2. 校验 60s 发送冷却频率<br/>3. 生成 6 位高强度数字验证码
    API->>Store: 存储验证码 (有效期 5 分钟)
    API->>SMTP: 发送包含验证码的安全通知邮件
    SMTP-->>Admin: 收到邮件: "【Foundry】您的登录验证码为: 839201"

    Admin->>API: POST /api/v1/admin/auth/email/login\n{ "email": "admin@company.com", "code": "839201" }
    Note over API: 核对验证码一致性与时效性
    API->>Store: 作废已使用的验证码 (防重放)
    API-->>Admin: 返回 JWT Token 与管理员信息

use axum::{Router, routing::get, middleware::from_fn_with_state};
use foundry::prelude::*;
use foundry_engine::middleware::require_admin_auth;

pub fn protected_routes(state: AppState) -> Router {
    Router::new()
        .route("/export-report", get(export_report_handler))
        .route_layer(from_fn_with_state(state.clone(), require_admin_auth))
}

// 在 Handler 中直接提取当前登录管理员身份
async fn export_report_handler(
    Extension(claims): Extension<AdminClaims>,
) -> ApiResponse<String> {
    ApiResponse::ok(format!("欢迎管理员: {}, ID: {}", claims.username, claims.sub))
}

use axum::{Router, routing::{get, post}, middleware::from_fn_with_state};
use foundry::prelude::*;
use foundry_engine::middleware::{require_admin_auth, require_topic_access};

pub struct ShopSubsystem;

impl SubsystemModule for ShopSubsystem {
    fn slug(&self) -> &'static str { "shop" }
    fn display_name(&self) -> &'static str { "商城子系统" }

    fn register_routes(&self, router: Router) -> Router {
        // 1. 公开对外接口（顾客浏览商品、获取配置等）
        let public_routes = Router::new()
            .route("/goods", get(list_public_goods));

        // 2. 商家管理接口（必须具备管理员凭证且拥有本子系统权限）
        // 该路由被挂载到: /api/v1/s/shop/ext/manage/*
        let protected_manage_routes = Router::new()
            .route("/manage/orders/ship", post(ship_order_handler))
            .route("/manage/stats", get(get_sales_stats_handler));

        router
            .merge(public_routes)
            .merge(protected_manage_routes)
    }
}