shadowzzh

thirdparty.rs

thirdparty.rs
//! 第三方 API 代理(github / wakatime / steam / books search)。
//! 共同原則(照抄 Express):**不看上游狀態碼**(https.get 直接 parse body 回 200),
//! JSON parse 失敗與網路錯誤各有固定錯誤訊息;wakatime(axios)例外——非 2xx 會轉拋。

use axum::{
    Json,
    extract::{Path, Query, State},
    http::StatusCode,
    response::{IntoResponse, Response},
};
use serde::{Deserialize, Serialize};
use serde_json::{Value, json};

use crate::state::AppState;
use crate::util::{encode_uri_component, js_truthy, ser_js_number};

// ── 命名原則 ──────────────────────────────────────────────────────────────
// 這批端點把上游回應重新塑形成前端真正用得到的欄位(同 spotify 的做法)。
// 沿用上游欄位名(`playtime_forever`、`avatarfull`、`grand_total`…)——它們是
// Steam / WakaTime 的識別字,改名只會讓人對不上文件;我們自己發明的欄位
// (`gameCount`、`actualCodingTime`)用 camelCase,同站上其他端點。
//
// error 欄位是回應的一部分而非另一個型別:這批端點刻意**不看上游狀態碼**
// (照抄 Express),錯誤是放進同一個 JSON 讓前端讀 `.error` 的。

// ── 小工具 ────────────────────────────────────────────────────────────────

/// https.get 式代理:抓 URL、parse JSON、原樣回 200;parse 失敗/網路錯誤回指定訊息。
async fn passthrough_json(
    http: &reqwest::Client,
    url: &str,
    ua: Option<&str>,
    parse_err: &str,
    fetch_err: &str,
) -> Response {
    match fetch_json_lenient(http, url, ua, parse_err, fetch_err).await {
        Ok(v) => Json(v).into_response(),
        Err(e) => (StatusCode::INTERNAL_SERVER_ERROR, Json(json!({ "error": e }))).into_response(),
    }
}

/// 抓 URL、parse JSON,**不看上游狀態碼**(照抄 Express)。網路錯誤/parse 失敗
/// 回固定訊息字串,讓呼叫端塞進自己回應的 `error` 欄位。
async fn fetch_json_lenient(
    http: &reqwest::Client,
    url: &str,
    ua: Option<&str>,
    parse_err: &str,
    fetch_err: &str,
) -> Result<Value, String> {
    let mut req = http.get(url);
    if let Some(u) = ua {
        req = req.header("User-Agent", u);
    }
    let resp = req.send().await.map_err(|_| fetch_err.to_string())?;
    let body = resp.text().await.map_err(|_| fetch_err.to_string())?;
    let mut v: Value = serde_json::from_str(&body).map_err(|_| parse_err.to_string())?;
    crate::util::js_normalize_numbers(&mut v);
    Ok(v)
}

use crate::util::{iso_from_millis, now_ms};

/// 今日 UTC 日期字串(`new Date().toISOString().split('T')[0]`)。
fn today_utc() -> String {
    chrono::Utc::now().format("%Y-%m-%d").to_string()
}

// ── GitHub ────────────────────────────────────────────────────────────────

const GH_UA: &str = "Personal-Website-Backend";

/// ghFetch 等價:失敗回 None(Express resolve(null))。
///
/// `base` 是 GitHub API 的 base URL(`state.external.github_api`)。傳進來而不是寫死,
/// 測試才攔得到——理由見 `state::ExternalUrls`。
async fn gh_fetch(http: &reqwest::Client, base: &str, path: &str, token: Option<&str>) -> Option<Value> {
    let mut req = http.get(format!("{base}{path}")).header("User-Agent", GH_UA);
    if let Some(t) = token {
        req = req.header("Authorization", format!("Bearer {t}"));
    }
    let mut v: Value = req.send().await.ok()?.json().await.ok()?;
    crate::util::js_normalize_numbers(&mut v);
    Some(v)
}

const GH_PARSE_ERR: &str = "Failed to parse GitHub API response";
const GH_FETCH_ERR: &str = "Failed to fetch GitHub data";

/// `GET /api/github/user/:username`
#[derive(Debug, Default, Serialize, specta::Type, utoipa::ToSchema)]
pub struct GithubUserResponse {
    pub login: Option<String>,
    pub name: Option<String>,
    pub avatar_url: Option<String>,
    pub html_url: Option<String>,
    #[specta(type = Option<specta_typescript::Number>)]
    pub public_repos: Option<i64>,
    pub error: Option<String>,
}

/// `GET /api/github/user/:username` —— 原本是原樣代理 GitHub 回應,改成只回上面五欄。
///
/// 順手修掉一個 bug:GitHub 的錯誤物件是 `{message, documentation_url}`,沒有 `error`,
/// 而前端一直在檢查 `.error`——所以 404 / rate limit 以前是「一個所有欄位都 undefined
/// 的使用者物件」悄悄穿過去。現在把 GitHub 的 message 收進 error 欄位。
#[utoipa::path(get, path = "/api/github/user/{username}", tag = "integrations",
    params(("username" = String, Path)),
    responses((status = 200, body = GithubUserResponse)))]
pub async fn github_user(State(state): State<AppState>, Path(username): Path<String>) -> Response {
    let url = format!("{}/users/{username}", state.external.github_api);
    let v = match fetch_json_lenient(&state.http, &url, Some(GH_UA), GH_PARSE_ERR, GH_FETCH_ERR).await {
        Ok(v) => v,
        Err(e) => {
            return (
                StatusCode::INTERNAL_SERVER_ERROR,
                Json(GithubUserResponse { error: Some(e), ..Default::default() }),
            )
                .into_response();
        }
    };
    let s = |k: &str| v.get(k).and_then(|x| x.as_str()).map(String::from);
    // 上游狀態碼一律不看(維持既有契約),錯誤走 error 欄位
    Json(GithubUserResponse {
        login: s("login"),
        name: s("name"),
        avatar_url: s("avatar_url"),
        html_url: s("html_url"),
        public_repos: v.get("public_repos").and_then(serde_json::Value::as_i64),
        error: s("message"),
    })
    .into_response()
}

/// `GET /api/github/repos/:username` 的一列。
#[derive(Debug, Serialize, specta::Type, utoipa::ToSchema)]
pub struct GithubRepo {
    #[specta(type = specta_typescript::Number)]
    pub id: i64,
    pub name: String,
    pub html_url: String,
    pub description: Option<String>,
    pub language: Option<String>,
    #[specta(type = specta_typescript::Number)]
    pub stargazers_count: i64,
}

/// `GET /api/github/repos/:username`
///
/// 這支以前不存在——前端直接從瀏覽器打 `api.github.com/users/:u/repos`。那條路是
/// **未認證**的,額度 60 req/hr 且是算在**讀者的 IP** 上;共用出口(公司 NAT、CGNAT、
/// VPN)額滿時這一區會靜默空白。收進後端就吃得到 GITHUB_TOKEN 的 5000/hr。
#[derive(Debug, Default, Serialize, specta::Type, utoipa::ToSchema)]
pub struct GithubReposResponse {
    pub repos: Vec<GithubRepo>,
    pub error: Option<String>,
}

#[derive(Debug, Deserialize)]
pub struct ReposQuery {
    limit: Option<u32>,
}

/// `GET /api/github/repos/:username` —— 依最後更新排序取前 N(預設 5)。
#[utoipa::path(get, path = "/api/github/repos/{username}", tag = "integrations",
    params(("username" = String, Path), ("limit" = Option<u32>, Query)),
    responses((status = 200, body = GithubReposResponse)))]
pub async fn github_repos(
    State(state): State<AppState>,
    Path(username): Path<String>,
    Query(q): Query<ReposQuery>,
) -> Response {
    let limit = q.limit.unwrap_or(5).clamp(1, 100);
    let token = std::env::var("GITHUB_TOKEN").ok().filter(|s| !s.is_empty());
    let path = format!("/users/{username}/repos?sort=updated&per_page={limit}");
    let Some(v) = gh_fetch(&state.http, &state.external.github_api, &path, token.as_deref()).await else {
        return Json(GithubReposResponse { repos: vec![], error: Some(GH_FETCH_ERR.to_string()) })
            .into_response();
    };
    let Some(arr) = v.as_array() else {
        // GitHub 錯誤物件({message,…})→ error 欄位,維持「不看上游狀態碼」的既有契約
        let error = v.get("message").and_then(|m| m.as_str()).map(String::from);
        return Json(GithubReposResponse { repos: vec![], error }).into_response();
    };
    let repos = arr
        .iter()
        .filter_map(|r| {
            // id / name / html_url 缺任一就整筆不收:那三個是 render 一張卡片的必需品
            Some(GithubRepo {
                id: r.get("id").and_then(serde_json::Value::as_i64)?,
                name: r.get("name").and_then(|x| x.as_str())?.to_string(),
                html_url: r.get("html_url").and_then(|x| x.as_str())?.to_string(),
                description: r.get("description").and_then(|x| x.as_str()).map(String::from),
                language: r.get("language").and_then(|x| x.as_str()).map(String::from),
                stargazers_count: r.get("stargazers_count").and_then(serde_json::Value::as_i64).unwrap_or(0),
            })
        })
        .collect();
    Json(GithubReposResponse { repos, error: None }).into_response()
}

/// 貢獻熱圖的一天。
#[derive(Debug, Serialize, specta::Type, utoipa::ToSchema)]
pub struct GithubContributionDay {
    /// `YYYY-MM-DD`
    pub date: String,
    #[specta(type = specta_typescript::Number)]
    pub count: i64,
}

/// `GET /api/github/contributions/:username`
///
/// 以前是前端直接打第三方的 `github-contributions-api.jogruber.de`——那是一個**爬
/// GitHub 個人頁 HTML** 的服務。GitHub 的 REST API 沒有貢獻資料,但 GraphQL 有官方的
/// `contributionsCollection.contributionCalendar`,而我們本來就有 token,所以不是把
/// jogruber 代理起來,是直接不需要它了。
#[derive(Debug, Default, Serialize, specta::Type, utoipa::ToSchema)]
pub struct GithubContributionsResponse {
    pub contributions: Vec<GithubContributionDay>,
    #[specta(type = specta_typescript::Number)]
    pub total: i64,
    pub error: Option<String>,
}

#[derive(Debug, Deserialize)]
pub struct ContributionsQuery {
    /// 西元年;省略或 "last" 都代表「最近一年」
    year: Option<String>,
}

/// `GET /api/github/contributions/:username?year=2025`
#[utoipa::path(get, path = "/api/github/contributions/{username}", tag = "integrations",
    params(("username" = String, Path), ("year" = Option<String>, Query)),
    responses((status = 200, body = GithubContributionsResponse)))]
pub async fn github_contributions(
    State(state): State<AppState>,
    Path(username): Path<String>,
    Query(q): Query<ContributionsQuery>,
) -> Response {
    let err = |m: String| {
        Json(GithubContributionsResponse { error: Some(m), ..Default::default() }).into_response()
    };
    let Some(token) = std::env::var("GITHUB_TOKEN").ok().filter(|s| !s.is_empty()) else {
        return err("GITHUB_TOKEN 未設定(GraphQL 一定要認證)".into());
    };
    // year 只接受四位數字:它會被拼進 GraphQL 的 ISO 時間字串
    let range = match q.year.as_deref().filter(|y| *y != "last") {
        Some(y) if y.len() == 4 && y.bytes().all(|b| b.is_ascii_digit()) => {
            Some((format!("{y}-01-01T00:00:00Z"), format!("{y}-12-31T23:59:59Z")))
        }
        Some(_) => return err("year 格式不正確".into()),
        // 不帶 from/to:GraphQL 預設就是最近一年
        None => None,
    };
    // 不帶 from/to 時 GraphQL 預設就是「最近一年」,所以整組引數直接省略
    let args = match &range {
        Some((f, t)) => format!(r#"(from: "{f}", to: "{t}")"#),
        None => String::new(),
    };
    // login 走 GraphQL variable(不拼字串);from/to 上面已經驗過只有四位數字組成
    let query = format!(
        r"query($login: String!) {{
             user(login: $login) {{
               contributionsCollection{args} {{
                 contributionCalendar {{
                   totalContributions
                   weeks {{ contributionDays {{ date contributionCount }} }}
                 }}
               }}
             }}
           }}"
    );
    let resp = state
        .http
        .post(format!("{}/graphql", state.external.github_api))
        .header("User-Agent", GH_UA)
        .bearer_auth(&token)
        .timeout(std::time::Duration::from_secs(10))
        .json(&json!({ "query": query, "variables": { "login": username } }))
        .send()
        .await;
    let Ok(resp) = resp else { return err(GH_FETCH_ERR.into()) };
    let Ok(text) = resp.text().await else { return err(GH_FETCH_ERR.into()) };
    let Ok(v) = serde_json::from_str::<Value>(&text) else { return err(GH_PARSE_ERR.into()) };
    // GraphQL 的錯誤是 200 + {errors:[…]},不是狀態碼
    if let Some(msg) = v.pointer("/errors/0/message").and_then(|m| m.as_str()) {
        return err(msg.to_string());
    }
    let cal = v.pointer("/data/user/contributionsCollection/contributionCalendar");
    let contributions: Vec<GithubContributionDay> = cal
        .and_then(|c| c.get("weeks"))
        .and_then(|w| w.as_array())
        .map(|weeks| {
            weeks
                .iter()
                .filter_map(|w| w.get("contributionDays").and_then(|d| d.as_array()))
                .flatten()
                .filter_map(|d| {
                    Some(GithubContributionDay {
                        date: d.get("date").and_then(|x| x.as_str())?.to_string(),
                        count: d.get("contributionCount").and_then(serde_json::Value::as_i64).unwrap_or(0),
                    })
                })
                .collect()
        })
        .unwrap_or_default();
    let total =
        cal.and_then(|c| c.get("totalContributions")).and_then(serde_json::Value::as_i64).unwrap_or(0);
    Json(GithubContributionsResponse { contributions, total, error: None }).into_response()
}

/// 作品頁(前端 about/Works)列的 repo,順序就是作品頁的順序(第一個是螺旋的起點)。
/// 加一件作品=在這裡加一行、前端 `data/works` 補一句介紹;它在畫面上長什麼樣子全由數據決定。
///
/// 刻意寫死、不讓前端傳:這支用的是站上的 GITHUB_TOKEN,接受任意 repo 清單的話,
/// 任何人換參數就能把 token 的 GraphQL 額度耗光。
const WORK_REPOS: &[(&str, &str)] = &[
    ("timo9378", "Volticar_API"),
    ("timo9378", "sora-to-ki"),
    ("timo9378", "flow2code"),
    ("timo9378", "session-to-obsidian"),
    ("timo9378", "anigamer-rs"),
    ("timo9378", "nuntius"),
    ("Limatura", "tessera"),
];

/// 一件作品的一種語言:GitHub 算的程式碼量(bytes)。
#[derive(Debug, Serialize, specta::Type, utoipa::ToSchema)]
pub struct WorkLanguage {
    pub name: String,
    #[specta(type = specta_typescript::Number)]
    pub bytes: i64,
}

/// `GET /api/github/works` 的一件作品。
#[derive(Debug, Serialize, specta::Type, utoipa::ToSchema)]
pub struct WorkRepo {
    /// `owner/name`
    pub repo: String,
    /// 私有 repo 沒有連結(讀者點過去只會看到 404)
    pub url: Option<String>,
    pub created_at: String,
    pub pushed_at: String,
    #[specta(type = specta_typescript::Number)]
    pub stars: i64,
    /// 預設分支上的 commit 數
    #[specta(type = specta_typescript::Number)]
    pub commits: i64,
    /// 由多到少
    pub languages: Vec<WorkLanguage>,
}

#[derive(Debug, Default, Serialize, specta::Type, utoipa::ToSchema)]
pub struct WorksResponse {
    pub works: Vec<WorkRepo>,
    pub error: Option<String>,
}

/// `GET /api/github/works` —— [`WORK_REPOS`] 每一個的語言組成、commit 數、星數、建立與最後推送時間。
/// 一次 GraphQL 查完(每個 repo 一個 alias)。抓不到回 502,讓上游快取層拿舊的資料頂著。
#[utoipa::path(get, path = "/api/github/works", tag = "integrations",
    responses((status = 200, body = WorksResponse)))]
pub async fn github_works(State(state): State<AppState>) -> Response {
    let fail = |m: String| {
        (StatusCode::BAD_GATEWAY, Json(WorksResponse { error: Some(m), ..Default::default() }))
            .into_response()
    };
    let Some(token) = std::env::var("GITHUB_TOKEN").ok().filter(|s| !s.is_empty()) else {
        return fail("GITHUB_TOKEN 未設定(GraphQL 一定要認證)".into());
    };
    // owner / name 來自上面寫死的常數,不是使用者輸入,可以直接拼進查詢
    let fields = WORK_REPOS
        .iter()
        .enumerate()
        .map(|(i, (owner, name))| {
            format!(
                r#"r{i}: repository(owner: "{owner}", name: "{name}") {{
                     nameWithOwner url isPrivate createdAt pushedAt stargazerCount
                     languages(first: 8, orderBy: {{field: SIZE, direction: DESC}}) {{ edges {{ size node {{ name }} }} }}
                     defaultBranchRef {{ target {{ ... on Commit {{ history {{ totalCount }} }} }} }}
                   }}"#
            )
        })
        .collect::<Vec<_>>()
        .join("\n");
    let resp = state
        .http
        .post(format!("{}/graphql", state.external.github_api))
        .header("User-Agent", GH_UA)
        .bearer_auth(&token)
        .timeout(std::time::Duration::from_secs(10))
        .json(&json!({ "query": format!("query {{ {fields} }}") }))
        .send()
        .await;
    let Ok(resp) = resp else { return fail(GH_FETCH_ERR.into()) };
    let Ok(text) = resp.text().await else { return fail(GH_FETCH_ERR.into()) };
    let Ok(v) = serde_json::from_str::<Value>(&text) else { return fail(GH_PARSE_ERR.into()) };
    let Some(data) = v.get("data").filter(|d| d.is_object()) else {
        let msg = v.pointer("/errors/0/message").and_then(|m| m.as_str()).unwrap_or(GH_PARSE_ERR);
        return fail(msg.to_string());
    };
    // 個別 repo 抓不到(改名、刪掉)時 GraphQL 會回那個 alias 是 null 加一則 error:
    // 那一件就不列,其他照常
    let works = (0..WORK_REPOS.len())
        .filter_map(|i| {
            let r = data.get(format!("r{i}"))?;
            let s = |k: &str| r.get(k).and_then(|x| x.as_str()).map(String::from);
            let private = r.get("isPrivate").and_then(Value::as_bool).unwrap_or(true);
            Some(WorkRepo {
                repo: s("nameWithOwner")?,
                url: if private { None } else { s("url") },
                created_at: s("createdAt")?,
                pushed_at: s("pushedAt")?,
                stars: r.get("stargazerCount").and_then(Value::as_i64).unwrap_or(0),
                commits: r
                    .pointer("/defaultBranchRef/target/history/totalCount")
                    .and_then(Value::as_i64)
                    .unwrap_or(0),
                languages: r
                    .pointer("/languages/edges")
                    .and_then(Value::as_array)
                    .map(|edges| {
                        edges
                            .iter()
                            .filter_map(|e| {
                                Some(WorkLanguage {
                                    name: e.pointer("/node/name")?.as_str()?.to_string(),
                                    bytes: e.get("size")?.as_i64()?,
                                })
                            })
                            .collect()
                    })
                    .unwrap_or_default(),
            })
        })
        .collect();
    Json(WorksResponse { works, error: None }).into_response()
}

#[derive(Debug, Serialize, specta::Type, utoipa::ToSchema)]
pub struct GithubCommitAuthor {
    pub name: Option<String>,
    pub email: Option<String>,
}

/// PushEvent 的一個 commit。sha 缺的 commit 直接不收——沒有 sha 就連不出 commit 連結,
/// 收進來只是把「可能是 null」傳染給前端。
#[derive(Debug, Serialize, specta::Type, utoipa::ToSchema)]
pub struct GithubCommit {
    pub sha: String,
    pub message: String,
    pub author: Option<GithubCommitAuthor>,
}

#[derive(Debug, Serialize, specta::Type, utoipa::ToSchema)]
pub struct GithubEventRepo {
    /// `owner/repo`
    pub name: String,
}

/// 只保留 PushEvent 用得到的欄位。其他事件型別的 payload 會是空 commits + null
/// ——前端只 render PushEvent,這裡不為沒人看的事件型別各建一份形狀。
#[derive(Debug, Default, Serialize, specta::Type, utoipa::ToSchema)]
pub struct GithubEventPayload {
    pub commits: Vec<GithubCommit>,
    pub before: Option<String>,
    pub head: Option<String>,
    #[specta(type = Option<specta_typescript::Number>)]
    pub size: Option<i64>,
}

#[derive(Debug, Serialize, specta::Type, utoipa::ToSchema)]
pub struct GithubEvent {
    pub id: String,
    #[serde(rename = "type")]
    pub kind: String,
    pub repo: GithubEventRepo,
    pub created_at: String,
    pub payload: GithubEventPayload,
}

/// `GET /api/github/events/:username`
///
/// 原本直接回一個 JSON 陣列(GitHub 錯誤時回 GitHub 的錯誤物件),而前端的型別寫成
/// `GithubEvent[] & { error?: string }` —— 陣列身上不會有 `.error`,那個交集型別是假的。
/// 改成包一層讓 error 成為真的欄位。
#[derive(Debug, Default, Serialize, specta::Type, utoipa::ToSchema)]
pub struct GithubEventsResponse {
    pub events: Vec<GithubEvent>,
    pub error: Option<String>,
}

/// `GET /api/github/events/:username` —— **一律用 /events/public**(只回公開事件)。
/// 有 token 時仍帶(拉高 rate limit + 供下面 enrich 空 commits 的 compare API 用),
/// 但端點固定 public:否則帶自己的 token 打 /events 會連**私有 repo 的 push 也回傳**(隱私外洩)。
#[utoipa::path(get, path = "/api/github/events/{username}", tag = "integrations",
    params(("username" = String, Path)),
    responses((status = 200, body = GithubEventsResponse)))]
pub async fn github_events(State(state): State<AppState>, Path(username): Path<String>) -> Response {
    let token = std::env::var("GITHUB_TOKEN").ok().filter(|s| !s.is_empty());
    let path = format!("/users/{username}/events/public?per_page=30");
    let events = gh_fetch(&state.http, &state.external.github_api, &path, token.as_deref()).await;

    let Some(Value::Array(mut events)) = events else {
        // GitHub 錯誤物件({message,…})→ error 欄位;抓不到 / null → 空清單
        let error = events
            .as_ref()
            .and_then(|v| v.get("message"))
            .and_then(|m| m.as_str())
            .map(String::from)
            .or_else(|| events.is_none().then(|| GH_FETCH_ERR.to_string()));
        return Json(GithubEventsResponse { events: vec![], error }).into_response();
    };

    if let Some(t) = &token {
        // 以前每個 push 依序 await 一次 compare:30 筆事件裡常有十幾筆 push 不帶 commits,
        // 整支要 7–10 秒。改成一起發,而 commit 範圍(repo, before, head)抓過就不會變,記起來不再抓。
        let mut jobs = tokio::task::JoinSet::new();
        for (i, ev) in events.iter().enumerate() {
            let Some(cmp_path) = compare_path_for(ev) else { continue };
            let hit = COMPARE_CACHE.lock().get(&cmp_path).cloned();
            if let Some(hit) = hit {
                jobs.spawn(async move { (i, Some(hit)) });
                continue;
            }
            let (http, base, t) = (state.http.clone(), state.external.github_api.clone(), t.clone());
            jobs.spawn(async move {
                let cmp = gh_fetch(&http, &base, &cmp_path, Some(&t)).await;
                let mapped =
                    cmp.as_ref().and_then(|c| c.get("commits")).and_then(|c| c.as_array()).map(|commits| {
                        commits
                            .iter()
                            .map(|c| {
                                json!({
                                    "sha": c.get("sha").cloned().unwrap_or(Value::Null),
                                    "message": c.pointer("/commit/message").cloned().unwrap_or(Value::Null),
                                    "author": c.pointer("/commit/author").cloned().unwrap_or(Value::Null),
                                })
                            })
                            .collect::<Vec<Value>>()
                    });
                if let Some(m) = &mapped {
                    let mut cache = COMPARE_CACHE.lock();
                    if cache.len() >= COMPARE_CACHE_MAX {
                        cache.clear(); // 只是省 API 額度的快取,滿了整個重來就好
                    }
                    cache.insert(cmp_path, m.clone());
                }
                (i, mapped)
            });
        }
        while let Some(Ok((i, mapped))) = jobs.join_next().await {
            let Some(mapped) = mapped else { continue };
            if let Some(payload) = events[i].get_mut("payload").and_then(|p| p.as_object_mut()) {
                payload.insert("size".into(), json!(mapped.len()));
                payload.insert("commits".into(), Value::Array(mapped));
            }
        }
    }
    Json(GithubEventsResponse { events: events.iter().filter_map(github_event_from).collect(), error: None })
        .into_response()
}

/// compare 結果的快取,key 是 compare 路徑(含 repo、before、head)。
static COMPARE_CACHE: std::sync::LazyLock<parking_lot::Mutex<std::collections::HashMap<String, Vec<Value>>>> =
    std::sync::LazyLock::new(Default::default);
const COMPARE_CACHE_MAX: usize = 512;

/// 不帶 commits 的 push(GitHub 對大 push 會省略)→ 要補抓的 compare 路徑;其他事件 → None。
fn compare_path_for(ev: &Value) -> Option<String> {
    if ev.get("type").and_then(|v| v.as_str()) != Some("PushEvent") {
        return None;
    }
    let p = ev.get("payload");
    let commits_empty =
        p.and_then(|p| p.get("commits")).and_then(|c| c.as_array()).is_none_or(std::vec::Vec::is_empty);
    let field = |k: &str| p.and_then(|p| p.get(k)).filter(|v| js_truthy(Some(v))).and_then(|v| v.as_str());
    let repo = ev.pointer("/repo/name").and_then(|v| v.as_str())?;
    let (before, head) = (field("before")?, field("head")?);
    commits_empty.then(|| format!("/repos/{repo}/compare/{before}...{head}"))
}

/// GitHub 事件 → 我們的形狀。id / type / repo.name / created_at 任一缺就整筆不收:
/// 那四個欄位是前端 render 一列必需的,缺了也沒東西可顯示。
fn github_event_from(ev: &Value) -> Option<GithubEvent> {
    let s = |k: &str| ev.get(k).and_then(|v| v.as_str()).map(String::from);
    let repo = ev.pointer("/repo/name").and_then(|v| v.as_str()).map(String::from);
    let (Some(id), Some(kind), Some(repo), Some(created_at)) = (s("id"), s("type"), repo, s("created_at"))
    else {
        tracing::warn!("[github] 跳過缺 id/type/repo.name/created_at 的事件");
        return None;
    };
    let p = ev.get("payload");
    let ps = |k: &str| p.and_then(|p| p.get(k)).and_then(|v| v.as_str()).map(String::from);
    let commits = p
        .and_then(|p| p.get("commits"))
        .and_then(|c| c.as_array())
        .map(|a| {
            a.iter()
                .filter_map(|c| {
                    let sha = c.get("sha").and_then(|v| v.as_str())?.to_string();
                    let author = c.get("author").and_then(|a| a.as_object()).map(|a| GithubCommitAuthor {
                        name: a.get("name").and_then(|v| v.as_str()).map(String::from),
                        email: a.get("email").and_then(|v| v.as_str()).map(String::from),
                    });
                    let message = c.get("message").and_then(|v| v.as_str()).unwrap_or_default().to_string();
                    Some(GithubCommit { sha, message, author })
                })
                .collect()
        })
        .unwrap_or_default();
    Some(GithubEvent {
        id,
        kind,
        repo: GithubEventRepo { name: repo },
        created_at,
        payload: GithubEventPayload {
            commits,
            before: ps("before"),
            head: ps("head"),
            size: p.and_then(|p| p.get("size")).and_then(serde_json::Value::as_i64),
        },
    })
}

// ── WakaTime ──────────────────────────────────────────────────────────────

use base64::Engine;

fn wakatime_key() -> Option<String> {
    std::env::var("WAKATIME_API_KEY").ok().filter(|s| !s.is_empty())
}

fn waka_auth(key: &str) -> String {
    format!("Basic {}", base64::engine::general_purpose::STANDARD.encode(key))
}

const WAKA_UNCONFIGURED: &str = "WakaTime API 未配置(請在 server/.env 設置 WAKATIME_API_KEY)";

/// WakaTime 的 `grand_total`(前端只用 text,total_seconds 一起帶著方便日後算)。
#[derive(Debug, Serialize, specta::Type, utoipa::ToSchema)]
pub struct WakatimeGrandTotal {
    pub text: Option<String>,
    #[serde(serialize_with = "crate::util::ser_js_number_opt")]
    #[specta(type = Option<specta_typescript::Number>)]
    pub total_seconds: Option<f64>,
}

/// durations 端點算出來的「實際編碼區間」——第一筆的開始到最後一筆的結束。
#[derive(Debug, Default, Serialize, specta::Type, utoipa::ToSchema)]
pub struct WakatimeActualCodingTime {
    pub start: Option<String>,
    pub end: Option<String>,
    #[serde(rename = "hasData")]
    pub has_data: bool,
}

/// `GET /api/wakatime/today`
///
/// 原本回 WakaTime 的 `{data:[summary], start, end}` 加上 actualCodingTime,
/// summary 是一整包(categories / editors / machines / …)而前端只讀
/// `data[0].grand_total.text`。這裡把那個只有一個元素的陣列攤掉。
#[derive(Debug, Default, Serialize, specta::Type, utoipa::ToSchema)]
pub struct WakatimeTodayResponse {
    pub grand_total: Option<WakatimeGrandTotal>,
    /// WakaTime 回的查詢區間(非「實際編碼」區間)
    pub start: Option<String>,
    pub end: Option<String>,
    #[serde(rename = "actualCodingTime")]
    pub actual_coding_time: WakatimeActualCodingTime,
    pub error: Option<String>,
    /// 上游的錯誤內容(原本叫 details,是 parse 過的 body;這裡轉字串好進型別)
    pub details: Option<String>,
}

/// stats 端點的一列(語言 / 專案共用同一個形狀)。
#[derive(Debug, Serialize, specta::Type, utoipa::ToSchema)]
pub struct WakatimeStat {
    pub name: String,
    pub text: String,
    #[serde(serialize_with = "ser_js_number")]
    #[specta(type = specta_typescript::Number)]
    pub percent: f64,
}

/// `GET /api/wakatime/week`、`GET /api/wakatime/projects`
///
/// 原本回 WakaTime 的 `{data:{languages, projects, editors, …}}` 原樣,前端讀 `.data`。
/// 這裡把 data 攤掉、只留前端會 render 的兩組。
#[derive(Debug, Default, Serialize, specta::Type, utoipa::ToSchema)]
pub struct WakatimeStatsResponse {
    pub languages: Vec<WakatimeStat>,
    pub projects: Vec<WakatimeStat>,
    pub error: Option<String>,
    pub details: Option<String>,
}

fn waka_stats_from(data: &Value) -> Vec<WakatimeStat> {
    data.as_array()
        .map(|a| {
            a.iter()
                .filter_map(|x| {
                    Some(WakatimeStat {
                        name: x.get("name").and_then(|v| v.as_str())?.to_string(),
                        text: x.get("text").and_then(|v| v.as_str()).unwrap_or_default().to_string(),
                        percent: x.get("percent").and_then(serde_json::Value::as_f64).unwrap_or(0.0),
                    })
                })
                .collect()
        })
        .unwrap_or_default()
}

/// axios 式請求:非 2xx → Err((status, parsed body))、網路錯 → Err((500, message 字串))。
async fn waka_get(http: &reqwest::Client, url: &str, key: &str) -> Result<Value, (StatusCode, Value)> {
    let resp = http
        .get(url)
        .header("Authorization", waka_auth(key))
        .timeout(std::time::Duration::from_secs(10))
        .send()
        .await
        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, Value::from(e.to_string())))?;
    let status = resp.status();
    let body =
        resp.text().await.map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, Value::from(e.to_string())))?;
    let mut v: Value = serde_json::from_str(&body).unwrap_or_else(|_| Value::from(body));
    crate::util::js_normalize_numbers(&mut v);
    if status.is_success() { Ok(v) } else { Err((status, v)) }
}

/// 上游錯誤 → (狀態碼, error, details)。details 原本是 parse 過的 body,轉字串好進型別。
fn waka_err_parts(kind: &str, e: (StatusCode, Value)) -> (StatusCode, Option<String>, Option<String>) {
    let details = match e.1 {
        Value::String(s) => Some(s),
        Value::Null => None,
        v => Some(v.to_string()),
    };
    (e.0, Some(kind.to_string()), details)
}

/// `GET /api/wakatime/today` —— summaries + durations 並行,合併 actualCodingTime。
#[utoipa::path(get, path = "/api/wakatime/today", tag = "integrations",
    responses((status = 200, body = WakatimeTodayResponse)))]
pub async fn wakatime_today(State(state): State<AppState>) -> Response {
    let Some(key) = wakatime_key() else {
        return (
            StatusCode::INTERNAL_SERVER_ERROR,
            Json(WakatimeTodayResponse { error: Some(WAKA_UNCONFIGURED.to_string()), ..Default::default() }),
        )
            .into_response();
    };
    let date = today_utc();
    let base = &state.external.wakatime;
    let url_summary = format!("{base}/api/v1/users/current/summaries?start={date}&end={date}");
    let url_durations = format!("{base}/api/v1/users/current/durations?date={date}");
    let (summary, durations) =
        tokio::join!(waka_get(&state.http, &url_summary, &key), waka_get(&state.http, &url_durations, &key));
    let today_err = |e| {
        let (status, error, details) = waka_err_parts("Failed to fetch WakaTime today data", e);
        (status, Json(WakatimeTodayResponse { error, details, ..Default::default() })).into_response()
    };
    let summary = match summary {
        Ok(v) => v,
        Err(e) => return today_err(e),
    };
    let durations = match durations {
        Ok(v) => v,
        Err(e) => return today_err(e),
    };

    let dur_list: Vec<&Value> =
        durations.get("data").and_then(|d| d.as_array()).map(|a| a.iter().collect()).unwrap_or_default();
    let mut actual_start: Option<f64> = None;
    let mut actual_end: Option<f64> = None;
    for d in &dur_list {
        if let Some(t) = d.get("time").and_then(serde_json::Value::as_f64) {
            actual_start = Some(actual_start.map_or(t, |e| e.min(t)));
            let end = t + d.get("duration").and_then(serde_json::Value::as_f64).unwrap_or(0.0);
            actual_end = Some(actual_end.map_or(end, |e| e.max(end)));
        }
    }
    let gt = summary.pointer("/data/0/grand_total");

    Json(WakatimeTodayResponse {
        grand_total: gt.map(|g| WakatimeGrandTotal {
            text: g.get("text").and_then(|v| v.as_str()).map(String::from),
            total_seconds: g.get("total_seconds").and_then(serde_json::Value::as_f64),
        }),
        start: summary.get("start").and_then(|v| v.as_str()).map(String::from),
        end: summary.get("end").and_then(|v| v.as_str()).map(String::from),
        actual_coding_time: WakatimeActualCodingTime {
            // JS new Date(x*1000):ms 取整(ToInteger 截斷)。Rust 的 f64→i64 是飽和轉換,
            // 這裡要的就是 JS 那個截斷語意,不是「可能出錯的轉換」。
            #[allow(clippy::cast_possible_truncation, reason = "刻意複製 JS ToInteger 的截斷語意")]
            start: actual_start.map(|t| iso_from_millis((t * 1000.0) as i64)),
            #[allow(clippy::cast_possible_truncation, reason = "刻意複製 JS ToInteger 的截斷語意")]
            end: actual_end.map(|t| iso_from_millis((t * 1000.0) as i64)),
            has_data: !dur_list.is_empty(),
        },
        error: None,
        details: None,
    })
    .into_response()
}

/// week / projects 共用(同一支 stats API,只差錯誤字串)。
async fn wakatime_stats(state: &AppState, err_kind: &str) -> Response {
    let Some(key) = wakatime_key() else {
        return (
            StatusCode::INTERNAL_SERVER_ERROR,
            Json(WakatimeStatsResponse { error: Some(WAKA_UNCONFIGURED.to_string()), ..Default::default() }),
        )
            .into_response();
    };
    let stats_url = format!("{}/api/v1/users/current/stats/last_7_days", state.external.wakatime);
    match waka_get(&state.http, &stats_url, &key).await {
        Ok(v) => Json(WakatimeStatsResponse {
            languages: waka_stats_from(v.pointer("/data/languages").unwrap_or(&Value::Null)),
            projects: waka_stats_from(v.pointer("/data/projects").unwrap_or(&Value::Null)),
            error: None,
            details: None,
        })
        .into_response(),
        Err(e) => {
            let (status, error, details) = waka_err_parts(err_kind, e);
            (status, Json(WakatimeStatsResponse { error, details, ..Default::default() })).into_response()
        }
    }
}

#[utoipa::path(get, path = "/api/wakatime/week", tag = "integrations",
    responses((status = 200, body = WakatimeStatsResponse)))]
pub async fn wakatime_week(State(state): State<AppState>) -> Response {
    wakatime_stats(&state, "Failed to fetch WakaTime week data").await
}

/// ⚠️ 與 `/week` 打同一支上游 API、回同一份資料,差別只有錯誤字串(Express 就這樣,照抄)。
/// 前端只用 `/week`。
#[utoipa::path(get, path = "/api/wakatime/projects", tag = "integrations",
    responses((status = 200, body = WakatimeStatsResponse)))]
pub async fn wakatime_projects(State(state): State<AppState>) -> Response {
    wakatime_stats(&state, "Failed to fetch WakaTime projects data").await
}

// ── Steam(純代理 4 支;/steam/profile 有 SWR 快取留 proxy)────────────────

fn steam_env() -> Option<(String, String)> {
    let key = std::env::var("STEAM_API_KEY").ok().filter(|s| !s.is_empty())?;
    let id = std::env::var("STEAM_ID").ok().filter(|s| !s.is_empty())?;
    Some((key, id))
}

const STEAM_UNCONFIGURED: &str = "Steam API 未配置(請在 server/.env 設置 STEAM_API_KEY 和 STEAM_ID)";
const STEAM_PARSE_ERR: &str = "Failed to parse Steam API response";
const STEAM_FETCH_ERR: &str = "Failed to fetch Steam data";

/// GetPlayerSummaries 的 `players[0]` 裡我們用得到的欄位(欄位名沿用 Steam 的)。
#[derive(Debug, Clone, Serialize, specta::Type, utoipa::ToSchema)]
pub struct SteamPlayer {
    pub personaname: Option<String>,
    pub avatarfull: Option<String>,
    pub profileurl: Option<String>,
    /// Steam 的狀態 enum(1 = 上線)
    #[specta(type = Option<specta_typescript::Number>)]
    pub personastate: Option<i64>,
    /// 正在玩的 appid。Steam 這欄回**字串**不是數字(有值就代表在遊戲中)
    pub gameid: Option<String>,
}

/// `GET /api/steam/player`
///
/// 原本原樣回 Steam 的 `{response:{players:[…]}}`,前端自己挖 `response.players[0]`。
/// 這裡把那層挖掉——一個 steamid 就只會有一個 player。
#[derive(Debug, Default, Serialize, specta::Type, utoipa::ToSchema)]
pub struct SteamPlayerResponse {
    pub player: Option<SteamPlayer>,
    pub error: Option<String>,
}

#[derive(Debug, Serialize, specta::Type, utoipa::ToSchema)]
pub struct SteamGame {
    #[specta(type = Option<specta_typescript::Number>)]
    pub appid: Option<i64>,
    pub name: Option<String>,
    #[specta(type = Option<specta_typescript::Number>)]
    pub playtime_2weeks: Option<i64>,
    #[specta(type = Option<specta_typescript::Number>)]
    pub playtime_forever: Option<i64>,
}

/// `GET /api/steam/recent-games` 與 `GET /api/steam/owned-games`
/// (`gameCount` 只有 owned-games 會有;那是我們自己的欄位名,故 camelCase)。
#[derive(Debug, Default, Serialize, specta::Type, utoipa::ToSchema)]
pub struct SteamGamesResponse {
    pub games: Vec<SteamGame>,
    #[serde(rename = "gameCount")]
    #[specta(type = Option<specta_typescript::Number>)]
    pub game_count: Option<i64>,
    pub error: Option<String>,
}

fn steam_games_from(v: &Value) -> Vec<SteamGame> {
    v.pointer("/response/games")
        .and_then(|g| g.as_array())
        .map(|a| {
            a.iter()
                .map(|g| SteamGame {
                    appid: g.get("appid").and_then(serde_json::Value::as_i64),
                    name: g.get("name").and_then(|x| x.as_str()).map(String::from),
                    playtime_2weeks: g.get("playtime_2weeks").and_then(serde_json::Value::as_i64),
                    playtime_forever: g.get("playtime_forever").and_then(serde_json::Value::as_i64),
                })
                .collect()
        })
        .unwrap_or_default()
}

#[utoipa::path(get, path = "/api/steam/player", tag = "integrations",
    responses((status = 200, body = SteamPlayerResponse)))]
pub async fn steam_player(State(state): State<AppState>) -> Response {
    let unconf = || {
        (
            StatusCode::INTERNAL_SERVER_ERROR,
            Json(SteamPlayerResponse { error: Some(STEAM_UNCONFIGURED.to_string()), ..Default::default() }),
        )
            .into_response()
    };
    let Some((key, id)) = steam_env() else { return unconf() };
    let url =
        format!("{}/ISteamUser/GetPlayerSummaries/v0002/?key={key}&steamids={id}", state.external.steam_api);
    match fetch_json_lenient(&state.http, &url, None, STEAM_PARSE_ERR, STEAM_FETCH_ERR).await {
        Err(e) => (
            StatusCode::INTERNAL_SERVER_ERROR,
            Json(SteamPlayerResponse { error: Some(e), ..Default::default() }),
        )
            .into_response(),
        Ok(v) => Json(SteamPlayerResponse {
            player: v.pointer("/response/players/0").map(steam_player_from),
            error: None,
        })
        .into_response(),
    }
}

fn steam_player_from(p: &Value) -> SteamPlayer {
    let s = |k: &str| p.get(k).and_then(|v| v.as_str()).map(String::from);
    SteamPlayer {
        personaname: s("personaname"),
        avatarfull: s("avatarfull"),
        profileurl: s("profileurl"),
        personastate: p.get("personastate").and_then(serde_json::Value::as_i64),
        gameid: s("gameid"),
    }
}

/// recent-games / owned-games 共用(只差 URL 與要不要帶 gameCount)。
async fn steam_games(state: &AppState, url: &str, with_count: bool) -> Response {
    match fetch_json_lenient(&state.http, url, None, STEAM_PARSE_ERR, STEAM_FETCH_ERR).await {
        Err(e) => (
            StatusCode::INTERNAL_SERVER_ERROR,
            Json(SteamGamesResponse { error: Some(e), ..Default::default() }),
        )
            .into_response(),
        Ok(v) => Json(SteamGamesResponse {
            games: steam_games_from(&v),
            game_count: with_count
                .then(|| v.pointer("/response/game_count").and_then(serde_json::Value::as_i64))
                .flatten(),
            error: None,
        })
        .into_response(),
    }
}

fn steam_games_unconfigured() -> Response {
    (
        StatusCode::INTERNAL_SERVER_ERROR,
        Json(SteamGamesResponse { error: Some(STEAM_UNCONFIGURED.to_string()), ..Default::default() }),
    )
        .into_response()
}

#[utoipa::path(get, path = "/api/steam/recent-games", tag = "integrations",
    responses((status = 200, body = SteamGamesResponse)))]
pub async fn steam_recent_games(State(state): State<AppState>) -> Response {
    let Some((key, id)) = steam_env() else { return steam_games_unconfigured() };
    let url = format!(
        "{}/IPlayerService/GetRecentlyPlayedGames/v0001/?key={key}&steamid={id}&format=json",
        state.external.steam_api
    );
    steam_games(&state, &url, false).await
}

#[utoipa::path(get, path = "/api/steam/owned-games", tag = "integrations",
    responses((status = 200, body = SteamGamesResponse)))]
pub async fn steam_owned_games(State(state): State<AppState>) -> Response {
    let Some((key, id)) = steam_env() else { return steam_games_unconfigured() };
    let url = format!(
        "{}/IPlayerService/GetOwnedGames/v0001/?key={key}&steamid={id}&include_appinfo=true&include_played_free_games=true&format=json",
        state.external.steam_api
    );
    steam_games(&state, &url, true).await
}

fn steam_unconfigured() -> Response {
    (StatusCode::INTERNAL_SERVER_ERROR, Json(json!({ "error": STEAM_UNCONFIGURED }))).into_response()
}

/// ⚠️ 這支**刻意留原樣代理**:站上沒有任何地方消費它,要 typed 就得替一份沒人看的
/// Steam 成就形狀憑空造型別。等真的有人用再收。
#[utoipa::path(get, path = "/api/steam/achievements/{appid}", tag = "integrations",
    params(("appid" = String, Path)),
    responses((status = 200, description = "Steam 遊戲成就(動態 JSON,唯一保留的原樣代理)")))]
pub async fn steam_achievements(State(state): State<AppState>, Path(appid): Path<String>) -> Response {
    let Some((key, id)) = steam_env() else { return steam_unconfigured() };
    passthrough_json(
        &state.http,
        &format!(
            "{}/ISteamUserStats/GetPlayerAchievements/v0001/?appid={appid}&key={key}&steamid={id}",
            state.external.steam_api
        ),
        None,
        "Failed to parse Steam API response",
        "Failed to fetch Steam achievements data",
    )
    .await
}

// ── Books 外部搜尋(Google Books + OpenLibrary fallback)──────────────────

/// Google Books 高解析度封面 URL 處理(JS .replace = 只換第一次出現)。
fn upgrade_google_cover(url: &str) -> String {
    if url.is_empty() {
        return String::new();
    }
    let mut cover = url.replacen("&zoom=1", "&zoom=0", 1).replacen("&edge=curl", "", 1).replacen(
        "&img=1",
        "&img=1&w=500&h=800",
        1,
    );
    if !cover.contains("zoom=") {
        cover.push_str("&zoom=0");
    }
    if !cover.contains("&w=") {
        cover.push_str("&w=500&h=800");
    }
    cover
}

fn s_or_empty(v: Option<&Value>) -> String {
    v.and_then(|x| x.as_str()).unwrap_or("").to_string()
}

/// `base` 是 Google Books 的 base URL(`state.external.google_books`)。
///
/// ⚠ 一定要帶 `GOOGLE_BOOKS_API_KEY`。沒帶 key 的請求吃的是**全世界共用的匿名額度**,
/// 2026-10 實測書櫃裡 22 個 ISBN 全部 429 `rateLimitExceeded`——後台用 ISBN「常常查不到」
/// 就是這個。而 429 的 body 也是合法 JSON(只是沒有 `items`),所以以前會被當成「查無此書」,
/// 靜靜退回 OpenLibrary(台灣的書它 22 本只有 8 本)。現在非 2xx 一律回 Err,由呼叫端轉成
/// 後台看得到的 warning。
async fn search_google_books(http: &reqwest::Client, base: &str, q: &str) -> Result<Vec<Value>, String> {
    let mut url = format!("{base}/books/v1/volumes?q={}&maxResults=10", encode_uri_component(q));
    if let Some(key) = std::env::var("GOOGLE_BOOKS_API_KEY").ok().filter(|s| !s.is_empty()) {
        url.push_str("&key=");
        url.push_str(&encode_uri_component(&key));
    }
    let resp = http.get(&url).send().await.map_err(|e| format!("Google Books 連不上:{e}"))?;
    let status = resp.status();
    let body = resp.text().await.map_err(|e| format!("Google Books 回應讀取失敗:{e}"))?;
    if !status.is_success() {
        let reason = serde_json::from_str::<Value>(&body)
            .ok()
            .and_then(|v| v.pointer("/error/errors/0/reason").and_then(|r| r.as_str()).map(String::from))
            .unwrap_or_default();
        return Err(if status == StatusCode::TOO_MANY_REQUESTS {
            format!("Google Books 額度用完({status} {reason})——檢查 GOOGLE_BOOKS_API_KEY")
        } else {
            format!("Google Books 回 {status} {reason}")
        });
    }
    let mut data: Value =
        serde_json::from_str(&body).map_err(|e| format!("Google Books 回應不是 JSON:{e}"))?;
    crate::util::js_normalize_numbers(&mut data);
    let Some(items) = data.get("items").and_then(|i| i.as_array()) else { return Ok(vec![]) };
    Ok(items
        .iter()
        .map(|item| {
            let v = item.get("volumeInfo").cloned().unwrap_or_else(|| json!({}));
            let find_isbn = |t: &str| -> Option<String> {
                v.get("industryIdentifiers")?.as_array()?.iter().find_map(|id| {
                    (id.get("type").and_then(|x| x.as_str()) == Some(t))
                        .then(|| id.get("identifier").and_then(|x| x.as_str()).map(String::from))
                        .flatten()
                })
            };
            let isbn = find_isbn("ISBN_13").or_else(|| find_isbn("ISBN_10")).unwrap_or_default();
            let img = v.get("imageLinks");
            let cover_raw = ["large", "medium", "thumbnail", "smallThumbnail"]
                .iter()
                .find_map(|k| img.and_then(|i| i.get(*k)).and_then(|x| x.as_str()).filter(|s| !s.is_empty()))
                .unwrap_or("");
            let authors = v
                .get("authors")
                .and_then(|a| a.as_array())
                .map(|a| a.iter().filter_map(|x| x.as_str()).collect::<Vec<_>>().join(", "))
                .unwrap_or_default();
            let categories = v
                .get("categories")
                .and_then(|a| a.as_array())
                .map(|a| a.iter().filter_map(|x| x.as_str()).collect::<Vec<_>>().join(", "))
                .unwrap_or_default();
            let page_count =
                v.get("pageCount").filter(|x| js_truthy(Some(x))).cloned().unwrap_or(Value::Null);
            json!({
                "isbn": isbn,
                "title": s_or_empty(v.get("title")),
                "authors": authors,
                "publisher": s_or_empty(v.get("publisher")),
                "published_date": s_or_empty(v.get("publishedDate")),
                "description": s_or_empty(v.get("description")),
                "cover_url": upgrade_google_cover(cover_raw),
                "page_count": page_count,
                "language": s_or_empty(v.get("language")),
                "categories": categories,
                "source": "google",
            })
        })
        .collect())
}

async fn fetch_json(http: &reqwest::Client, url: &str) -> Option<Value> {
    let mut v: Value = http.get(url).send().await.ok()?.json().await.ok()?;
    crate::util::js_normalize_numbers(&mut v);
    Some(v)
}

/// `base` 是 Open Library 的 base URL(`state.external.openlibrary`)。
async fn search_open_library(http: &reqwest::Client, base: &str, input: &str, is_isbn: bool) -> Vec<Value> {
    if is_isbn {
        let clean: String = input.chars().filter(|c| *c != '-' && !c.is_whitespace()).collect();
        let url = format!("{base}/api/books?bibkeys=ISBN:{clean}&format=json&jscmd=data");
        let Some(data) = fetch_json(http, &url).await else { return vec![] };
        let key = format!("ISBN:{clean}");
        let Some(b) = data.get(&key) else { return vec![] };
        let names = |k: &str| -> String {
            b.get(k)
                .and_then(|a| a.as_array())
                .map(|a| {
                    a.iter()
                        .filter_map(|x| x.get("name").and_then(|n| n.as_str()))
                        .collect::<Vec<_>>()
                        .join(", ")
                })
                .unwrap_or_default()
        };
        let description = b
            .get("notes")
            .and_then(|n| n.as_str())
            .filter(|s| !s.is_empty())
            .map(String::from)
            .or_else(|| b.pointer("/excerpts/0/text").and_then(|t| t.as_str()).map(String::from))
            .unwrap_or_default();
        let cover = ["large", "medium", "small"]
            .iter()
            .find_map(|k| {
                b.pointer(&format!("/cover/{k}")).and_then(|x| x.as_str()).filter(|s| !s.is_empty())
            })
            .unwrap_or("");
        let categories = b
            .get("subjects")
            .and_then(|a| a.as_array())
            .map(|a| {
                a.iter()
                    .take(5)
                    .filter_map(|x| x.get("name").and_then(|n| n.as_str()))
                    .collect::<Vec<_>>()
                    .join(", ")
            })
            .unwrap_or_default();
        vec![json!({
            "isbn": clean,
            "title": s_or_empty(b.get("title")),
            "authors": names("authors"),
            "publisher": names("publishers"),
            "published_date": s_or_empty(b.get("publish_date")),
            "description": description,
            "cover_url": cover,
            "page_count": b.get("number_of_pages").filter(|x| js_truthy(Some(x))).cloned().unwrap_or(Value::Null),
            "language": "",
            "categories": categories,
            "source": "openlibrary",
        })]
    } else {
        let url = format!("{base}/search.json?q={}&limit=10", encode_uri_component(input));
        let Some(data) = fetch_json(http, &url).await else { return vec![] };
        let Some(docs) = data.get("docs").and_then(|d| d.as_array()) else { return vec![] };
        docs.iter()
            .take(10)
            .map(|d| {
                let year = d
                    .get("first_publish_year")
                    .filter(|x| js_truthy(Some(x)))
                    .map(crate::util::js_interp)
                    .unwrap_or_default();
                let cover = d
                    .get("cover_i")
                    .filter(|x| js_truthy(Some(x)))
                    .map(|c| format!("https://covers.openlibrary.org/b/id/{}-L.jpg", crate::util::js_interp(c)))
                    .unwrap_or_default();
                let subjects = d
                    .get("subject")
                    .and_then(|a| a.as_array())
                    .map(|a| a.iter().take(3).filter_map(|x| x.as_str()).collect::<Vec<_>>().join(", "))
                    .unwrap_or_default();
                json!({
                    "isbn": d.pointer("/isbn/0").and_then(|x| x.as_str()).unwrap_or(""),
                    "title": s_or_empty(d.get("title")),
                    "authors": d.get("author_name").and_then(|a| a.as_array()).map(|a| a.iter().filter_map(|x| x.as_str()).collect::<Vec<_>>().join(", ")).unwrap_or_default(),
                    "publisher": d.pointer("/publisher/0").and_then(|x| x.as_str()).unwrap_or(""),
                    "published_date": year,
                    "description": "",
                    "cover_url": cover,
                    "page_count": d.get("number_of_pages_median").filter(|x| js_truthy(Some(x))).cloned().unwrap_or(Value::Null),
                    "language": d.pointer("/language/0").and_then(|x| x.as_str()).unwrap_or(""),
                    "categories": subjects,
                    "source": "openlibrary",
                })
            })
            .collect()
    }
}

#[derive(Debug, Deserialize)]
pub struct BookSearchQuery {
    query: Option<String>,
    isbn: Option<String>,
}

/// `GET /api/books/search/external` —— Google Books 為主、OpenLibrary 補位。
#[utoipa::path(get, path = "/api/books/search/external", tag = "integrations",
    responses((status = 200, description = "書籍外部搜尋(Google Books + OpenLibrary,動態 JSON,第三方 proxy)")))]
pub async fn books_search_external(
    State(state): State<AppState>,
    Query(q): Query<BookSearchQuery>,
) -> Response {
    let query = q.query.filter(|s| !s.is_empty());
    let isbn = q.isbn.filter(|s| !s.is_empty());
    let Some(input) = isbn.clone().or(query) else {
        return (StatusCode::BAD_REQUEST, Json(json!({ "error": "請提供書名或 ISBN" }))).into_response();
    };
    let no_space: String = input.chars().filter(|c| !c.is_whitespace()).collect();
    static ISBN_RE: std::sync::LazyLock<regex::Regex> =
        std::sync::LazyLock::new(|| regex::Regex::new(r"^[\d-]{10,17}$").expect("字面 regex"));
    let is_isbn = ISBN_RE.is_match(&no_space);
    let clean_isbn: String = input.chars().filter(|c| *c != '-' && !c.is_whitespace()).collect();
    // ⚠ 不要加 `isbn:` 前綴。2026-10 實測 Google Books 的 `isbn:` 運算子對任何書都回 0 筆
    //   (連 Zero to One 的 9780804139298 都是),直接查數字反而找得到。代價是數字也可能出現在
    //   別本書的內文裡,所以下面把 ISBN 完全吻合的那幾本排到最前面。
    let search_query = if is_isbn { clean_isbn.clone() } else { input.clone() };

    // warnings:上游壞掉時告訴後台「是來源的問題」,而不是讓它看起來像「這本書不存在」。
    let mut warnings: Vec<String> = Vec::new();
    let mut books = match search_google_books(&state.http, &state.external.google_books, &search_query).await
    {
        Ok(mut b) => {
            if is_isbn {
                // 穩定排序:吻合的在前,其餘維持 Google 的相關度順序
                b.sort_by_key(|x| x.get("isbn").and_then(Value::as_str) != Some(clean_isbn.as_str()));
            }
            b
        }
        Err(e) => {
            tracing::warn!(error = %e, "books search: Google Books 失敗,改查 OpenLibrary");
            warnings.push(e);
            vec![]
        }
    };
    // 國圖新書書目(本地索引,見 handlers/tw_isbn.rs):台灣出版的書 Google 多半沒有或版本不對
    let ncl: Vec<Value> = if is_isbn {
        crate::handlers::tw_isbn::lookup_isbn(&state.pool, &clean_isbn)
            .await
            .iter()
            .map(crate::handlers::tw_isbn::to_search_json)
            .collect()
    } else {
        crate::handlers::tw_isbn::search(&state.pool, &input, 5)
            .await
            .iter()
            .map(crate::handlers::tw_isbn::to_search_json)
            .collect()
    };
    let ncl_first = is_isbn || input.chars().any(is_cjk);
    books = merge_with_ncl(ncl, books, ncl_first);
    if books.is_empty() {
        books = search_open_library(&state.http, &state.external.openlibrary, &input, is_isbn).await;
    }
    Json(json!({ "message": "success", "books": books, "warnings": warnings })).into_response()
}

const fn is_cjk(c: char) -> bool {
    matches!(c, '\u{3400}'..='\u{9fff}' | '\u{f900}'..='\u{faff}')
}

/// 把國圖的結果與 Google 的結果合在一起。
///
/// - 同一個 ISBN 兩邊都有:留國圖那筆(台灣版的書名、出版社、出版日才是對的),
///   但國圖沒有封面與簡介——從 Google 那筆補上,Google 那筆就不再重複列出。
/// - `ncl_first`:用 ISBN 查、或關鍵字有中文時,國圖的排前面;英文關鍵字多半是外文書,Google 在前。
fn merge_with_ncl(mut ncl: Vec<Value>, google: Vec<Value>, ncl_first: bool) -> Vec<Value> {
    let mut rest = Vec::with_capacity(google.len());
    for g in google {
        let gi = g.get("isbn").and_then(Value::as_str).unwrap_or("");
        let twin = (!gi.is_empty())
            .then(|| ncl.iter_mut().find(|n| n.get("isbn").and_then(Value::as_str) == Some(gi)))
            .flatten();
        match twin {
            Some(n) => {
                for key in ["cover_url", "description", "language"] {
                    let empty = n.get(key).and_then(Value::as_str).is_none_or(str::is_empty);
                    if empty && let Some(v) = g.get(key) {
                        n[key] = v.clone();
                    }
                }
                if n.get("page_count").is_none_or(Value::is_null) {
                    n["page_count"] = g.get("page_count").cloned().unwrap_or(Value::Null);
                }
            }
            None => rest.push(g),
        }
    }
    if ncl_first {
        ncl.extend(rest);
        ncl
    } else {
        rest.extend(ncl);
        rest
    }
}

// ── steam/profile(SWR 快取 + miniprofile 客製解析)───────────────────────

const STEAM_PROFILE_REFRESH_AFTER: i64 = 30 * 60 * 1000;
const STEAM_PROFILE_RETRY_BACKOFF: i64 = 5 * 60 * 1000;

/// _fetchHttps 等價(瀏覽器 UA;json 版套 number 正規化)。
async fn steam_fetch_json(http: &reqwest::Client, url: &str) -> Result<Value, String> {
    let body = steam_fetch_text(http, url).await?;
    let mut v: Value = serde_json::from_str(&body).map_err(|e| e.to_string())?;
    crate::util::js_normalize_numbers(&mut v);
    Ok(v)
}

async fn steam_fetch_text(http: &reqwest::Client, url: &str) -> Result<String, String> {
    http.get(url)
        .header(
            "User-Agent",
            "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0 Safari/537.36",
        )
        .header("Accept-Language", "en-US,en;q=0.9")
        .send()
        .await
        .map_err(|e| e.to_string())?
        .text()
        .await
        .map_err(|e| e.to_string())
}

/// _parseMiniProfile 等價(4 條 regex;lookahead `(?!_frame)` 因後接 `\s+` 恆真,等價移除)。
fn parse_mini_profile(html: &str) -> SteamCustomization {
    let mut out = SteamCustomization::default();
    if html.is_empty() {
        return out;
    }
    let re = |p: &str| regex::RegexBuilder::new(p).case_insensitive(true).build().ok();
    if let Some(block) = re(r#"<video class=["']miniprofile_nameplate[^>]*>((?s:.*?))</video>"#)
        .and_then(|r| r.captures(html).map(|c| c.get(1).map(|m| m.as_str().to_string())))
        .flatten()
    {
        out.nameplate_webm = re(r#"src=["']([^"']+\.webm)["']"#)
            .and_then(|r| r.captures(&block).and_then(|c| c.get(1).map(|m| m.as_str().to_string())));
        out.nameplate_mp4 = re(r#"src=["']([^"']+\.mp4)["']"#)
            .and_then(|r| r.captures(&block).and_then(|c| c.get(1).map(|m| m.as_str().to_string())));
    }
    out.avatar_frame = re(r#"playersection_avatar_frame[^>]*>\s*<img\s+src=["']([^"']+)["']"#)
        .and_then(|r| r.captures(html).and_then(|c| c.get(1).map(|m| m.as_str().to_string())));
    out.animated_avatar = re(r#"playersection_avatar\s+[^"']*["'][^>]*>\s*<img\s+src=["']([^"']+)["']"#)
        .and_then(|r| r.captures(html).and_then(|c| c.get(1).map(|m| m.as_str().to_string())));
    if let Some(c) = re(r#"<div class=["']miniprofile_featuredcontainer["']>\s*<img src=["']([^"']+)["'][^>]*class=["']badge_icon["']>\s*<div class=["']description["']>\s*<div class=["']name["']>([^<]+)</div>\s*<div class=["']xp["']>([^<]+)</div>"#)
        .and_then(|r| r.captures(html))
    {
        out.featured_badge = Some(SteamFeaturedBadge {
            icon: c.get(1).map_or("", |m| m.as_str()).to_string(),
            name: c.get(2).map_or("", |m| m.as_str().trim()).to_string(),
            xp: c.get(3).map_or("", |m| m.as_str().trim()).to_string(),
        });
    }
    out
}

/// miniprofile 頁面刮下來的展示徽章(三個都是 regex 捕獲組,必為字串)。
#[derive(Debug, Clone, Serialize, specta::Type, utoipa::ToSchema)]
pub struct SteamFeaturedBadge {
    pub icon: String,
    pub name: String,
    /// Steam 頁面上是 "1,234 XP" 這種已格式化的字串,不是數字
    pub xp: String,
}

/// miniprofile 客製(動態頭像 / 頭像框 / 名牌動畫)。抓不到的就是 None。
#[derive(Debug, Clone, Default, Serialize, specta::Type, utoipa::ToSchema)]
pub struct SteamCustomization {
    #[serde(rename = "animatedAvatar")]
    pub animated_avatar: Option<String>,
    #[serde(rename = "avatarFrame")]
    pub avatar_frame: Option<String>,
    #[serde(rename = "nameplateWebm")]
    pub nameplate_webm: Option<String>,
    #[serde(rename = "nameplateMp4")]
    pub nameplate_mp4: Option<String>,
    #[serde(rename = "featuredBadge")]
    pub featured_badge: Option<SteamFeaturedBadge>,
}

/// `/api/steam/profile` 的資料本體(=快取內容)。
#[derive(Debug, Clone, Serialize, specta::Type, utoipa::ToSchema)]
pub struct SteamProfile {
    pub player: SteamPlayer,
    #[specta(type = specta_typescript::Number)]
    pub level: i64,
    #[specta(type = specta_typescript::Number)]
    pub xp: i64,
    #[serde(rename = "xpToNext")]
    #[specta(type = specta_typescript::Number)]
    pub xp_to_next: i64,
    #[serde(rename = "badgeCount")]
    #[specta(type = specta_typescript::Number)]
    pub badge_count: i64,
    pub customization: SteamCustomization,
    #[serde(rename = "profileUrl")]
    pub profile_url: String,
}

/// `GET /api/steam/profile`
///
/// `_cachedAt` 是伺服器記帳(SWR 的抓取時間),不是 profile 的一部分——所以它在
/// 回應型別上,而快取只存 profile 本體(同 watch/now 把 expiresAt 移出 wire type)。
#[derive(Debug, Serialize, specta::Type, utoipa::ToSchema)]
pub struct SteamProfileResponse {
    #[serde(flatten)]
    pub profile: SteamProfile,
    /// epoch ms
    #[serde(rename = "_cachedAt")]
    #[specta(type = specta_typescript::Number)]
    pub cached_at: i64,
}

/// _refreshSteamProfile 等價(呼叫端負責 inflight dedup)。成功寫快取、失敗只更新 lastTriedAt。
async fn refresh_steam_profile(state: &AppState, key: &str, id: &str) -> Result<SteamProfile, String> {
    let account_id = if let Ok(n) = id.parse::<i64>() {
        (n - 76_561_197_960_265_728i64).to_string()
    } else {
        // invalid STEAM_ID:同樣走失敗路徑
        if let Some(c) = state.steam.cache.lock().as_mut() {
            c.last_tried_at = now_ms();
        }
        return Err("invalid STEAM_ID".to_string());
    };
    let u1 =
        format!("{}/ISteamUser/GetPlayerSummaries/v0002/?key={key}&steamids={id}", state.external.steam_api);
    let u2 = format!("{}/IPlayerService/GetSteamLevel/v1/?key={key}&steamid={id}", state.external.steam_api);
    let u3 = format!("{}/IPlayerService/GetBadges/v1/?key={key}&steamid={id}", state.external.steam_api);
    let u4 = format!("{}/miniprofile/{account_id}", state.external.steam_community);
    let (player, level, badges, mini_html) = tokio::join!(
        steam_fetch_json(&state.http, &u1),
        steam_fetch_json(&state.http, &u2),
        steam_fetch_json(&state.http, &u3),
        steam_fetch_text(&state.http, &u4)
    );
    let result: Result<SteamProfile, String> = (|| {
        let player = player?;
        let level = level?;
        let badges = badges.unwrap_or(Value::Null);
        let player_obj = player.pointer("/response/players/0");
        let lvl = level.pointer("/response/player_level").and_then(serde_json::Value::as_i64);
        let (Some(player_obj), Some(level)) = (player_obj, lvl) else {
            return Err("incomplete response from Steam".to_string());
        };
        let badge_count =
            badges.pointer("/response/badges").and_then(|b| b.as_array()).map_or(0, std::vec::Vec::len);
        Ok(SteamProfile {
            player: steam_player_from(player_obj),
            level,
            xp: badges.pointer("/response/player_xp").and_then(serde_json::Value::as_i64).unwrap_or(0),
            xp_to_next: badges
                .pointer("/response/player_xp_needed_to_level_up")
                .and_then(serde_json::Value::as_i64)
                .unwrap_or(0),
            badge_count: i64::try_from(badge_count).unwrap_or(i64::MAX),
            customization: parse_mini_profile(&mini_html.unwrap_or_default()),
            profile_url: format!("https://steamcommunity.com/profiles/{id}"),
        })
    })();
    match result {
        Ok(data) => {
            let now = now_ms();
            *state.steam.cache.lock() = Some(crate::state::SteamProfileCache {
                data: data.clone(),
                fetched_at: now,
                last_tried_at: now,
            });
            Ok(data)
        }
        Err(e) => {
            if let Some(c) = state.steam.cache.lock().as_mut() {
                c.last_tried_at = now_ms();
            }
            Err(e)
        }
    }
}

/// `GET /api/steam/profile` —— stale-while-revalidate:有快取直接回、過期背景重抓;
/// 首抓需等待(tokio Mutex dedup 併發重抓)。
#[utoipa::path(get, path = "/api/steam/profile", tag = "integrations",
    responses((status = 200, body = SteamProfileResponse),
              (status = 503, description = "首抓失敗且無快取")))]
pub async fn steam_profile(State(state): State<AppState>) -> Response {
    let Some((key, id)) = steam_env() else {
        return (StatusCode::INTERNAL_SERVER_ERROR, Json(json!({ "error": STEAM_UNCONFIGURED })))
            .into_response();
    };
    let now = now_ms();
    let cached = state.steam.cache.lock().clone();
    if let Some(c) = cached {
        let since_fetch = now - c.fetched_at;
        let since_try = now - c.last_tried_at;
        if since_fetch >= STEAM_PROFILE_REFRESH_AFTER && since_try >= STEAM_PROFILE_RETRY_BACKOFF {
            // 背景重抓(不 await;try_lock dedup)
            let st = state.clone();
            tokio::spawn(async move {
                if let Ok(_g) = st.steam.refresh_lock.try_lock() {
                    let _ = refresh_steam_profile(&st, &key, &id).await;
                }
            });
        }
        return Json(SteamProfileResponse { profile: c.data, cached_at: c.fetched_at }).into_response();
    }
    // 首抓:持鎖去重;等鎖期間別人可能已抓好 → 再查一次快取
    let _g = state.steam.refresh_lock.lock().await;
    let cached = state.steam.cache.lock().clone();
    if let Some(c) = cached {
        return Json(SteamProfileResponse { profile: c.data, cached_at: c.fetched_at }).into_response();
    }
    match refresh_steam_profile(&state, &key, &id).await {
        Ok(profile) => {
            let cached_at = state.steam.cache.lock().as_ref().map_or_else(now_ms, |c| c.fetched_at);
            Json(SteamProfileResponse { profile, cached_at }).into_response()
        }
        Err(e) => (
            StatusCode::SERVICE_UNAVAILABLE,
            Json(json!({ "error": "steam fetch failed, no cache yet", "message": e })),
        )
            .into_response(),
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// STEAM_API_KEY / STEAM_ID 是 process 全域的。nextest 一個測試一個行程不會撞,
    /// 但 `cargo test`(cargo-mutants 預設用它)是同行程平行跑 → 需要串起來。
    static STEAM_ENV_LOCK: std::sync::LazyLock<tokio::sync::Mutex<()>> =
        std::sync::LazyLock::new(|| tokio::sync::Mutex::new(()));

    fn fake_profile(persona: &str) -> SteamProfile {
        SteamProfile {
            player: SteamPlayer {
                personaname: Some(persona.to_string()),
                avatarfull: None,
                profileurl: None,
                personastate: Some(1),
                gameid: None,
            },
            level: 42,
            xp: 100,
            xp_to_next: 200,
            badge_count: 3,
            customization: SteamCustomization::default(),
            profile_url: "https://steamcommunity.com/profiles/1".to_string(),
        }
    }

    /// **stampede**:64 個請求同時打「首抓」路徑。
    ///
    /// 契約是「同一時間只有一個去打上游,其餘的等;等到之後**重查快取**」——
    /// `steam_profile` 裡拿到鎖之後的那次 `state.steam.cache.lock()` 就是這個 double-check。
    ///
    /// 這個測試把那條路徑逼出來的方式是:測試自己先佔住 `refresh_lock`,讓 64 個
    /// handler 全部卡在鎖上,然後在牠們排隊期間把快取填好、再放開鎖。
    /// 每一個醒來的人都應該讀到快取回 200。
    ///
    /// 把 double-check 拿掉的話,這 64 個會各自去打 api.steampowered.com(帶著
    /// 測試用的假 key)→ 全部 503,測試就紅了。也就是說它擋的是真的會發生的退化,
    /// 不是「有呼叫到 lock()」這種形式檢查。
    #[tokio::test]
    async fn steam_profile_stampede_rechecks_cache_instead_of_all_refetching() {
        let _env = STEAM_ENV_LOCK.lock().await;
        // SAFETY: 同上,靠 STEAM_ENV_LOCK 串行化;測試結束前還原。
        unsafe {
            std::env::set_var("STEAM_API_KEY", "test-key-never-actually-used");
            std::env::set_var("STEAM_ID", "76561197960265729");
        }
        let state = crate::state::test_state().await;

        // 佔住鎖:後面每個 handler 走到首抓路徑都會停在這裡
        let guard = state.steam.refresh_lock.lock().await;

        let mut tasks = tokio::task::JoinSet::new();
        for _ in 0..64 {
            let st = state.clone();
            tasks.spawn(async move { steam_profile(axum::extract::State(st)).await });
        }
        // 讓那 64 個 task 有機會被排程、走到鎖前面
        for _ in 0..8 {
            tokio::task::yield_now().await;
        }

        // 模擬「持鎖的那一個抓好了」。fetched_at 用當下時間——放舊的會讓後到的請求
        // 判定快取過期而 spawn 背景重抓,那才是真的會打網路。
        let now = now_ms();
        *state.steam.cache.lock() = Some(crate::state::SteamProfileCache {
            data: fake_profile("stampede-sentinel"),
            fetched_at: now,
            last_tried_at: now,
        });
        drop(guard);

        let mut served = 0;
        while let Some(joined) = tasks.join_next().await {
            let resp = joined.expect("handler task panicked");
            assert_eq!(
                resp.status(),
                StatusCode::OK,
                "有人沒重查快取,跑去打上游了(503 = 假 key 被真的送出去)"
            );
            let bytes =
                http_body_util::BodyExt::collect(resp.into_body()).await.expect("collect body").to_bytes();
            let v: Value = serde_json::from_slice(&bytes).expect("response is JSON");
            assert_eq!(v["player"]["personaname"], "stampede-sentinel", "回的不是快取那份");
            assert_eq!(v["_cachedAt"], json!(now));
            served += 1;
        }
        assert_eq!(served, 64);

        // SAFETY: 見上。
        unsafe {
            std::env::remove_var("STEAM_API_KEY");
            std::env::remove_var("STEAM_ID");
        }
    }

    /// 沒設 key/id 時要在碰鎖之前就回 500——否則未配置的部署會把所有請求排到鎖上。
    #[tokio::test]
    async fn steam_profile_without_env_fails_before_taking_the_lock() {
        let _env = STEAM_ENV_LOCK.lock().await;
        // SAFETY: 見上。
        unsafe {
            std::env::remove_var("STEAM_API_KEY");
            std::env::remove_var("STEAM_ID");
        }
        let state = crate::state::test_state().await;

        // 鎖被佔著;若 handler 會去搶鎖,這個呼叫就會卡住而不是回 500
        let _guard = state.steam.refresh_lock.lock().await;
        let resp = tokio::time::timeout(
            std::time::Duration::from_secs(5),
            steam_profile(axum::extract::State(state.clone())),
        )
        .await
        .expect("未配置時不該去等鎖");
        assert_eq!(resp.status(), StatusCode::INTERNAL_SERVER_ERROR);
    }

    /// 塑形這一步是這批改動唯一會出錯的地方(抓取本身走網路,測不到)。
    /// 樣本照 GitHub `/users/:u/events/public` 的實際形狀寫。
    #[test]
    fn github_event_keeps_push_fields_and_drops_shaless_commits() {
        let ev = json!({
            "id": "12345", "type": "PushEvent", "created_at": "2026-07-28T10:00:00Z",
            "repo": { "id": 1, "name": "timo9378/sora-to-ki" },
            "actor": { "login": "timo9378" },
            "payload": {
                "before": "aaa", "head": "bbb", "size": 2,
                "commits": [
                    { "sha": "c1", "message": "feat: 一", "author": { "name": "T", "email": "t@e" } },
                    { "message": "沒有 sha,不該收" },
                    { "sha": "c2", "message": "feat: 二" }
                ]
            }
        });
        let e = github_event_from(&ev).expect("應該收得下");
        assert_eq!(e.id, "12345");
        assert_eq!(e.kind, "PushEvent");
        assert_eq!(e.repo.name, "timo9378/sora-to-ki");
        assert_eq!(e.payload.size, Some(2));
        assert_eq!(e.payload.commits.len(), 2, "缺 sha 的那筆要被丟掉");
        assert_eq!(e.payload.commits[0].sha, "c1");
        assert_eq!(e.payload.commits[0].author.as_ref().unwrap().name.as_deref(), Some("T"));
        assert!(e.payload.commits[1].author.is_none());
    }

    #[test]
    fn github_event_without_repo_is_dropped() {
        let ev = json!({ "id": "1", "type": "WatchEvent", "created_at": "2026-07-28T10:00:00Z" });
        assert!(github_event_from(&ev).is_none());
    }

    /// 非 PushEvent 仍收得下(前端自己 filter),payload 就是空 commits。
    #[test]
    fn github_non_push_event_has_empty_payload() {
        let ev = json!({
            "id": "2", "type": "WatchEvent", "created_at": "2026-07-28T10:00:00Z",
            "repo": { "name": "a/b" }, "payload": { "action": "started" }
        });
        let e = github_event_from(&ev).unwrap();
        assert!(e.payload.commits.is_empty());
        assert_eq!(e.payload.before, None);
    }

    #[test]
    fn steam_games_unwraps_response_envelope() {
        let v = json!({ "response": { "total_count": 2, "games": [
            { "appid": 730, "name": "CS2", "playtime_2weeks": 120, "playtime_forever": 9999 },
            { "appid": 440, "name": "TF2" }
        ] } });
        let games = steam_games_from(&v);
        assert_eq!(games.len(), 2);
        assert_eq!(games[0].appid, Some(730));
        assert_eq!(games[0].playtime_2weeks, Some(120));
        assert_eq!(games[1].playtime_2weeks, None, "沒玩過就是 None,不是 0");
    }

    #[test]
    fn steam_games_on_missing_envelope_is_empty_not_panic() {
        assert!(steam_games_from(&json!({ "response": {} })).is_empty());
        assert!(steam_games_from(&json!({})).is_empty());
    }

    #[test]
    fn steam_player_gameid_stays_string() {
        let p = json!({
            "personaname": "koi", "avatarfull": "https://a/f.jpg",
            "profileurl": "https://s/p/1", "personastate": 1, "gameid": "730"
        });
        let sp = steam_player_from(&p);
        assert_eq!(sp.gameid.as_deref(), Some("730"), "Steam 這欄是字串不是數字");
        assert_eq!(sp.personastate, Some(1));
    }

    #[test]
    fn wakatime_stats_skips_entries_without_name() {
        let v = json!([
            { "name": "Rust", "text": "3 hrs", "percent": 62.5 },
            { "text": "沒名字,不該收", "percent": 10.0 },
            { "name": "TypeScript" }
        ]);
        let stats = waka_stats_from(&v);
        assert_eq!(stats.len(), 2);
        assert_eq!(stats[0].name, "Rust");
        assert!((stats[0].percent - 62.5).abs() < f64::EPSILON);
        assert_eq!(stats[1].text, "", "缺 text 退成空字串而不是整筆丟掉");
    }

    // ── 打 mock 上游的整合測試 ────────────────────────────────────────────
    //
    // 這一整組在 `state::ExternalUrls` 之前是**寫不出來**的:上游位址寫死在字串裡,
    // 任何 mock 都攔不到,所以 thirdparty.rs 2248 個 region 有八成從來沒被執行過。
    //
    // 驗的是「上游回什麼 → 我們吐什麼」這層轉換。那正是最容易在改動時默默壞掉、
    // 而且壞了只有讀者會看到的地方(前端拿到形狀不符的 JSON 就是空白區塊)。

    use crate::state::ExternalUrls;
    use wiremock::matchers::{method, path, query_param};
    use wiremock::{Mock, MockServer, ResponseTemplate};

    /// 建一個 state,並把全部外部位址指到這台 mock。
    async fn state_with_mock(server: &MockServer) -> AppState {
        let mut st = crate::state::test_state().await;
        st.external = std::sync::Arc::new(ExternalUrls::all_pointing_at(&server.uri()));
        st
    }

    async fn body_of(resp: Response) -> Value {
        let bytes = http_body_util::BodyExt::collect(resp.into_body()).await.expect("collect").to_bytes();
        serde_json::from_slice(&bytes).expect("回應應該是 JSON")
    }

    /// GitHub 的錯誤物件是 `{message, documentation_url}`,沒有 `error` 欄位。
    /// 這支端點的存在理由之一就是把 message 收進 `error`——在此之前 404 / rate limit
    /// 會變成「所有欄位都是 null 的使用者物件」悄悄穿過去,前端檢查 `.error` 檢查不到。
    #[tokio::test]
    async fn github_user_surfaces_upstream_error_message() {
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/github/users/ghost"))
            .respond_with(ResponseTemplate::new(404).set_body_json(json!({
                "message": "Not Found",
                "documentation_url": "https://docs.github.com/rest"
            })))
            .mount(&server)
            .await;

        let st = state_with_mock(&server).await;
        let v =
            body_of(github_user(axum::extract::State(st), axum::extract::Path("ghost".into())).await).await;
        assert_eq!(v["error"], "Not Found", "GitHub 的 message 要被收進 error 欄位");
        assert!(v["login"].is_null(), "失敗時不該有半個看起來正常的欄位");
    }

    /// 上游回的**根本不是 JSON**(Cloudflare 擋頁、502 的 HTML…)走的是另一條分支:
    /// 前一條測的是「合法 JSON 但內容是錯誤物件」。兩條都要有訊息,
    /// 否則前端拿到的是一個所有欄位都是 null 又沒有 error 的使用者物件。
    #[tokio::test]
    async fn github_user_回應不是_json_時也要有錯誤訊息() {
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/github/users/u"))
            .respond_with(ResponseTemplate::new(200).set_body_string("<html>502 Bad Gateway</html>"))
            .mount(&server)
            .await;
        let st = state_with_mock(&server).await;
        let resp = github_user(axum::extract::State(st), axum::extract::Path("u".into())).await;
        assert_eq!(resp.status(), StatusCode::INTERNAL_SERVER_ERROR);
        let v = body_of(resp).await;
        assert_eq!(v["error"], GH_PARSE_ERR);
        assert!(v["login"].is_null());
    }

    #[tokio::test]
    async fn steam_player_回應不是_json_時也要有錯誤訊息() {
        let _env = STEAM_ENV_LOCK.lock().await;
        // SAFETY: 靠 STEAM_ENV_LOCK 串行化。
        unsafe {
            std::env::set_var("STEAM_API_KEY", "k");
            std::env::set_var("STEAM_ID", "1");
        }
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/steam-api/ISteamUser/GetPlayerSummaries/v0002/"))
            .respond_with(ResponseTemplate::new(200).set_body_string("not json at all"))
            .mount(&server)
            .await;
        let st = state_with_mock(&server).await;
        let resp = steam_player(axum::extract::State(st)).await;
        assert_eq!(resp.status(), StatusCode::INTERNAL_SERVER_ERROR);
        assert_eq!(body_of(resp).await["error"], STEAM_PARSE_ERR);

        // SAFETY: 見上。
        unsafe {
            std::env::remove_var("STEAM_API_KEY");
            std::env::remove_var("STEAM_ID");
        }
    }

    /// 正常路徑:只回我們宣告的那五欄,上游多給的欄位不轉發。
    #[tokio::test]
    async fn github_user_returns_only_the_declared_fields() {
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/github/users/timo9378"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "login": "timo9378",
                "name": "Koi",
                "avatar_url": "https://avatars.githubusercontent.com/u/1",
                "html_url": "https://github.com/timo9378",
                "public_repos": 42,
                // 上游還會給幾十個欄位,這裡放一個代表:不該出現在回應裡
                "gravatar_id": "should-not-be-forwarded"
            })))
            .mount(&server)
            .await;

        let st = state_with_mock(&server).await;
        let v = body_of(github_user(axum::extract::State(st), axum::extract::Path("timo9378".into())).await)
            .await;
        assert_eq!(v["login"], "timo9378");
        assert_eq!(v["public_repos"], 42);
        assert!(v["error"].is_null());
        assert!(v.get("gravatar_id").is_none(), "上游多給的欄位不該原樣轉發出去");
    }

    /// steam/player:上游把玩家包在 `{response:{players:[…]}}` 裡,這支要把那層挖掉。
    /// 挖錯層前端就是拿到 undefined,而且不會有任何錯誤訊息。
    #[tokio::test]
    async fn steam_player_unwraps_the_response_envelope() {
        let _env = STEAM_ENV_LOCK.lock().await;
        // SAFETY: 靠 STEAM_ENV_LOCK 串行化;結束前還原。
        unsafe {
            std::env::set_var("STEAM_API_KEY", "k");
            std::env::set_var("STEAM_ID", "76561197960265729");
        }
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/steam-api/ISteamUser/GetPlayerSummaries/v0002/"))
            .and(query_param("key", "k"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "response": { "players": [{
                    "personaname": "koi",
                    "avatarfull": "https://avatars.steamstatic.com/x.jpg",
                    "personastate": 1,
                    "gameid": "730"
                }]}
            })))
            .mount(&server)
            .await;

        let st = state_with_mock(&server).await;
        let v = body_of(steam_player(axum::extract::State(st)).await).await;
        assert_eq!(v["player"]["personaname"], "koi");
        // gameid 上游回的是**字串**不是數字,轉成數字會讓「在遊戲中」的判斷壞掉
        assert_eq!(v["player"]["gameid"], "730");
        assert!(v["error"].is_null());

        // SAFETY: 見上。
        unsafe {
            std::env::remove_var("STEAM_API_KEY");
            std::env::remove_var("STEAM_ID");
        }
    }

    /// 上游回了但形狀不對(players 是空陣列)時不該 panic,也不該回一個假的玩家。
    #[tokio::test]
    async fn steam_player_handles_empty_players_without_panicking() {
        let _env = STEAM_ENV_LOCK.lock().await;
        // SAFETY: 見上。
        unsafe {
            std::env::set_var("STEAM_API_KEY", "k");
            std::env::set_var("STEAM_ID", "76561197960265729");
        }
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/steam-api/ISteamUser/GetPlayerSummaries/v0002/"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({ "response": { "players": [] } })))
            .mount(&server)
            .await;

        let st = state_with_mock(&server).await;
        let v = body_of(steam_player(axum::extract::State(st)).await).await;
        assert!(v["player"].is_null(), "沒有玩家就該是 null,不是一個空殼物件");

        // SAFETY: 見上。
        unsafe {
            std::env::remove_var("STEAM_API_KEY");
            std::env::remove_var("STEAM_ID");
        }
    }

    // ── WakaTime ──────────────────────────────────────────────────────────
    //
    // 這一整塊在補之前是 0 覆蓋。它全部是「重新塑形上游回應」的程式:塑錯了不會
    // crash,前端只會拿到 undefined 然後畫出一片空白,而且沒有任何錯誤訊息。

    /// WAKATIME_API_KEY 同樣是 process 全域,理由同 STEAM_ENV_LOCK。
    static WAKA_ENV_LOCK: std::sync::LazyLock<tokio::sync::Mutex<()>> =
        std::sync::LazyLock::new(|| tokio::sync::Mutex::new(()));

    /// 設好 key、跑完自動還原。回傳的 guard 一 drop 就清掉。
    // 這個欄位不會被讀,只是把鎖握到 guard 被 drop 為止(env 是 process 全域的)。
    struct WakaKey(#[allow(dead_code)] tokio::sync::MutexGuard<'static, ()>);
    impl Drop for WakaKey {
        fn drop(&mut self) {
            // SAFETY: 靠 WAKA_ENV_LOCK 串行化(guard 還握在手上)。
            unsafe { std::env::remove_var("WAKATIME_API_KEY") };
        }
    }
    async fn with_waka_key() -> WakaKey {
        let g = WAKA_ENV_LOCK.lock().await;
        // SAFETY: 同上。
        unsafe { std::env::set_var("WAKATIME_API_KEY", "test-waka-key") };
        WakaKey(g)
    }

    #[test]
    fn waka_auth_是_base64_的_basic() {
        // 打錯就是每一次請求都 401,而 handler 會把它包成 error 欄位回 200 給前端——
        // 看起來像「今天沒寫程式」而不是「認證壞了」。
        assert_eq!(waka_auth("abc"), "Basic YWJj");
        assert_eq!(waka_auth(""), "Basic ");
    }

    // 這裡的 percent 是從 JSON 原樣讀進來、沒有經過任何運算就寫進欄位,
    // 驗的就是「原封不動」,所以要的正是精確相等而不是 epsilon 比較。
    #[allow(clippy::float_cmp, reason = "驗的是 JSON 原值有沒有被改動,不是計算結果")]
    #[test]
    fn waka_stats_from_跳過沒有名字的列並補預設值() {
        let v = json!([
            { "name": "Rust", "text": "10 hrs", "percent": 62.5 },
            { "name": "TypeScript" },                      // 缺 text/percent → 補預設
            { "text": "沒有名字", "percent": 100 },          // 缺 name → 整列不收
        ]);
        let out = waka_stats_from(&v);
        assert_eq!(out.len(), 2, "缺 name 的那列要被丟掉");
        assert_eq!(out[0].name, "Rust");
        assert_eq!(out[0].percent, 62.5);
        assert_eq!(out[1].name, "TypeScript");
        assert_eq!(out[1].text, "", "缺 text 補空字串,不是 null");
        assert_eq!(out[1].percent, 0.0);
        // 不是陣列時回空陣列而不是 panic——前端直接 .map,給 null 會炸
        assert!(waka_stats_from(&Value::Null).is_empty());
        assert!(waka_stats_from(&json!({ "languages": [] })).is_empty());
    }

    #[test]
    fn waka_err_parts_把上游的_body_轉成_details_字串() {
        let (st, err, det) = waka_err_parts("kind", (StatusCode::UNAUTHORIZED, Value::from("Unauthorized")));
        assert_eq!(st, StatusCode::UNAUTHORIZED, "上游的狀態碼要原樣帶出來");
        assert_eq!(err.as_deref(), Some("kind"));
        assert_eq!(det.as_deref(), Some("Unauthorized"), "字串就原樣放,不要再包一層引號");

        let (_, _, det) = waka_err_parts("kind", (StatusCode::BAD_GATEWAY, json!({ "error": "nope" })));
        assert_eq!(det.as_deref(), Some(r#"{"error":"nope"}"#), "物件轉成 JSON 字串");

        let (_, _, det) = waka_err_parts("kind", (StatusCode::BAD_GATEWAY, Value::Null));
        assert_eq!(det, None, "沒有 body 就不要生一個 \"null\" 字串出來");
    }

    #[tokio::test]
    async fn wakatime_today_把只有一個元素的_data_陣列攤平並算出實際編碼區間() {
        let _key = with_waka_key().await;
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/wakatime/api/v1/users/current/summaries"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "data": [{ "grand_total": { "text": "3 hrs 12 mins", "total_seconds": 11520.0 } }],
                "start": "2026-08-02T00:00:00Z",
                "end": "2026-08-02T23:59:59Z",
            })))
            .mount(&server)
            .await;
        // 刻意亂序:actualCodingTime 要取 min(time) 與 max(time+duration),不是第一筆與最後一筆
        Mock::given(method("GET"))
            .and(path("/wakatime/api/v1/users/current/durations"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "data": [
                    { "time": 1_770_000_600.0, "duration": 600.0 },
                    { "time": 1_770_000_000.0, "duration": 120.0 },
                ]
            })))
            .mount(&server)
            .await;

        let st = state_with_mock(&server).await;
        let v = body_of(wakatime_today(axum::extract::State(st)).await).await;

        // 查的日期必須真的是「今天」。這條看起來瑣碎,但 today_utc 回空字串或亂值時
        // WakaTime 會回一片空白,而畫面上就是「今天沒寫程式」——沒有任何錯誤。
        let today = crate::util::iso_from_millis(crate::util::now_ms())[..10].to_string();
        let reqs = server.received_requests().await.unwrap();
        let summ = reqs.iter().find(|r| r.url.path().ends_with("/summaries")).unwrap();
        let qp = |r: &wiremock::Request, k: &str| {
            r.url.query_pairs().find(|(a, _)| a == k).map(|(_, v)| v.into_owned())
        };
        assert_eq!(qp(summ, "start").as_deref(), Some(today.as_str()), "start 要是今天");
        assert_eq!(qp(summ, "end").as_deref(), Some(today.as_str()), "end 也是今天(單日查詢)");
        let dur = reqs.iter().find(|r| r.url.path().ends_with("/durations")).unwrap();
        assert_eq!(qp(dur, "date").as_deref(), Some(today.as_str()));

        assert_eq!(v["grand_total"]["text"], "3 hrs 12 mins", "data[0] 那層要被攤掉");
        assert_eq!(v["grand_total"]["total_seconds"], 11520);
        assert_eq!(v["start"], "2026-08-02T00:00:00Z");
        assert_eq!(v["actualCodingTime"]["hasData"], true);
        assert_eq!(
            v["actualCodingTime"]["start"],
            crate::util::iso_from_millis(1_770_000_000_000),
            "start 取的是最小的 time,不是陣列第一筆"
        );
        assert_eq!(
            v["actualCodingTime"]["end"],
            crate::util::iso_from_millis(1_770_001_200_000),
            "end 取的是最大的 time+duration"
        );
        assert!(v["error"].is_null());
    }

    #[tokio::test]
    async fn wakatime_today_沒有_durations_時_hasdata_是_false() {
        let _key = with_waka_key().await;
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/wakatime/api/v1/users/current/summaries"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({ "data": [] })))
            .mount(&server)
            .await;
        Mock::given(method("GET"))
            .and(path("/wakatime/api/v1/users/current/durations"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({ "data": [] })))
            .mount(&server)
            .await;

        let st = state_with_mock(&server).await;
        let v = body_of(wakatime_today(axum::extract::State(st)).await).await;
        assert_eq!(v["actualCodingTime"]["hasData"], false);
        assert!(v["actualCodingTime"]["start"].is_null(), "沒資料時不該生出 1970-01-01");
        assert!(v["grand_total"].is_null(), "data 是空陣列 → 沒有 grand_total");
    }

    #[tokio::test]
    async fn wakatime_today_把上游的錯誤狀態碼與內容帶出來() {
        let _key = with_waka_key().await;
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/wakatime/api/v1/users/current/summaries"))
            .respond_with(ResponseTemplate::new(401).set_body_json(json!({ "error": "Unauthorized" })))
            .mount(&server)
            .await;
        Mock::given(method("GET"))
            .and(path("/wakatime/api/v1/users/current/durations"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({ "data": [] })))
            .mount(&server)
            .await;

        let st = state_with_mock(&server).await;
        let resp = wakatime_today(axum::extract::State(st)).await;
        assert_eq!(resp.status(), StatusCode::UNAUTHORIZED, "401 不該被吞成 200");
        let v = body_of(resp).await;
        assert_eq!(v["error"], "Failed to fetch WakaTime today data");
        assert!(v["details"].as_str().unwrap().contains("Unauthorized"), "要看得出上游說了什麼");
    }

    #[tokio::test]
    async fn wakatime_沒設定_key_時三支都回_500_並說明原因() {
        let _g = WAKA_ENV_LOCK.lock().await;
        // SAFETY: 靠 WAKA_ENV_LOCK 串行化。
        unsafe { std::env::remove_var("WAKATIME_API_KEY") };
        let server = MockServer::start().await; // 不掛任何 route:一旦有人送請求就會 404
        let st = state_with_mock(&server).await;

        for resp in [
            wakatime_today(axum::extract::State(st.clone())).await,
            wakatime_week(axum::extract::State(st.clone())).await,
            wakatime_projects(axum::extract::State(st.clone())).await,
        ] {
            assert_eq!(resp.status(), StatusCode::INTERNAL_SERVER_ERROR);
            let v = body_of(resp).await;
            assert_eq!(v["error"], WAKA_UNCONFIGURED, "要說得出是「沒設定」而不是「壞了」");
        }
        assert!(server.received_requests().await.unwrap().is_empty(), "沒有 key 就不該對外發請求");
    }

    #[tokio::test]
    async fn wakatime_week_與_projects_打同一支上游_只有錯誤字串不同() {
        let _key = with_waka_key().await;
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/wakatime/api/v1/users/current/stats/last_7_days"))
            .respond_with(ResponseTemplate::new(500).set_body_json(json!({ "error": "boom" })))
            .mount(&server)
            .await;
        let st = state_with_mock(&server).await;

        let w = body_of(wakatime_week(axum::extract::State(st.clone())).await).await;
        let p = body_of(wakatime_projects(axum::extract::State(st)).await).await;
        assert_eq!(w["error"], "Failed to fetch WakaTime week data");
        assert_eq!(p["error"], "Failed to fetch WakaTime projects data");
        // details 是「上游到底說了什麼」——只有 error 的話查起來完全沒有線索
        assert!(w["details"].as_str().unwrap().contains("boom"), "得到 {}", w["details"]);
        assert!(w["languages"].is_array(), "出錯時陣列欄位也要在(前端直接 .map)");
        // 兩支打的是同一個路徑(Express 就這樣,照抄)——這條把那件事釘住
        let paths: Vec<String> =
            server.received_requests().await.unwrap().iter().map(|r| r.url.path().to_string()).collect();
        assert_eq!(paths.len(), 2);
        assert_eq!(paths[0], paths[1], "week 與 projects 是同一支上游 API");
    }

    #[tokio::test]
    async fn wakatime_week_把_data_攤成_languages_與_projects() {
        let _key = with_waka_key().await;
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/wakatime/api/v1/users/current/stats/last_7_days"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "data": {
                    "languages": [{ "name": "Rust", "text": "9 hrs", "percent": 70.0 }],
                    "projects": [{ "name": "web", "text": "5 hrs", "percent": 40.0 }],
                    // 上游還會給 editors / machines / …,不該轉發
                    "editors": [{ "name": "VS Code", "text": "9 hrs", "percent": 100.0 }],
                }
            })))
            .mount(&server)
            .await;

        let st = state_with_mock(&server).await;
        let v = body_of(wakatime_week(axum::extract::State(st)).await).await;
        assert_eq!(v["languages"][0]["name"], "Rust");
        assert_eq!(v["projects"][0]["name"], "web");
        assert!(v.get("editors").is_none(), "只留前端會 render 的兩組");
        assert!(v.get("data").is_none(), "data 那層要被攤掉");
    }

    // ── GitHub ────────────────────────────────────────────────────────────

    #[test]
    fn github_event_from_缺必要欄位就整筆不收() {
        // 這四欄是 render 一列的必需品,缺了留著只會是一列空白
        let full = json!({
            "id": "1", "type": "PushEvent", "created_at": "2026-08-02T00:00:00Z",
            "repo": { "name": "timo9378/web" },
        });
        assert!(github_event_from(&full).is_some());
        for missing in ["id", "type", "created_at"] {
            let mut ev = full.clone();
            ev.as_object_mut().unwrap().remove(missing);
            assert!(github_event_from(&ev).is_none(), "缺 {missing} 應該整筆不收");
        }
        let mut no_repo = full;
        no_repo["repo"] = json!({});
        assert!(github_event_from(&no_repo).is_none(), "缺 repo.name 也一樣");
    }

    #[test]
    fn github_event_from_的_commits_缺_sha_就跳過該筆() {
        let ev = json!({
            "id": "1", "type": "PushEvent", "created_at": "2026-08-02T00:00:00Z",
            "repo": { "name": "timo9378/web" },
            "payload": {
                "before": "aaa", "head": "bbb", "size": 2,
                "commits": [
                    { "sha": "c1", "message": "第一筆", "author": { "name": "Koi", "email": "k@example.com" } },
                    { "message": "沒有 sha 的不收" },
                    { "sha": "c3" },
                ],
            },
        });
        let e = github_event_from(&ev).expect("完整事件");
        assert_eq!(e.kind, "PushEvent");
        assert_eq!(e.repo.name, "timo9378/web");
        assert_eq!(e.payload.before.as_deref(), Some("aaa"));
        assert_eq!(e.payload.size, Some(2));
        assert_eq!(e.payload.commits.len(), 2, "缺 sha 的那筆要跳過");
        assert_eq!(e.payload.commits[0].message, "第一筆");
        assert_eq!(e.payload.commits[0].author.as_ref().unwrap().name.as_deref(), Some("Koi"));
        assert_eq!(e.payload.commits[1].message, "", "缺 message 補空字串");
        assert!(e.payload.commits[1].author.is_none());
    }

    #[test]
    fn github_event_from_沒有_payload_也不會炸() {
        let ev = json!({
            "id": "1", "type": "WatchEvent", "created_at": "2026-08-02T00:00:00Z",
            "repo": { "name": "a/b" },
        });
        let e = github_event_from(&ev).expect("沒有 payload 的事件仍然有效");
        assert!(e.payload.commits.is_empty());
        assert!(e.payload.before.is_none());
        assert!(e.payload.size.is_none());
    }

    #[tokio::test]
    async fn github_repos_丟掉缺必要欄位的列並補齊選填欄位() {
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/github/users/timo9378/repos"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!([
                { "id": 1, "name": "web", "html_url": "https://github.com/timo9378/web",
                  "description": null, "language": "Rust", "stargazers_count": 7 },
                { "id": 2, "name": "沒有網址的" },                 // 缺 html_url → 不收
                { "name": "沒有 id 的", "html_url": "https://x/" }, // 缺 id → 不收
            ])))
            .mount(&server)
            .await;

        let st = state_with_mock(&server).await;
        let v = body_of(
            github_repos(
                axum::extract::State(st),
                axum::extract::Path("timo9378".into()),
                axum::extract::Query(ReposQuery { limit: None }),
            )
            .await,
        )
        .await;
        let repos = v["repos"].as_array().unwrap();
        assert_eq!(repos.len(), 1, "兩筆殘缺的要被丟掉");
        assert_eq!(repos[0]["name"], "web");
        assert!(repos[0]["description"].is_null());
        assert_eq!(repos[0]["stargazers_count"], 7);
        assert!(v["error"].is_null());
    }

    #[tokio::test]
    async fn github_repos_的_limit_夾在一到一百() {
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/github/users/u/repos"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!([])))
            .mount(&server)
            .await;
        let st = state_with_mock(&server).await;

        for (given, want) in [(None, "5"), (Some(0), "1"), (Some(999), "100"), (Some(20), "20")] {
            let _ = github_repos(
                axum::extract::State(st.clone()),
                axum::extract::Path("u".into()),
                axum::extract::Query(ReposQuery { limit: given }),
            )
            .await;
            let last = server.received_requests().await.unwrap().pop().unwrap();
            let per_page = last.url.query_pairs().find(|(k, _)| k == "per_page").unwrap().1.into_owned();
            assert_eq!(per_page, want, "limit={given:?} 應該送出 per_page={want}");
        }
    }

    /// 有設 GITHUB_TOKEN 就要真的帶上去。沒帶的話 REST 只剩每小時 60 次的匿名額度,
    /// 撞到之後 GitHub 回錯誤物件 → 前端顯示「這個人沒有任何 repo」。
    #[tokio::test]
    async fn github_repos_有_token_時會帶上_authorization() {
        let _t = with_gh_token().await;
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/github/users/u/repos"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!([])))
            .mount(&server)
            .await;
        let st = state_with_mock(&server).await;
        let _ = github_repos(
            axum::extract::State(st),
            axum::extract::Path("u".into()),
            axum::extract::Query(ReposQuery { limit: None }),
        )
        .await;
        let req = server.received_requests().await.unwrap().pop().unwrap();
        let auth = req.headers.get("authorization").map(|v| v.to_str().unwrap().to_string());
        assert_eq!(auth.as_deref(), Some("Bearer test-gh-token"));
    }

    #[tokio::test]
    async fn github_repos_遇到錯誤物件時把_message_放進_error() {
        // GitHub 的錯誤是物件不是陣列;不處理的話 `as_array()` 失敗會變成空清單 + 沒有錯誤,
        // 前端顯示「這個人沒有任何 repo」——把 rate limit 說成事實。
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/github/users/u/repos"))
            .respond_with(
                ResponseTemplate::new(403).set_body_json(json!({ "message": "API rate limit exceeded" })),
            )
            .mount(&server)
            .await;
        let st = state_with_mock(&server).await;
        let v = body_of(
            github_repos(
                axum::extract::State(st),
                axum::extract::Path("u".into()),
                axum::extract::Query(ReposQuery { limit: None }),
            )
            .await,
        )
        .await;
        assert_eq!(v["error"], "API rate limit exceeded");
        assert_eq!(v["repos"].as_array().unwrap().len(), 0);
    }

    /// GITHUB_TOKEN 同樣是 process 全域。
    static GH_ENV_LOCK: std::sync::LazyLock<tokio::sync::Mutex<()>> =
        std::sync::LazyLock::new(|| tokio::sync::Mutex::new(()));

    // 這個欄位不會被讀,只是把鎖握到 guard 被 drop 為止(env 是 process 全域的)。
    struct GhToken(#[allow(dead_code)] tokio::sync::MutexGuard<'static, ()>);
    impl Drop for GhToken {
        fn drop(&mut self) {
            // SAFETY: 靠 GH_ENV_LOCK 串行化。
            unsafe { std::env::remove_var("GITHUB_TOKEN") };
        }
    }
    async fn with_gh_token() -> GhToken {
        let g = GH_ENV_LOCK.lock().await;
        // SAFETY: 同上。
        unsafe { std::env::set_var("GITHUB_TOKEN", "test-gh-token") };
        GhToken(g)
    }

    #[tokio::test]
    async fn github_works_每個_repo_一個_alias_私有的沒有連結_抓不到的那件跳過() {
        let _t = with_gh_token().await;
        let server = MockServer::start().await;
        Mock::given(method("POST"))
            .and(path("/github/graphql"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "data": {
                    "r0": {
                        "nameWithOwner": "timo9378/Volticar_API", "url": "https://github.com/timo9378/Volticar_API",
                        "isPrivate": true, "createdAt": "2025-03-21T00:00:00Z", "pushedAt": "2025-03-21T00:00:00Z",
                        "stargazerCount": 0,
                        "languages": { "edges": [ { "size": 21623, "node": { "name": "Python" } } ] },
                        "defaultBranchRef": { "target": { "history": { "totalCount": 1 } } }
                    },
                    "r1": {
                        "nameWithOwner": "timo9378/sora-to-ki", "url": "https://github.com/timo9378/sora-to-ki",
                        "isPrivate": false, "createdAt": "2025-03-31T00:00:00Z", "pushedAt": "2026-10-23T00:00:00Z",
                        "stargazerCount": 2,
                        "languages": { "edges": [
                            { "size": 2368532, "node": { "name": "TypeScript" } },
                            { "size": 1381627, "node": { "name": "Rust" } }
                        ] },
                        "defaultBranchRef": { "target": { "history": { "totalCount": 732 } } }
                    },
                    "r2": null
                },
                "errors": [ { "message": "Could not resolve to a Repository" } ]
            })))
            .mount(&server)
            .await;

        let st = state_with_mock(&server).await;
        let resp = github_works(axum::extract::State(st)).await;
        assert_eq!(resp.status(), StatusCode::OK, "部分 repo 抓不到不算整支失敗");
        let v = body_of(resp).await;
        let works = v["works"].as_array().unwrap();
        assert_eq!(works.len(), 2, "null 的那件不列");
        assert!(works[0]["url"].is_null(), "私有 repo 不給連結");
        assert_eq!(works[1]["url"], "https://github.com/timo9378/sora-to-ki");
        assert_eq!(works[1]["commits"], 732);
        assert_eq!(works[1]["languages"][1]["name"], "Rust");
        assert_eq!(works[1]["languages"][1]["bytes"], 1381627);
    }

    #[tokio::test]
    async fn github_works_整個查詢失敗回_502_讓快取層拿舊的頂著() {
        let _t = with_gh_token().await;
        let server = MockServer::start().await;
        Mock::given(method("POST"))
            .and(path("/github/graphql"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "errors": [ { "message": "API rate limit exceeded" } ]
            })))
            .mount(&server)
            .await;

        let st = state_with_mock(&server).await;
        let resp = github_works(axum::extract::State(st)).await;
        assert_eq!(resp.status(), StatusCode::BAD_GATEWAY);
        assert_eq!(body_of(resp).await["error"], "API rate limit exceeded");
    }

    #[tokio::test]
    async fn github_contributions_把週攤平成日並帶出總數() {
        let _t = with_gh_token().await;
        let server = MockServer::start().await;
        Mock::given(method("POST"))
            .and(path("/github/graphql"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "data": { "user": { "contributionsCollection": { "contributionCalendar": {
                    "totalContributions": 123,
                    "weeks": [
                        { "contributionDays": [
                            { "date": "2026-01-01", "contributionCount": 3 },
                            { "date": "2026-01-02", "contributionCount": 0 },
                        ]},
                        { "contributionDays": [{ "date": "2026-01-03", "contributionCount": 5 }]},
                    ],
                }}}}
            })))
            .mount(&server)
            .await;

        let st = state_with_mock(&server).await;
        let v = body_of(
            github_contributions(
                axum::extract::State(st),
                axum::extract::Path("u".into()),
                axum::extract::Query(ContributionsQuery { year: None }),
            )
            .await,
        )
        .await;
        let days = v["contributions"].as_array().unwrap();
        assert_eq!(days.len(), 3, "兩週共三天要被攤成一個平陣列");
        assert_eq!(days[0]["date"], "2026-01-01");
        assert_eq!(days[2]["count"], 5);
        assert_eq!(v["total"], 123);
        assert!(v["error"].is_null());
    }

    #[tokio::test]
    async fn github_contributions_的_graphql_錯誤是_200_加_errors_不是狀態碼() {
        // 這是 GraphQL 的特性:查詢失敗照樣回 200。只看狀態碼的話會把錯誤當成
        // 「這個人今年一次貢獻都沒有」畫出一張全白的熱圖。
        let _t = with_gh_token().await;
        let server = MockServer::start().await;
        Mock::given(method("POST"))
            .and(path("/github/graphql"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "errors": [{ "message": "Could not resolve to a User with the login of 'nobody'." }]
            })))
            .mount(&server)
            .await;

        let st = state_with_mock(&server).await;
        let v = body_of(
            github_contributions(
                axum::extract::State(st),
                axum::extract::Path("nobody".into()),
                axum::extract::Query(ContributionsQuery { year: None }),
            )
            .await,
        )
        .await;
        assert!(v["error"].as_str().unwrap().contains("Could not resolve"));
        assert_eq!(v["total"], 0);
        assert_eq!(v["contributions"].as_array().unwrap().len(), 0);
    }

    #[tokio::test]
    async fn github_contributions_的_year_只接受四位數字() {
        let _t = with_gh_token().await;
        let server = MockServer::start().await;
        Mock::given(method("POST"))
            .and(path("/github/graphql"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({ "data": {} })))
            .mount(&server)
            .await;
        let st = state_with_mock(&server).await;

        // year 會被拼進 GraphQL 的時間字串,所以它是注入面——擋在送出之前
        for bad in ["20xx", "12345", "2026'", "", "1"] {
            let v = body_of(
                github_contributions(
                    axum::extract::State(st.clone()),
                    axum::extract::Path("u".into()),
                    axum::extract::Query(ContributionsQuery { year: Some(bad.to_string()) }),
                )
                .await,
            )
            .await;
            assert_eq!(v["error"], "year 格式不正確", "year={bad:?} 應該被擋下");
        }
        assert!(server.received_requests().await.unwrap().is_empty(), "格式不對就不該送出查詢");

        // 合法的四位數字與 "last" 都要放行
        for ok in ["2026", "last"] {
            let v = body_of(
                github_contributions(
                    axum::extract::State(st.clone()),
                    axum::extract::Path("u".into()),
                    axum::extract::Query(ContributionsQuery { year: Some(ok.to_string()) }),
                )
                .await,
            )
            .await;
            assert!(v["error"].is_null(), "year={ok} 應該放行");
        }
    }

    #[tokio::test]
    async fn github_contributions_沒有_token_就不送出查詢() {
        let _g = GH_ENV_LOCK.lock().await;
        // SAFETY: 靠 GH_ENV_LOCK 串行化。
        unsafe { std::env::remove_var("GITHUB_TOKEN") };
        let server = MockServer::start().await;
        let st = state_with_mock(&server).await;
        let v = body_of(
            github_contributions(
                axum::extract::State(st),
                axum::extract::Path("u".into()),
                axum::extract::Query(ContributionsQuery { year: None }),
            )
            .await,
        )
        .await;
        assert!(v["error"].as_str().unwrap().contains("GITHUB_TOKEN"));
        assert!(server.received_requests().await.unwrap().is_empty());
    }

    #[tokio::test]
    async fn github_events_套用_github_event_from_的過濾() {
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/github/users/u/events/public"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!([
                { "id": "1", "type": "PushEvent", "created_at": "2026-08-02T00:00:00Z",
                  "repo": { "name": "a/b" }, "payload": { "size": 1 } },
                { "id": "2", "type": "PushEvent" },  // 殘缺 → 丟掉
            ])))
            .mount(&server)
            .await;

        let st = state_with_mock(&server).await;
        let v = body_of(github_events(axum::extract::State(st), axum::extract::Path("u".into())).await).await;
        let events = v["events"].as_array().unwrap();
        assert_eq!(events.len(), 1);
        assert_eq!(events[0]["type"], "PushEvent", "序列化欄位名是 type 不是 kind");
        assert_eq!(events[0]["repo"]["name"], "a/b");
    }

    /// GitHub 的 events API 會把 PushEvent 的 commits 截斷(常常是空陣列),
    /// 所以有 before/head 時要再去打 compare API 補回來。
    /// 這段壞掉的話動態牆會顯示「推了 N 個 commit」卻一條訊息都沒有。
    #[tokio::test]
    async fn github_events_用_compare_api_補回被截斷的_commits() {
        let _t = with_gh_token().await;
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/github/users/u/events/public"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!([{
                "id": "1", "type": "PushEvent", "created_at": "2026-08-02T00:00:00Z",
                "repo": { "name": "timo9378/web" },
                "payload": { "commits": [], "before": "aaa", "head": "bbb", "size": 0 },
            }])))
            .mount(&server)
            .await;
        Mock::given(method("GET"))
            .and(path("/github/repos/timo9378/web/compare/aaa...bbb"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "commits": [
                    { "sha": "c1", "commit": { "message": "第一個 commit", "author": { "name": "Koi" } } },
                    { "sha": "c2", "commit": { "message": "第二個 commit", "author": { "name": "Koi" } } },
                ]
            })))
            .mount(&server)
            .await;

        let st = state_with_mock(&server).await;
        let v = body_of(github_events(axum::extract::State(st), axum::extract::Path("u".into())).await).await;
        let commits = v["events"][0]["payload"]["commits"].as_array().unwrap();
        assert_eq!(commits.len(), 2, "compare 回來的 commits 要被填進去");
        assert_eq!(commits[0]["message"], "第一個 commit", "訊息在 commit.message 那層,要挖出來");
        assert_eq!(commits[0]["author"]["name"], "Koi");
        assert_eq!(v["events"][0]["payload"]["size"], 2, "size 要跟著補正,不是留著上游的 0");
    }

    #[tokio::test]
    async fn github_events_沒有_token_時不打_compare_api() {
        // compare 需要認證;沒 token 就不該白跑一趟(也不該因此整筆失敗)
        let _g = GH_ENV_LOCK.lock().await;
        // SAFETY: 靠 GH_ENV_LOCK 串行化。
        unsafe { std::env::remove_var("GITHUB_TOKEN") };
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/github/users/u/events/public"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!([{
                "id": "1", "type": "PushEvent", "created_at": "2026-08-02T00:00:00Z",
                "repo": { "name": "a/b" },
                "payload": { "commits": [], "before": "aaa", "head": "bbb" },
            }])))
            .mount(&server)
            .await;

        let st = state_with_mock(&server).await;
        let v = body_of(github_events(axum::extract::State(st), axum::extract::Path("u".into())).await).await;
        assert_eq!(v["events"].as_array().unwrap().len(), 1, "沒有 commits 也還是要顯示這筆");
        let paths: Vec<String> =
            server.received_requests().await.unwrap().iter().map(|r| r.url.path().to_string()).collect();
        assert!(!paths.iter().any(|p| p.contains("/compare/")), "沒有 token 就不該打 compare");
    }

    /// 只有「commits 是空的」才需要去補;已經有 commits 的不能再打一次 compare。
    ///
    /// `cargo mutants` 指出來的:把那串條件的 `&&` 換成 `||` 測試照樣全綠。
    /// 後果是每一筆 PushEvent 都多打一次 GitHub API(很快就撞到 rate limit),
    /// 而且會用 compare 的結果**覆蓋掉原本就正確的 commits**。
    #[tokio::test]
    async fn github_events_已經有_commits_時不再打_compare() {
        let _t = with_gh_token().await;
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/github/users/u/events/public"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!([{
                "id": "1", "type": "PushEvent", "created_at": "2026-08-02T00:00:00Z",
                "repo": { "name": "a/b" },
                // commits 非空,但 before/head 也在——這正是 `||` 會誤判的組合
                "payload": {
                    "commits": [{ "sha": "已有的", "message": "原本就抓得到" }],
                    "before": "aaa", "head": "bbb", "size": 1,
                },
            }])))
            .mount(&server)
            .await;
        // 刻意不掛 compare:真的去打就會 404,下面的斷言會看到 commits 被清空
        let st = state_with_mock(&server).await;
        let v = body_of(github_events(axum::extract::State(st), axum::extract::Path("u".into())).await).await;

        let commits = v["events"][0]["payload"]["commits"].as_array().unwrap();
        assert_eq!(commits.len(), 1);
        assert_eq!(commits[0]["sha"], "已有的", "原本就有的 commits 不該被覆蓋");
        let paths: Vec<String> =
            server.received_requests().await.unwrap().iter().map(|r| r.url.path().to_string()).collect();
        assert!(
            !paths.iter().any(|p| p.contains("/compare/")),
            "已經有 commits 就不必補,實際打了 {paths:?}"
        );
    }

    #[tokio::test]
    async fn github_events_遇到錯誤物件時把_message_放進_error() {
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/github/users/u/events/public"))
            .respond_with(
                ResponseTemplate::new(403).set_body_json(json!({ "message": "API rate limit exceeded" })),
            )
            .mount(&server)
            .await;
        let st = state_with_mock(&server).await;
        let v = body_of(github_events(axum::extract::State(st), axum::extract::Path("u".into())).await).await;
        assert_eq!(v["error"], "API rate limit exceeded", "不然前端會以為這個人真的沒有動態");
        assert_eq!(v["events"].as_array().unwrap().len(), 0);
    }

    // ── Steam 的未配置降級路徑 ────────────────────────────────────────────
    //
    // 這條路只有在「金鑰沒設好」時才會走到,平常沒有人經過——正因如此它壞掉了
    // 也不會有人發現,直到某次換機器忘了帶 env。形狀由 e2e 的 api-contract 也驗一次,
    // 這裡驗的是狀態碼與訊息。

    #[tokio::test]
    async fn steam_沒設定金鑰時回_500_且陣列欄位仍然存在() {
        let _env = STEAM_ENV_LOCK.lock().await;
        // SAFETY: 靠 STEAM_ENV_LOCK 串行化。
        unsafe {
            std::env::remove_var("STEAM_API_KEY");
            std::env::remove_var("STEAM_ID");
        }
        let server = MockServer::start().await;
        let st = state_with_mock(&server).await;

        for resp in [
            steam_recent_games(axum::extract::State(st.clone())).await,
            steam_owned_games(axum::extract::State(st.clone())).await,
        ] {
            assert_eq!(resp.status(), StatusCode::INTERNAL_SERVER_ERROR);
            let v = body_of(resp).await;
            assert_eq!(v["error"], STEAM_UNCONFIGURED);
            assert!(v["games"].is_array(), "前端直接 .map,games 一定要是陣列不能是 undefined");
        }

        let resp = steam_player(axum::extract::State(st.clone())).await;
        assert_eq!(resp.status(), StatusCode::INTERNAL_SERVER_ERROR);
        assert_eq!(body_of(resp).await["error"], STEAM_UNCONFIGURED);

        let resp = steam_achievements(axum::extract::State(st), axum::extract::Path("440".into())).await;
        assert_eq!(resp.status(), StatusCode::INTERNAL_SERVER_ERROR);
        assert_eq!(body_of(resp).await["error"], STEAM_UNCONFIGURED);

        assert!(server.received_requests().await.unwrap().is_empty(), "沒金鑰就不該對外發請求");
    }

    /// `steam_games` 這個共用 helper 原本只有它裡面的純函式(`steam_games_from`)被測過,
    /// 整條 HTTP 路徑沒走過——包含「只有 owned-games 才帶 gameCount」這個差別。
    #[tokio::test]
    async fn steam_的兩支遊戲清單只有_owned_帶_gamecount() {
        let _env = STEAM_ENV_LOCK.lock().await;
        // SAFETY: 靠 STEAM_ENV_LOCK 串行化。
        unsafe {
            std::env::set_var("STEAM_API_KEY", "k");
            std::env::set_var("STEAM_ID", "1");
        }
        let server = MockServer::start().await;
        let body = json!({ "response": {
            "game_count": 87,
            "games": [{ "appid": 730, "name": "CS2", "playtime_forever": 9999 }],
        }});
        for p in [
            "/steam-api/IPlayerService/GetRecentlyPlayedGames/v0001/",
            "/steam-api/IPlayerService/GetOwnedGames/v0001/",
        ] {
            Mock::given(method("GET"))
                .and(path(p))
                .respond_with(ResponseTemplate::new(200).set_body_json(body.clone()))
                .mount(&server)
                .await;
        }
        let st = state_with_mock(&server).await;

        let recent = body_of(steam_recent_games(axum::extract::State(st.clone())).await).await;
        assert_eq!(recent["games"][0]["name"], "CS2");
        assert!(recent["gameCount"].is_null(), "recent-games 不帶 gameCount(上游有給也不轉發)");

        let owned = body_of(steam_owned_games(axum::extract::State(st.clone())).await).await;
        assert_eq!(owned["games"][0]["appid"], 730);
        assert_eq!(owned["gameCount"], 87, "owned-games 才帶 gameCount");

        // SAFETY: 見上。
        unsafe {
            std::env::remove_var("STEAM_API_KEY");
            std::env::remove_var("STEAM_ID");
        }
    }

    #[tokio::test]
    async fn steam_遊戲清單遇到非_json_回應時仍然給得出陣列() {
        let _env = STEAM_ENV_LOCK.lock().await;
        // SAFETY: 見上。
        unsafe {
            std::env::set_var("STEAM_API_KEY", "k");
            std::env::set_var("STEAM_ID", "1");
        }
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/steam-api/IPlayerService/GetRecentlyPlayedGames/v0001/"))
            .respond_with(ResponseTemplate::new(200).set_body_string("<html>Steam is down</html>"))
            .mount(&server)
            .await;
        let st = state_with_mock(&server).await;

        let resp = steam_recent_games(axum::extract::State(st)).await;
        assert_eq!(resp.status(), StatusCode::INTERNAL_SERVER_ERROR);
        let v = body_of(resp).await;
        assert_eq!(v["error"], STEAM_PARSE_ERR);
        assert!(v["games"].is_array(), "前端直接 .map,錯誤時 games 也不能是 undefined");

        // SAFETY: 見上。
        unsafe {
            std::env::remove_var("STEAM_API_KEY");
            std::env::remove_var("STEAM_ID");
        }
    }

    #[tokio::test]
    async fn steam_achievements_是唯一保留原樣轉發的一支() {
        let _env = STEAM_ENV_LOCK.lock().await;
        // SAFETY: 見上。
        unsafe {
            std::env::set_var("STEAM_API_KEY", "k");
            std::env::set_var("STEAM_ID", "1");
        }
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/steam-api/ISteamUserStats/GetPlayerAchievements/v0001/"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "playerstats": { "achievements": [{ "apiname": "A", "achieved": 1 }] }
            })))
            .mount(&server)
            .await;

        let st = state_with_mock(&server).await;
        let v =
            body_of(steam_achievements(axum::extract::State(st), axum::extract::Path("440".into())).await)
                .await;
        // 這支刻意不塑形(註解說明了理由),所以上游的巢狀結構要原樣出現
        assert_eq!(v["playerstats"]["achievements"][0]["apiname"], "A");

        // SAFETY: 見上。
        unsafe {
            std::env::remove_var("STEAM_API_KEY");
            std::env::remove_var("STEAM_ID");
        }
    }

    // ── steam/profile 的 SWR 與 refresh ───────────────────────────────────
    //
    // `cargo mutants` 指出來的一整片洞。這裡每一個判斷壞掉都是**沒有症狀**的:
    // 要嘛個人檔案永遠停在舊資料,要嘛每一次請求都去打 Steam(而 Steam 會限流)。

    /// 用真的 Steam ID 算出 miniprofile 的 accountid。這個減法寫錯的話 miniprofile
    /// 會抓到別人的頁面或 404 —— 客製全部消失,但個人檔案其他欄位都正常。
    const STEAM_ID64: &str = "76561198000000000";
    const ACCOUNT_ID: &str = "39734272"; // 76561198000000000 - 76561197960265728

    /// 掛好 refresh 需要的四支上游。`mini` 是 miniprofile 的 HTML。
    async fn mount_steam_profile_upstreams(server: &MockServer, mini: &str) {
        Mock::given(method("GET"))
            .and(path("/steam-api/ISteamUser/GetPlayerSummaries/v0002/"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "response": { "players": [{ "personaname": "Koi", "personastate": 1 }] }
            })))
            .mount(server)
            .await;
        Mock::given(method("GET"))
            .and(path("/steam-api/IPlayerService/GetSteamLevel/v1/"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "response": { "player_level": 42 }
            })))
            .mount(server)
            .await;
        Mock::given(method("GET"))
            .and(path("/steam-api/IPlayerService/GetBadges/v1/"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "response": { "badges": [{}, {}, {}], "player_xp": 100, "player_xp_needed_to_level_up": 200 }
            })))
            .mount(server)
            .await;
        Mock::given(method("GET"))
            .and(path(format!("/steam-community/miniprofile/{ACCOUNT_ID}")))
            .respond_with(ResponseTemplate::new(200).set_body_string(mini))
            .mount(server)
            .await;
    }

    #[tokio::test]
    async fn refresh_steam_profile_合併四支上游並算對_miniprofile_的_accountid() {
        let server = MockServer::start().await;
        mount_steam_profile_upstreams(&server, MINI_PROFILE_HTML).await;
        let st = state_with_mock(&server).await;

        let p = refresh_steam_profile(&st, "k", STEAM_ID64).await.expect("四支都成功");
        assert_eq!(p.player.personaname.as_deref(), Some("Koi"));
        assert_eq!(p.level, 42);
        assert_eq!(p.xp, 100);
        assert_eq!(p.xp_to_next, 200);
        assert_eq!(p.badge_count, 3, "badge_count 是 badges 陣列的長度");
        assert_eq!(p.profile_url, format!("https://steamcommunity.com/profiles/{STEAM_ID64}"));
        // miniprofile 的 HTML 真的有被解析(不是拿到空字串就算了)
        assert_eq!(p.customization.avatar_frame.as_deref(), Some("https://cdn/frame.png"));
        // accountid 算錯就會 404 → 上面那條會是 None。這裡再直接確認打的是哪個路徑。
        let paths: Vec<String> =
            server.received_requests().await.unwrap().iter().map(|r| r.url.path().to_string()).collect();
        assert!(
            paths.iter().any(|p| p.ends_with(&format!("/miniprofile/{ACCOUNT_ID}"))),
            "SteamID64 要減掉 76561197960265728 才是 accountid,實際打了 {paths:?}"
        );

        // 成功要寫進快取,且兩個時間戳一致
        let c = st.steam.cache.lock().clone().expect("成功後應該有快取");
        assert_eq!(c.fetched_at, c.last_tried_at);
        assert_eq!(c.data.level, 42);
    }

    #[tokio::test]
    async fn refresh_steam_profile_失敗時只更新_last_tried_at_不動舊資料() {
        let server = MockServer::start().await;
        // level 那支掛掉 → 整次 refresh 失敗
        Mock::given(method("GET"))
            .and(path("/steam-api/ISteamUser/GetPlayerSummaries/v0002/"))
            .respond_with(
                ResponseTemplate::new(200).set_body_json(json!({ "response": { "players": [{}] } })),
            )
            .mount(&server)
            .await;
        Mock::given(method("GET"))
            .and(path("/steam-api/IPlayerService/GetSteamLevel/v1/"))
            .respond_with(ResponseTemplate::new(500))
            .mount(&server)
            .await;
        let st = state_with_mock(&server).await;
        *st.steam.cache.lock() = Some(crate::state::SteamProfileCache {
            data: fake_profile("舊資料"),
            fetched_at: 1_000,
            last_tried_at: 1_000,
        });

        assert!(refresh_steam_profile(&st, "k", STEAM_ID64).await.is_err());
        let c = st.steam.cache.lock().clone().unwrap();
        assert_eq!(c.data.player.personaname.as_deref(), Some("舊資料"), "失敗不該清掉能用的舊資料");
        assert_eq!(c.fetched_at, 1_000, "fetched_at 不動——不然會被當成剛抓過而不再重試");
        assert!(c.last_tried_at > 1_000, "只有 last_tried_at 前進,退避才有依據");
    }

    #[tokio::test]
    async fn refresh_steam_profile_的_steam_id_不是數字時直接失敗() {
        let server = MockServer::start().await;
        let st = state_with_mock(&server).await;
        let e = refresh_steam_profile(&st, "k", "not-a-number").await.unwrap_err();
        assert_eq!(e, "invalid STEAM_ID");
        assert!(server.received_requests().await.unwrap().is_empty(), "算不出 accountid 就不該送出請求");
    }

    /// SWR 的重抓判斷:`距上次成功 >= 30 分鐘` **且** `距上次嘗試 >= 5 分鐘`。
    ///
    /// 三種寫壞的方式各有各的無聲後果:
    ///   · `>=` 反向 → 新鮮時狂抓、過期時反而不抓
    ///   · `&&` 換 `||` → 上游掛掉之後每一次請求都重試,退避形同虛設(Steam 會限流)
    ///   · 常數乘號寫成加號 → 30*60*1000 變 1090ms,等於每次請求都重抓
    /// 全部都不會有錯誤訊息,只會在 Steam 那端變成一個很吵的客戶端。
    #[tokio::test]
    async fn steam_profile_的_swr_只在夠舊且過了退避期才背景重抓() {
        let _env = STEAM_ENV_LOCK.lock().await;
        // SAFETY: 靠 STEAM_ENV_LOCK 串行化。
        unsafe {
            std::env::set_var("STEAM_API_KEY", "k");
            std::env::set_var("STEAM_ID", STEAM_ID64);
        }

        // (距上次成功, 距上次嘗試, 是否該重抓)
        //
        // ⚠ 「十分鐘」那一組是刻意的:它落在 30 分鐘門檻之內,但**超過**把常數的
        // `30 * 60 * 1000` 誤寫成 `30 + 60 * 1000`(=60030ms)之後的門檻。
        // 第一版只放了 60 秒,兩種寫法都判定為新鮮,於是那個變異活了下來。
        let cases = [
            (1_000i64, 1_000i64, false, "剛抓完"),
            (600_000, 600_000, false, "十分鐘——還沒到 30 分鐘的重抓門檻"),
            // ⚠ 這裡的 120 秒也是刻意挑的,理由同上:它在 5 分鐘退避之內,但**超過**
            // 把 `5 * 60 * 1000` 誤寫成 `5 + 60 * 1000`(=60005ms)之後的門檻。
            // 第一版寫 60 秒,兩種寫法都判定為「還在退避中」,那個變異因此活了下來。
            (STEAM_PROFILE_REFRESH_AFTER + 1, 120_000, false, "夠舊了但兩分鐘前才試過 → 要等退避"),
            (600_000, STEAM_PROFILE_RETRY_BACKOFF + 1, false, "退避過了但資料還新鮮"),
            (STEAM_PROFILE_REFRESH_AFTER + 1, STEAM_PROFILE_RETRY_BACKOFF + 1, true, "兩個條件都成立"),
        ];
        for (since_fetch, since_try, should_refetch, why) in cases {
            let server = MockServer::start().await;
            mount_steam_profile_upstreams(&server, "").await;
            let st = state_with_mock(&server).await;
            let now = now_ms();
            *st.steam.cache.lock() = Some(crate::state::SteamProfileCache {
                data: fake_profile("快取裡的"),
                fetched_at: now - since_fetch,
                last_tried_at: now - since_try,
            });

            let v = body_of(steam_profile(axum::extract::State(st.clone())).await).await;
            assert_eq!(v["player"]["personaname"], "快取裡的", "{why}:不管重不重抓,這一次都該直接回快取");

            // 背景重抓是 tokio::spawn,給它一點時間跑完
            for _ in 0..50 {
                if !server.received_requests().await.unwrap().is_empty() {
                    break;
                }
                tokio::time::sleep(std::time::Duration::from_millis(20)).await;
            }
            let hit = !server.received_requests().await.unwrap().is_empty();
            assert_eq!(hit, should_refetch, "{why}:預期重抓={should_refetch},實際={hit}");
        }

        // SAFETY: 見上。
        unsafe {
            std::env::remove_var("STEAM_API_KEY");
            std::env::remove_var("STEAM_ID");
        }
    }

    // ── Books 外部搜尋 ────────────────────────────────────────────────────

    #[test]
    fn upgrade_google_cover_照抄_js_replace_只換第一次出現() {
        // 空字串直接回空——不要生出一個 "&zoom=0&w=500&h=800" 這種連不到的網址
        assert_eq!(upgrade_google_cover(""), "");

        let got = upgrade_google_cover("https://books.google.com/x?id=1&zoom=1&edge=curl&img=1");
        assert!(got.contains("&zoom=0"), "zoom=1 要換成 zoom=0(要高解析度)");
        assert!(!got.contains("edge=curl"), "捲角效果要拿掉");
        assert!(got.contains("&img=1&w=500&h=800"));

        // 本來就沒有 zoom / w 的要補上
        let got = upgrade_google_cover("https://books.google.com/x?id=1");
        assert!(got.ends_with("&zoom=0&w=500&h=800"), "得到 {got}");

        // 只換第一次出現(JS 的 String.replace 語意)
        let got = upgrade_google_cover("https://x/?a&zoom=1&b&zoom=1");
        assert_eq!(got.matches("zoom=1").count(), 1, "第二個 zoom=1 不該被換掉");
    }

    #[tokio::test]
    async fn books_search_external_沒給關鍵字就_400() {
        let server = MockServer::start().await;
        let st = state_with_mock(&server).await;
        let resp = books_search_external(
            axum::extract::State(st),
            axum::extract::Query(BookSearchQuery { query: None, isbn: Some(String::new()) }),
        )
        .await;
        assert_eq!(resp.status(), StatusCode::BAD_REQUEST);
        assert_eq!(body_of(resp).await["error"], "請提供書名或 ISBN");
        assert!(server.received_requests().await.unwrap().is_empty());
    }

    #[tokio::test]
    async fn books_search_external_認得出_isbn_去掉連字號_不加_isbn_前綴() {
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/google-books/books/v1/volumes"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({ "items": [] })))
            .mount(&server)
            .await;
        Mock::given(method("GET"))
            .and(path("/openlibrary/search.json"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({ "docs": [] })))
            .mount(&server)
            .await;
        let st = state_with_mock(&server).await;

        // 帶連字號的 ISBN:查詢字串要變成去掉連字號的純數字。
        // 不加 `isbn:` 前綴——Google Books 的那個運算子現在對任何書都回 0 筆(見 books_search_external)。
        let _ = books_search_external(
            axum::extract::State(st),
            axum::extract::Query(BookSearchQuery { query: None, isbn: Some("978-1-234-56789-0".into()) }),
        )
        .await;
        let reqs = server.received_requests().await.unwrap();
        let google = reqs.iter().find(|r| r.url.path().contains("volumes")).expect("該打 Google Books");
        let q = google.url.query_pairs().find(|(k, _)| k == "q").unwrap().1.into_owned();
        assert_eq!(q, "9781234567890", "連字號要去掉,而且不能加 isbn: 前綴");
    }

    #[tokio::test]
    async fn books_search_external_google_有結果就不打_openlibrary() {
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/google-books/books/v1/volumes"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "items": [{ "volumeInfo": {
                    "title": "測試書名",
                    "authors": ["作者一", "作者二"],
                    "publisher": "某出版社",
                    "industryIdentifiers": [
                        { "type": "ISBN_10", "identifier": "1234567890" },
                        { "type": "ISBN_13", "identifier": "9781234567890" },
                    ],
                    "imageLinks": { "thumbnail": "https://books.google.com/x?img=1&zoom=1" },
                    "pageCount": 320,
                    "categories": ["Computers", "Programming"],
                }}]
            })))
            .mount(&server)
            .await;
        let st = state_with_mock(&server).await;

        let v = body_of(
            books_search_external(
                axum::extract::State(st),
                axum::extract::Query(BookSearchQuery { query: Some("測試".into()), isbn: None }),
            )
            .await,
        )
        .await;
        let books = v["books"].as_array().unwrap();
        assert_eq!(books.len(), 1);
        assert_eq!(books[0]["isbn"], "9781234567890", "ISBN_13 優先於 ISBN_10");
        assert_eq!(books[0]["authors"], "作者一, 作者二", "多位作者用逗號串起來");
        assert_eq!(books[0]["categories"], "Computers, Programming");
        assert_eq!(books[0]["page_count"], 320);
        assert_eq!(books[0]["source"], "google");
        assert!(books[0]["cover_url"].as_str().unwrap().contains("zoom=0"));
        // 有結果就不該再打補位的那支
        let paths: Vec<String> =
            server.received_requests().await.unwrap().iter().map(|r| r.url.path().to_string()).collect();
        assert!(!paths.iter().any(|p| p.contains("openlibrary")), "Google 有結果就不必補位");
        assert_eq!(v["warnings"], json!([]), "正常時不該有 warning");
    }

    #[tokio::test]
    async fn books_search_external_用_isbn_查時_isbn_吻合的排第一() {
        // 不加 isbn: 前綴之後,數字也可能出現在別本書的內容裡;吻合的那本要排在最前面
        let server = MockServer::start().await;
        let item = |isbn: &str, title: &str| json!({ "volumeInfo": { "title": title, "industryIdentifiers": [{ "type": "ISBN_13", "identifier": isbn }] } });
        Mock::given(method("GET"))
            .and(path("/google-books/books/v1/volumes"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "items": [item("9780000000001", "引用了這個數字的別本書"), item("9789573267478", "要找的那本")]
            })))
            .mount(&server)
            .await;
        let st = state_with_mock(&server).await;
        let v = body_of(
            books_search_external(
                axum::extract::State(st),
                axum::extract::Query(BookSearchQuery { query: None, isbn: Some("978-957-32-6747-8".into()) }),
            )
            .await,
        )
        .await;
        assert_eq!(v["books"][0]["title"], "要找的那本");
        assert_eq!(v["books"].as_array().unwrap().len(), 2, "不吻合的也留著(可能是同一本的其他版本)");
    }

    #[test]
    fn merge_with_ncl_同一本留國圖那筆並從_google_補封面() {
        let ncl =
            vec![json!({ "isbn": "9789864894253", "title": "午夜圖書館", "cover_url": "", "description": "",
                               "language": "繁體中文", "page_count": null, "source": "ncl" })];
        let google = vec![
            json!({ "isbn": "9789864894253", "title": "The Midnight Library", "cover_url": "https://g/c.jpg",
                    "description": "簡介", "language": "zh-TW", "page_count": 288, "source": "google" }),
            json!({ "isbn": "9780000000000", "title": "別本", "source": "google" }),
        ];
        let out = merge_with_ncl(ncl.clone(), google.clone(), true);
        assert_eq!(out.len(), 2, "同一個 ISBN 不能列兩次:{out:?}");
        assert_eq!(out[0]["title"], "午夜圖書館", "書名要留台灣版的");
        assert_eq!(out[0]["cover_url"], "https://g/c.jpg", "國圖沒有封面,要從 Google 補");
        assert_eq!(out[0]["description"], "簡介");
        assert_eq!(out[0]["page_count"], 288);
        assert_eq!(out[0]["language"], "繁體中文", "國圖有的欄位不能被 Google 蓋掉");
        assert_eq!(out[1]["title"], "別本");

        // 英文關鍵字:Google 的排前面
        let out = merge_with_ncl(ncl, google, false);
        assert_eq!(out[0]["title"], "別本");
    }

    #[tokio::test]
    async fn books_search_external_用_isbn_查時國圖的索引排第一() {
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/google-books/books/v1/volumes"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({ "items": [] })))
            .mount(&server)
            .await;
        let st = state_with_mock(&server).await;
        sqlx::query("INSERT INTO tw_books (isbn, title, publisher, pub_date, ym) VALUES (?, ?, ?, ?, ?)")
            .bind("9786267388990")
            .bind("過於喧囂的孤獨")
            .bind("大塊文化")
            .bind("2024-05-00")
            .bind("202404")
            .execute(&st.pool)
            .await
            .unwrap();
        let v = body_of(
            books_search_external(
                axum::extract::State(st),
                axum::extract::Query(BookSearchQuery { query: None, isbn: Some("978-626-7388-99-0".into()) }),
            )
            .await,
        )
        .await;
        assert_eq!(v["books"][0]["title"], "過於喧囂的孤獨", "{v}");
        assert_eq!(v["books"][0]["source"], "ncl");
        assert_eq!(v["books"][0]["published_date"], "2024-05");
        // 國圖有結果就不必再打 OpenLibrary
        let paths: Vec<String> =
            server.received_requests().await.unwrap().iter().map(|r| r.url.path().to_string()).collect();
        assert!(!paths.iter().any(|p| p.contains("openlibrary")));
    }

    #[tokio::test]
    async fn books_search_external_google_429_要回報而不是當成查無此書() {
        // 2026-10 的實況:沒帶 key 時 Google Books 對每個 ISBN 都回 429,body 是合法 JSON 但沒有 items。
        // 以前那會被當成「查無結果」,後台只看到空清單。
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/google-books/books/v1/volumes"))
            .respond_with(ResponseTemplate::new(429).set_body_json(json!({
                "error": { "code": 429, "errors": [{ "reason": "rateLimitExceeded" }] }
            })))
            .mount(&server)
            .await;
        Mock::given(method("GET"))
            .and(path("/openlibrary/api/books"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "ISBN:9789573267478": { "title": "補位找到的書" }
            })))
            .mount(&server)
            .await;
        let st = state_with_mock(&server).await;

        let v = body_of(
            books_search_external(
                axum::extract::State(st),
                axum::extract::Query(BookSearchQuery { query: None, isbn: Some("9789573267478".into()) }),
            )
            .await,
        )
        .await;
        let w = v["warnings"].as_array().unwrap();
        assert_eq!(w.len(), 1, "Google 失敗要留下一筆 warning:{v}");
        let msg = w[0].as_str().unwrap();
        assert!(msg.contains("額度") && msg.contains("rateLimitExceeded"), "訊息要講出原因:{msg}");
        assert_eq!(v["books"][0]["title"], "補位找到的書", "Google 失敗仍要退回 OpenLibrary");
    }

    #[tokio::test]
    async fn books_search_external_有設_key_就帶上() {
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/google-books/books/v1/volumes"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({ "items": [] })))
            .mount(&server)
            .await;
        Mock::given(method("GET"))
            .and(path("/openlibrary/search.json"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({ "docs": [] })))
            .mount(&server)
            .await;
        let st = state_with_mock(&server).await;
        // SAFETY: nextest 一個測試一個行程,不會跟別的測試搶 env。
        unsafe { std::env::set_var("GOOGLE_BOOKS_API_KEY", "test-key") };
        let _ = books_search_external(
            axum::extract::State(st),
            axum::extract::Query(BookSearchQuery { query: Some("任何書".into()), isbn: None }),
        )
        .await;
        // SAFETY: 同上。
        unsafe { std::env::remove_var("GOOGLE_BOOKS_API_KEY") };
        let reqs = server.received_requests().await.unwrap();
        let google = reqs.iter().find(|r| r.url.path().contains("volumes")).expect("該打 Google Books");
        let key = google.url.query_pairs().find(|(k, _)| k == "key").map(|(_, v)| v.into_owned());
        assert_eq!(key.as_deref(), Some("test-key"));
    }

    // ── Steam miniprofile 的 HTML 爬取 ────────────────────────────────────
    //
    // 五條 regex 在刮 Steam 的頁面。Steam 改版或 regex 寫歪的話,個人檔案只會靜靜地
    // 少掉頭像框/名牌/徽章——沒有錯誤、沒有 log,而且沒有人會注意到。

    /// 形狀取自實際的 miniprofile 頁面(屬性順序與換行都照原樣)。
    const MINI_PROFILE_HTML: &str = r#"
<div class="miniprofile_nameplate_container">
  <video class="miniprofile_nameplate" autoplay loop muted playsinline poster="https://cdn/poster.png">
    <source src="https://cdn/nameplate.webm" type="video/webm">
    <source src="https://cdn/nameplate.mp4" type="video/mp4">
  </video>
</div>
<div class="playersection_avatar_frame">
  <img src="https://cdn/frame.png">
</div>
<div class="playersection_avatar has_frame">
  <img src="https://cdn/avatar.gif">
</div>
<div class="miniprofile_featuredcontainer">
  <img src="https://cdn/badge.png" class="badge_icon">
  <div class="description">
    <div class="name">  Steam 十週年  </div>
    <div class="xp">1,234 XP</div>
  </div>
</div>
"#;

    #[test]
    fn parse_mini_profile_刮得出五種客製() {
        let c = parse_mini_profile(MINI_PROFILE_HTML);
        assert_eq!(c.nameplate_webm.as_deref(), Some("https://cdn/nameplate.webm"));
        assert_eq!(c.nameplate_mp4.as_deref(), Some("https://cdn/nameplate.mp4"));
        assert_eq!(c.avatar_frame.as_deref(), Some("https://cdn/frame.png"));
        assert_eq!(
            c.animated_avatar.as_deref(),
            Some("https://cdn/avatar.gif"),
            "動態頭像不能抓到頭像框那張——兩個 class 名字只差一個底線"
        );
        let b = c.featured_badge.expect("展示徽章");
        assert_eq!(b.icon, "https://cdn/badge.png");
        assert_eq!(b.name, "Steam 十週年", "name 與 xp 都要 trim");
        assert_eq!(b.xp, "1,234 XP", "XP 是已格式化的字串不是數字");
    }

    #[test]
    fn parse_mini_profile_沒有客製時全部是_none() {
        // 大多數帳號長這樣。這條擋的是「regex 太寬鬆而抓到不相干的東西」。
        let plain = r#"<div class="miniprofile_container"><img src="https://cdn/plain.jpg"></div>"#;
        let c = parse_mini_profile(plain);
        assert!(c.nameplate_webm.is_none());
        assert!(c.nameplate_mp4.is_none());
        assert!(c.avatar_frame.is_none());
        assert!(c.animated_avatar.is_none());
        assert!(c.featured_badge.is_none());

        let c = parse_mini_profile("");
        assert!(c.animated_avatar.is_none(), "空字串要早退,不是丟給 regex");
    }

    #[test]
    fn parse_mini_profile_只有部分客製時其餘保持_none() {
        // 只有頭像框沒有名牌——很常見的組合。全有或全無的實作會在這裡露餡。
        let only_frame = r#"<div class="playersection_avatar_frame">
  <img src="https://cdn/only-frame.png">
</div>"#;
        let c = parse_mini_profile(only_frame);
        assert_eq!(c.avatar_frame.as_deref(), Some("https://cdn/only-frame.png"));
        assert!(c.nameplate_webm.is_none());
        assert!(c.featured_badge.is_none());

        // 名牌只有 webm 沒有 mp4(Steam 上真的有這種)
        let webm_only = r#"<video class="miniprofile_nameplate" autoplay>
  <source src="https://cdn/a.webm" type="video/webm">
</video>"#;
        let c = parse_mini_profile(webm_only);
        assert_eq!(c.nameplate_webm.as_deref(), Some("https://cdn/a.webm"));
        assert!(c.nameplate_mp4.is_none(), "沒有 mp4 就是 None,不要退回 webm 那條");
    }

    #[test]
    fn parse_mini_profile_的名牌來源只從_video_區塊內找() {
        // 頁面別處也可能有 .mp4 的連結;抓錯範圍會把不相干的影片當成名牌。
        let html = r#"
<a href="https://cdn/unrelated.mp4">別的影片</a>
<video class="miniprofile_nameplate" autoplay>
  <source src="https://cdn/real-nameplate.mp4" type="video/mp4">
</video>"#;
        let c = parse_mini_profile(html);
        assert_eq!(
            c.nameplate_mp4.as_deref(),
            Some("https://cdn/real-nameplate.mp4"),
            "要從 <video> 區塊裡找,不是整頁亂抓"
        );
    }

    #[tokio::test]
    async fn books_search_external_google_空手時退到_openlibrary() {
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/google-books/books/v1/volumes"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({ "items": [] })))
            .mount(&server)
            .await;
        Mock::given(method("GET"))
            .and(path("/openlibrary/search.json"))
            .and(query_param("q", "冷門書"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "docs": [{
                    "title": "冷門書",
                    "author_name": ["某人"],
                    "first_publish_year": 1999,
                    "number_of_pages_median": 250,
                }]
            })))
            .mount(&server)
            .await;
        let st = state_with_mock(&server).await;

        let v = body_of(
            books_search_external(
                axum::extract::State(st),
                axum::extract::Query(BookSearchQuery { query: Some("冷門書".into()), isbn: None }),
            )
            .await,
        )
        .await;
        let books = v["books"].as_array().unwrap();
        assert_eq!(books.len(), 1, "Google 沒結果就該換 OpenLibrary");
        assert_eq!(books[0]["title"], "冷門書");
        assert_eq!(books[0]["source"], "openlibrary");
        assert_eq!(books[0]["page_count"], 250);
    }

    /// OpenLibrary 的 **ISBN 分支走完全不同的端點與回應形狀**(`/api/books` 而不是
    /// `/search.json`,資料包在 `"ISBN:<號碼>"` 這個 key 底下)。同一支函式兩條路,
    /// 只測其中一條等於沒測到另一條——而 ISBN 查詢正是新增書籍最常走的那條。
    #[tokio::test]
    async fn books_search_external_的_isbn_走_openlibrary_的另一支端點() {
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/google-books/books/v1/volumes"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({ "items": [] })))
            .mount(&server)
            .await;
        Mock::given(method("GET"))
            .and(path("/openlibrary/api/books"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "ISBN:9781234567890": {
                    "title": "以 ISBN 查到的書",
                    "authors": [{ "name": "作者甲" }, { "name": "作者乙" }],
                    "publishers": [{ "name": "某出版社" }],
                    "publish_date": "2020",
                    "number_of_pages": 512,
                    "cover": { "medium": "https://covers.openlibrary.org/m.jpg" },
                    "subjects": [
                        { "name": "分類一" }, { "name": "分類二" }, { "name": "分類三" },
                        { "name": "分類四" }, { "name": "分類五" }, { "name": "第六個不該出現" },
                    ],
                    "excerpts": [{ "text": "摘錄的內容" }],
                }
            })))
            .mount(&server)
            .await;

        let st = state_with_mock(&server).await;
        let v = body_of(
            books_search_external(
                axum::extract::State(st),
                axum::extract::Query(BookSearchQuery { query: None, isbn: Some("978-1-234-56789-0".into()) }),
            )
            .await,
        )
        .await;
        let b = &v["books"][0];
        assert_eq!(b["isbn"], "9781234567890", "連字號要去掉才對得上回應的 key");
        assert_eq!(b["title"], "以 ISBN 查到的書");
        assert_eq!(b["authors"], "作者甲, 作者乙", "這裡的作者是物件陣列不是字串陣列");
        assert_eq!(b["publisher"], "某出版社");
        assert_eq!(b["page_count"], 512);
        assert_eq!(b["cover_url"], "https://covers.openlibrary.org/m.jpg", "large 沒有就退 medium");
        assert_eq!(b["description"], "摘錄的內容", "沒有 notes 時退到 excerpts[0].text");
        // 註:`notes` 是**空字串**時也要退到 excerpts,見下面那條測試。
        assert_eq!(b["categories"], "分類一, 分類二, 分類三, 分類四, 分類五", "分類只取前五個");
        assert_eq!(b["source"], "openlibrary");
    }

    /// `notes` 是**空字串**時要當成沒有,退到 excerpts。
    ///
    /// 這條是 `cargo mutants` 指出來的:把 `.filter(|s| !s.is_empty())` 的驚嘆號刪掉
    /// 測試照樣全綠,因為既有的案例裡 notes 根本不存在(走的是 `and_then` 的 None 那側)。
    /// OpenLibrary 實際上很常回空字串,那時書籍簡介會整個變空白。
    #[tokio::test]
    async fn books_search_external_的_notes_是空字串時退到_excerpts() {
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/google-books/books/v1/volumes"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({ "items": [] })))
            .mount(&server)
            .await;
        Mock::given(method("GET"))
            .and(path("/openlibrary/api/books"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "ISBN:9781234567890": {
                    "title": "有空 notes 的書",
                    "notes": "",
                    "excerpts": [{ "text": "退而求其次的簡介" }],
                }
            })))
            .mount(&server)
            .await;

        let st = state_with_mock(&server).await;
        let v = body_of(
            books_search_external(
                axum::extract::State(st),
                axum::extract::Query(BookSearchQuery { query: None, isbn: Some("9781234567890".into()) }),
            )
            .await,
        )
        .await;
        assert_eq!(v["books"][0]["description"], "退而求其次的簡介", "空字串的 notes 不算有值");
    }

    #[tokio::test]
    async fn books_search_external_的_isbn_查不到時回空清單而不是報錯() {
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/google-books/books/v1/volumes"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({ "items": [] })))
            .mount(&server)
            .await;
        // OpenLibrary 查不到時回的是 `{}`,不是 404
        Mock::given(method("GET"))
            .and(path("/openlibrary/api/books"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({})))
            .mount(&server)
            .await;

        let st = state_with_mock(&server).await;
        let v = body_of(
            books_search_external(
                axum::extract::State(st),
                axum::extract::Query(BookSearchQuery { query: None, isbn: Some("9789999999999".into()) }),
            )
            .await,
        )
        .await;
        assert_eq!(v["message"], "success", "查不到不是錯誤");
        assert_eq!(v["books"].as_array().unwrap().len(), 0);
    }
}