feat(saas): Phase 1 — 基础框架与账号管理模块

- 新增 zclaw-saas crate 作为 workspace 成员
- 配置系统 (TOML + 环境变量覆盖)
- 错误类型体系 (SaasError 16 变体, IntoResponse)
- SQLite 数据库 (12 表 schema, 内存/文件双模式, 3 系统角色种子数据)
- JWT 认证 (签发/验证/刷新)
- Argon2id 密码哈希
- 认证中间件 (公开/受保护路由分层)
- 账号管理 CRUD + API Token 管理 + 操作日志
- 7 单元测试 + 5 集成测试全部通过

crates/zclaw-saas/src/auth/handlers.rs

@@ -0,0 +1,180 @@
+//! 认证 HTTP 处理器
+
+use axum::{extract::State, http::StatusCode, Json};
+use secrecy::ExposeSecret;
+use crate::state::AppState;
+use crate::error::{SaasError, SaasResult};
+use super::{
+    jwt::create_token,
+    password::{hash_password, verify_password},
+    types::{AuthContext, LoginRequest, LoginResponse, RegisterRequest, AccountPublic},
+};
+
+/// POST /api/v1/auth/register
+pub async fn register(
+    State(state): State<AppState>,
+    Json(req): Json<RegisterRequest>,
+) -> SaasResult<(StatusCode, Json<AccountPublic>)> {
+    if req.username.len() < 3 {
+        return Err(SaasError::InvalidInput("用户名至少 3 个字符".into()));
+    }
+    if req.password.len() < 8 {
+        return Err(SaasError::InvalidInput("密码至少 8 个字符".into()));
+    }
+
+    let existing: Vec<(String,)> = sqlx::query_as(
+        "SELECT id FROM accounts WHERE username = ?1 OR email = ?2"
+    )
+    .bind(&req.username)
+    .bind(&req.email)
+    .fetch_all(&state.db)
+    .await?;
+
+    if !existing.is_empty() {
+        return Err(SaasError::AlreadyExists("用户名或邮箱已存在".into()));
+    }
+
+    let password_hash = hash_password(&req.password)?;
+    let account_id = uuid::Uuid::new_v4().to_string();
+    let role = req.role.unwrap_or_else(|| "user".into());
+    let display_name = req.display_name.unwrap_or_default();
+    let now = chrono::Utc::now().to_rfc3339();
+
+    sqlx::query(
+        "INSERT INTO accounts (id, username, email, password_hash, display_name, role, status, created_at, updated_at)
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6, 'active', ?7, ?7)"
+    )
+    .bind(&account_id)
+    .bind(&req.username)
+    .bind(&req.email)
+    .bind(&password_hash)
+    .bind(&display_name)
+    .bind(&role)
+    .bind(&now)
+    .execute(&state.db)
+    .await?;
+
+    log_operation(&state.db, &account_id, "account.create", "account", &account_id, None, None).await?;
+
+    Ok((StatusCode::CREATED, Json(AccountPublic {
+        id: account_id,
+        username: req.username,
+        email: req.email,
+        display_name,
+        role,
+        status: "active".into(),
+        totp_enabled: false,
+        created_at: now,
+    })))
+}
+
+/// POST /api/v1/auth/login
+pub async fn login(
+    State(state): State<AppState>,
+    Json(req): Json<LoginRequest>,
+) -> SaasResult<Json<LoginResponse>> {
+    let row: Option<(String, String, String, String, String, String, bool, String)> =
+        sqlx::query_as(
+            "SELECT id, username, email, display_name, role, status, totp_enabled, created_at
+             FROM accounts WHERE username = ?1 OR email = ?1"
+        )
+        .bind(&req.username)
+        .fetch_optional(&state.db)
+        .await?;
+
+    let (id, username, email, display_name, role, status, totp_enabled, created_at) =
+        row.ok_or_else(|| SaasError::AuthError("用户名或密码错误".into()))?;
+
+    if status != "active" {
+        return Err(SaasError::Forbidden(format!("账号已{}，请联系管理员", status)));
+    }
+
+    let (password_hash,): (String,) = sqlx::query_as(
+        "SELECT password_hash FROM accounts WHERE id = ?1"
+    )
+    .bind(&id)
+    .fetch_one(&state.db)
+    .await?;
+
+    if !verify_password(&req.password, &password_hash)? {
+        return Err(SaasError::AuthError("用户名或密码错误".into()));
+    }
+
+    let permissions = get_role_permissions(&state.db, &role).await?;
+    let config = state.config.read().await;
+    let token = create_token(
+        &id, &role, permissions.clone(),
+        state.jwt_secret.expose_secret(),
+        config.auth.jwt_expiration_hours,
+    )?;
+
+    let now = chrono::Utc::now().to_rfc3339();
+    sqlx::query("UPDATE accounts SET last_login_at = ?1 WHERE id = ?2")
+        .bind(&now).bind(&id)
+        .execute(&state.db).await?;
+    log_operation(&state.db, &id, "account.login", "account", &id, None, None).await?;
+
+    Ok(Json(LoginResponse {
+        token,
+        account: AccountPublic {
+            id, username, email, display_name, role, status, totp_enabled, created_at,
+        },
+    }))
+}
+
+/// POST /api/v1/auth/refresh
+pub async fn refresh(
+    State(state): State<AppState>,
+    axum::extract::Extension(ctx): axum::extract::Extension<AuthContext>,
+) -> SaasResult<Json<serde_json::Value>> {
+    let config = state.config.read().await;
+    let token = create_token(
+        &ctx.account_id, &ctx.role, ctx.permissions.clone(),
+        state.jwt_secret.expose_secret(),
+        config.auth.jwt_expiration_hours,
+    )?;
+    Ok(Json(serde_json::json!({ "token": token })))
+}
+
+async fn get_role_permissions(db: &sqlx::SqlitePool, role: &str) -> SaasResult<Vec<String>> {
+    let row: Option<(String,)> = sqlx::query_as(
+        "SELECT permissions FROM roles WHERE id = ?1"
+    )
+    .bind(role)
+    .fetch_optional(db)
+    .await?;
+
+    let permissions_str = row
+        .ok_or_else(|| SaasError::Internal(format!("角色 {} 不存在", role)))?
+        .0;
+
+    let permissions: Vec<String> = serde_json::from_str(&permissions_str)?;
+    Ok(permissions)
+}
+
+/// 记录操作日志
+pub async fn log_operation(
+    db: &sqlx::SqlitePool,
+    account_id: &str,
+    action: &str,
+    target_type: &str,
+    target_id: &str,
+    details: Option<serde_json::Value>,
+    ip_address: Option<&str>,
+) -> SaasResult<()> {
+    let now = chrono::Utc::now().to_rfc3339();
+    sqlx::query(
+        "INSERT INTO operation_logs (account_id, action, target_type, target_id, details, ip_address, created_at)
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)"
+    )
+    .bind(account_id)
+    .bind(action)
+    .bind(target_type)
+    .bind(target_id)
+    .bind(details.map(|d| d.to_string()))
+    .bind(ip_address)
+    .bind(&now)
+    .execute(db)
+    .await?;
+    Ok(())
+}

crates/zclaw-saas/src/auth/jwt.rs

@@ -0,0 +1,91 @@
+//! JWT Token 创建与验证
+
+use chrono::{Duration, Utc};
+use jsonwebtoken::{decode, encode, DecodingKey, EncodingKey, Header, Validation};
+use serde::{Deserialize, Serialize};
+
+use crate::error::SaasResult;
+
+/// JWT Claims
+#[derive(Debug, Serialize, Deserialize)]
+pub struct Claims {
+    pub sub: String,
+    pub role: String,
+    pub permissions: Vec<String>,
+    pub iat: i64,
+    pub exp: i64,
+}
+
+impl Claims {
+    pub fn new(account_id: &str, role: &str, permissions: Vec<String>, expiration_hours: i64) -> Self {
+        let now = Utc::now();
+        Self {
+            sub: account_id.to_string(),
+            role: role.to_string(),
+            permissions,
+            iat: now.timestamp(),
+            exp: (now + Duration::hours(expiration_hours)).timestamp(),
+        }
+    }
+}
+
+/// 创建 JWT Token
+pub fn create_token(
+    account_id: &str,
+    role: &str,
+    permissions: Vec<String>,
+    secret: &str,
+    expiration_hours: i64,
+) -> SaasResult<String> {
+    let claims = Claims::new(account_id, role, permissions, expiration_hours);
+    let token = encode(
+        &Header::default(),
+        &claims,
+        &EncodingKey::from_secret(secret.as_bytes()),
+    )?;
+    Ok(token)
+}
+
+/// 验证 JWT Token
+pub fn verify_token(token: &str, secret: &str) -> SaasResult<Claims> {
+    let token_data = decode::<Claims>(
+        token,
+        &DecodingKey::from_secret(secret.as_bytes()),
+        &Validation::default(),
+    )?;
+    Ok(token_data.claims)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const TEST_SECRET: &str = "test-secret-key";
+
+    #[test]
+    fn test_create_and_verify_token() {
+        let token = create_token(
+            "account-123", "admin",
+            vec!["model:read".to_string()],
+            TEST_SECRET, 24,
+        ).unwrap();
+
+        let claims = verify_token(&token, TEST_SECRET).unwrap();
+        assert_eq!(claims.sub, "account-123");
+        assert_eq!(claims.role, "admin");
+        assert_eq!(claims.permissions, vec!["model:read"]);
+    }
+
+    #[test]
+    fn test_invalid_token() {
+        let result = verify_token("invalid.token.here", TEST_SECRET);
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn test_wrong_secret() {
+        let token = create_token("account-123", "admin", vec![], TEST_SECRET, 24).unwrap();
+        let result = verify_token(&token, "wrong-secret");
+        assert!(result.is_err());
+    }
+}

crates/zclaw-saas/src/auth/mod.rs

@@ -0,0 +1,69 @@
+//! 认证模块
+
+pub mod jwt;
+pub mod password;
+pub mod types;
+pub mod handlers;
+
+use axum::{
+    extract::{Request, State},
+    http::header,
+    middleware::Next,
+    response::{IntoResponse, Response},
+};
+use secrecy::ExposeSecret;
+use crate::error::SaasError;
+use crate::state::AppState;
+use types::AuthContext;
+
+/// 认证中间件: 从 JWT 或 API Token 提取身份
+pub async fn auth_middleware(
+    State(state): State<AppState>,
+    mut req: Request,
+    next: Next,
+) -> Response {
+    let auth_header = req.headers()
+        .get(header::AUTHORIZATION)
+        .and_then(|v| v.to_str().ok());
+
+    let result = if let Some(auth) = auth_header {
+        if let Some(token) = auth.strip_prefix("Bearer ") {
+            jwt::verify_token(token, state.jwt_secret.expose_secret())
+                .map(|claims| AuthContext {
+                    account_id: claims.sub,
+                    role: claims.role,
+                    permissions: claims.permissions,
+                })
+                .map_err(|_| SaasError::Unauthorized)
+        } else {
+            Err(SaasError::Unauthorized)
+        }
+    } else {
+        Err(SaasError::Unauthorized)
+    };
+
+    match result {
+        Ok(ctx) => {
+            req.extensions_mut().insert(ctx);
+            next.run(req).await
+        }
+        Err(e) => e.into_response(),
+    }
+}
+
+/// 路由 (无需认证的端点)
+pub fn routes() -> axum::Router<AppState> {
+    use axum::routing::post;
+
+    axum::Router::new()
+        .route("/api/v1/auth/register", post(handlers::register))
+        .route("/api/v1/auth/login", post(handlers::login))
+}
+
+/// 需要认证的路由
+pub fn protected_routes() -> axum::Router<AppState> {
+    use axum::routing::post;
+
+    axum::Router::new()
+        .route("/api/v1/auth/refresh", post(handlers::refresh))
+}

crates/zclaw-saas/src/auth/password.rs

@@ -0,0 +1,48 @@
+//! 密码哈希 (Argon2id)
+
+use argon2::{
+    password_hash::{rand_core::OsRng, PasswordHash, PasswordHasher, PasswordVerifier, SaltString},
+    Argon2,
+};
+
+use crate::error::{SaasError, SaasResult};
+
+/// 哈希密码
+pub fn hash_password(password: &str) -> SaasResult<String> {
+    let salt = SaltString::generate(&mut OsRng);
+    let argon2 = Argon2::default();
+    let hash = argon2
+        .hash_password(password.as_bytes(), &salt)
+        .map_err(|e| SaasError::PasswordHash(e.to_string()))?;
+    Ok(hash.to_string())
+}
+
+/// 验证密码
+pub fn verify_password(password: &str, hash: &str) -> SaasResult<bool> {
+    let parsed_hash = PasswordHash::new(hash)
+        .map_err(|e| SaasError::PasswordHash(e.to_string()))?;
+    Ok(Argon2::default()
+        .verify_password(password.as_bytes(), &parsed_hash)
+        .is_ok())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_hash_and_verify() {
+        let hash = hash_password("correct_password").unwrap();
+        assert!(verify_password("correct_password", &hash).unwrap());
+        assert!(!verify_password("wrong_password", &hash).unwrap());
+    }
+
+    #[test]
+    fn test_different_hashes_for_same_password() {
+        let hash1 = hash_password("same_password").unwrap();
+        let hash2 = hash_password("same_password").unwrap();
+        assert_ne!(hash1, hash2);
+        assert!(verify_password("same_password", &hash1).unwrap());
+        assert!(verify_password("same_password", &hash2).unwrap());
+    }
+}

crates/zclaw-saas/src/auth/types.rs

@@ -0,0 +1,49 @@
+//! 认证相关类型
+
+use serde::{Deserialize, Serialize};
+
+/// 登录请求
+#[derive(Debug, Deserialize)]
+pub struct LoginRequest {
+    pub username: String,
+    pub password: String,
+    pub totp_code: Option<String>,
+}
+
+/// 登录响应
+#[derive(Debug, Serialize)]
+pub struct LoginResponse {
+    pub token: String,
+    pub account: AccountPublic,
+}
+
+/// 注册请求
+#[derive(Debug, Deserialize)]
+pub struct RegisterRequest {
+    pub username: String,
+    pub email: String,
+    pub password: String,
+    pub display_name: Option<String>,
+    pub role: Option<String>,
+}
+
+/// 公开账号信息 (无敏感数据)
+#[derive(Debug, Clone, Serialize)]
+pub struct AccountPublic {
+    pub id: String,
+    pub username: String,
+    pub email: String,
+    pub display_name: String,
+    pub role: String,
+    pub status: String,
+    pub totp_enabled: bool,
+    pub created_at: String,
+}
+
+/// 认证上下文 (注入到 request extensions)
+#[derive(Debug, Clone)]
+pub struct AuthContext {
+    pub account_id: String,
+    pub role: String,
+    pub permissions: Vec<String>,
+}