tdm_server_rust/web/

mod.rs

//! HTTP 路由与控制器层 (Web Layer)
//!
//! 定义所有 API 端点的路由注册和 Handler 函数。
//!
//! ## 路由表 (`create_router()`)
//!
//! | 路由前缀 | Controller | 端点数 | 说明 |
//! |---------|-----------|--------|------|
//! | `/api/login`, `/api/reg` | [`login_controller`] | 5 | 登录/注册/邀请码 |
//! | `/api/members` | [`member_controller`] | 12 | 组员 CRUD/岗位/常驻 |
//! | `/api/authors` | [`author_controller`] | 7 | 作者管理 |
//! | `/api/magazines` | [`magazine_controller`] | 7 | 杂志管理 |
//! | `/api/evaluations` | [`evaluation_controller`] | 5 | 评价管理 |
//! | `/api/gray` | [`gray_release_controller`] | 1 | 灰度命中 |
//! | `/api/questionnaires` | [`questionnaire_controller`] | 3 | 问卷提交查询 |
//! | `/api/mangas` | [`manga_controller`] | 27 | 漫画/收藏/术语表 |
//! | `/api/episodes` | [`episode_controller`] | 14 | 话数/发布/上传 |
//! | `/api/manga/benefits` | [`manga_benefit_controller`] | 4 | 特典管理 |
//! | `/api/reward` | [`reward_controller`] | 10 | 悬赏/兑换/抽奖 |
//! | `/api/oss` | [`oss_controller`] | 4 | 文件上传下载 |
//! | `/api/admin/taskTracking` | [`task_tracking_controller`] | 3 | 任务看板 |
//! | `/api/admin/gray` | [`gray_release_controller`] | 4 | 灰度管理 |
//!
//! ## 中间件栈
//!
//! 所有 `/api/*` 路由经过：`error_log → auth → handler`
//! dev 环境下额外添加：`debug_log` 中间件

/// 作者管理 API 路由
pub mod author_controller;
/// 在线翻译协作 Hub（WebSocket）路由
pub mod collaboration_hub_controller;
/// dev 环境 API（SkyWalking 302 + health + errors）
/// OpenAPI / Swagger UI 静态资源路由
pub mod doc_controller;
/// 在线翻译编辑器 API 路由
pub mod editor_controller;
/// 话数管理 API 路由
pub mod episode_controller;
/// 评价管理 API 路由
pub mod evaluation_controller;
/// 灰度发布 API 路由
pub mod gray_release_controller;
/// 登录/注册 API 路由
pub mod login_controller;
/// 杂志管理 API 路由
pub mod magazine_controller;
/// 漫画特典 API 路由
pub mod manga_benefit_controller;
/// 漫画管理 API 路由
pub mod manga_controller;
/// 组员管理 API 路由
pub mod member_controller;
/// OSS 文件上传/下载 API 路由
pub mod oss_controller;
/// 问卷管理 API 路由
pub mod questionnaire_controller;
/// 悬赏/兑换/抽奖 API 路由
pub mod reward_controller;
/// 全局搜索 API 路由
pub mod search_controller;
/// 任务看板 API 路由
pub mod task_tracking_controller;

use crate::{
    app::AppState,
    dev,
    middleware::{auth_middleware, debug_log_middleware, error_log_middleware},
    telemetry::telemetry_http_span_middleware,
};
use axum::extract::State;
use axum::http::header;
use axum::http::{HeaderName, StatusCode};
use axum::middleware;
use axum::response::IntoResponse;
use axum::{routing::get, Json, Router};
use serde::Serialize;
use tower_http::cors::CorsLayer;

/// 顶层健康检查响应
#[derive(Debug, Serialize)]
struct HealthzResponse {
    /// 服务是否已完成基础依赖探活
    ok: bool,
    /// 当前运行 profile
    profile: String,
    /// 数据库连接是否可用
    database: bool,
    /// 进程已运行秒数
    uptime_seconds: u64,
}

/// 创建带 `/api` 前缀的完整路由
pub fn create_router(state: AppState) -> Router {
    let api = Router::new()
        .merge(login_controller::routes())
        .nest("/members", member_controller::routes())
        .nest("/authors", author_controller::routes())
        .nest("/magazines", magazine_controller::routes())
        .nest("/evaluations", evaluation_controller::routes())
        .nest("/gray", gray_release_controller::routes())
        .nest("/questionnaires", questionnaire_controller::routes())
        .nest("/mangas", manga_controller::routes())
        .nest("/episodes", episode_controller::routes())
        .nest("/editor", editor_controller::routes())
        .nest("/manga/benefits", manga_benefit_controller::routes())
        .nest("/reward", reward_controller::routes())
        .nest("/oss", oss_controller::routes())
        .route("/search", get(search_controller::global_search))
        .route("/search/", get(search_controller::global_search))
        .nest("/admin/gray", gray_release_controller::admin_routes())
        .nest("/admin/taskTracking", task_tracking_controller::routes());

    let api = api
        .fallback(api_not_found)
        .layer(middleware::from_fn(error_log_middleware))
        .layer(middleware::from_fn_with_state(
            state.clone(),
            auth_middleware,
        ))
        .with_state(state.clone());

    let cors = CorsLayer::permissive().expose_headers([
        HeaderName::from_static("server-timing"),
        header::LOCATION,
        HeaderName::from_static("x-download-filename"),
        header::CONTENT_DISPOSITION,
    ]);

    let mut app = Router::new()
        .route("/healthz", get(healthz))
        .nest("/api", api)
        // 协作 Hub 挂载于顶层（/hubs/*），不经过 /api 的 auth 中间件，
        // WS 鉴权由控制器自身从查询参数 access_token 完成
        .merge(collaboration_hub_controller::routes())
        .layer(cors)
        .with_state(state.clone());

    if state.config.telemetry.enabled {
        app = app.layer(middleware::from_fn(telemetry_http_span_middleware));
    }

    if matches!(state.config.profile.as_str(), "dev" | "dev-h2") {
        let springdoc = state.config.springdoc.clone();
        app = app.merge(doc_controller::routes(springdoc));
        app = app.merge(dev::routes(state.clone()));
        app = app.layer(middleware::from_fn(debug_log_middleware));
    }

    app
}

/// 顶层健康检查，不经过 `/api` 鉴权，供部署脚本和负载均衡探活使用
#[tracing::instrument(skip_all, level = "info")]
async fn healthz(State(state): State<AppState>) -> impl IntoResponse {
    let database = sqlx::query_scalar::<_, i32>("SELECT 1")
        .fetch_one(&state.db)
        .await
        .is_ok();
    let response = HealthzResponse {
        ok: database,
        profile: state.config.profile.clone(),
        database,
        uptime_seconds: state.started_at.elapsed().as_secs(),
    };
    let status = if response.ok {
        StatusCode::OK
    } else {
        StatusCode::SERVICE_UNAVAILABLE
    };

    (status, Json(response))
}

/// 未匹配的 `/api/*` 路由
#[tracing::instrument(skip_all, level = "info")]
async fn api_not_found() -> impl IntoResponse {
    (
        StatusCode::NOT_FOUND,
        r#"{"code":404,"msg":"接口不存在","data":null}"#,
    )
}