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(())
+}