refactor: 资源拆分

src/auth.py

@@ -0,0 +1,105 @@
+"""认证与 Session 管理模块。"""
+
+from __future__ import annotations
+
+import logging
+import os
+import secrets
+import uuid
+from typing import Optional
+
+import bcrypt
+from fastapi import HTTPException, Request
+from itsdangerous import BadSignature, SignatureExpired, TimestampSigner
+
+# 保持与原实现一致的常量和日志名称
+logger = logging.getLogger("gateway")
+
+
+# ── Session 配置 ───────────────────────────────────────────────────────────────
+SESSION_COOKIE = "gw_session"
+SESSION_MAX_AGE = 86400  # 24 hours
+
+SECRET_KEY = os.environ.get("SESSION_SECRET") or secrets.token_hex(32)
+signer = TimestampSigner(SECRET_KEY)
+
+INTERNAL_KEY_SALT = (os.environ.get("INTERNAL_KEY_SALT") or SECRET_KEY).strip()
+
+
+# ── 用户加载与认证 ────────────────────────────────────────────────────────────
+def _load_users() -> dict[str, str]:
+    """从 BASIC_AUTH_USERS 加载用户名密码。"""
+    raw = os.environ.get("BASIC_AUTH_USERS", "").replace("\\n", "\n")
+    users: dict[str, str] = {}
+    for line in raw.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if ":" not in line:
+            logger.warning("Skipping invalid BASIC_AUTH_USERS line (no colon)")
+            continue
+        username, password = line.split(":", 1)
+        username = username.strip()
+        password = password.strip()
+        if username and password:
+            users[username] = password
+    if not users:
+        logger.error("No valid users found — authentication will always fail")
+    return users
+
+
+USERS = _load_users()
+INTERNAL_KEY_NAMESPACE = uuid.uuid5(uuid.NAMESPACE_DNS, INTERNAL_KEY_SALT)
+
+
+def _make_internal_api_key(username: str) -> str:
+    """基于用户名生成稳定内部 Key（仅服务端使用）。"""
+    value = uuid.uuid5(INTERNAL_KEY_NAMESPACE, username)
+    return f"sk-{value}"
+
+
+INTERNAL_KEY_TO_USER = {
+    _make_internal_api_key(username): username for username in USERS.keys()
+}
+
+
+def _verify_credentials(username: str, password: str) -> bool:
+    """验证用户名密码，支持明文与 bcrypt。"""
+    stored = USERS.get(username)
+    if stored is None:
+        return False
+    if stored.startswith("$2"):
+        return bcrypt.checkpw(password.encode(), stored.encode())
+    return secrets.compare_digest(stored, password)
+
+
+# ── Session ──────────────────────────────────────────────────────────────────
+def _make_session(username: str) -> str:
+    """生成签名的 Session token。"""
+    return signer.sign(username).decode()
+
+
+def _verify_session(token: str) -> Optional[str]:
+    """验证 Session token，返回用户名或 None。"""
+    try:
+        username = signer.unsign(token, max_age=SESSION_MAX_AGE).decode()
+    except (BadSignature, SignatureExpired):
+        return None
+    if username not in USERS:
+        return None
+    return username
+
+
+def _get_session_user(request: Request) -> Optional[str]:
+    """从请求 Cookie 中解析当前用户。"""
+    token = request.cookies.get(SESSION_COOKIE)
+    return _verify_session(token) if token else None
+
+
+def _require_user(request: Request) -> str:
+    """FastAPI 依赖：要求用户已登录，否则抛出 401。"""
+    username = _get_session_user(request)
+    if not username:
+        raise HTTPException(status_code=401, detail="Unauthorized")
+    return username
+

src/billing.py

@@ -0,0 +1,118 @@
+"""计费逻辑与 usage_records 持久化。"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import storage
+
+
+# 价格单位：USD / 1M tokens
+DEFAULT_INPUT_PRICE_PER_1M = float(
+    os.environ.get("OPENAI_DEFAULT_INPUT_PRICE_PER_1M", "0.15")
+)
+DEFAULT_OUTPUT_PRICE_PER_1M = float(
+    os.environ.get("OPENAI_DEFAULT_OUTPUT_PRICE_PER_1M", "0.60")
+)
+MODEL_PRICES_PER_1M: dict[str, tuple[float, float]] = {
+    "gpt-4o-mini": (0.15, 0.60),
+    "gpt-4.1-mini": (0.40, 1.60),
+    "gpt-4.1": (2.00, 8.00),
+    "gpt-4o": (2.50, 10.00),
+}
+
+
+def calc_cost_usd(model: str, prompt_tokens: int, completion_tokens: int) -> float:
+    """计算一次请求的美元成本。"""
+    model_rates = MODEL_PRICES_PER_1M.get(model, None)
+    if model_rates is None:
+        in_rate = DEFAULT_INPUT_PRICE_PER_1M
+        out_rate = DEFAULT_OUTPUT_PRICE_PER_1M
+    else:
+        in_rate, out_rate = model_rates
+
+    cost = (prompt_tokens * in_rate + completion_tokens * out_rate) / 1_000_000.0
+    return round(cost, 8)
+
+
+def record_usage(
+    *,
+    username: str,
+    job_id: str | None,
+    model: str,
+    prompt_tokens: int,
+    completion_tokens: int,
+    total_tokens: int,
+) -> None:
+    """记录一次模型调用的 token 使用情况与成本。"""
+    cost_usd = calc_cost_usd(model, prompt_tokens, completion_tokens)
+    storage.db_execute(
+        """
+        INSERT INTO usage_records(
+            username, job_id, model,
+            prompt_tokens, completion_tokens, total_tokens,
+            cost_usd, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        """,
+        (
+            username,
+            job_id,
+            model,
+            prompt_tokens,
+            completion_tokens,
+            total_tokens,
+            cost_usd,
+            storage.now_iso(),
+        ),
+    )
+
+
+def get_billing_summary(username: str) -> dict[str, Any]:
+    """汇总某个用户的累计账单信息。"""
+    row = storage.db_fetchone(
+        """
+        SELECT
+            COALESCE(SUM(prompt_tokens), 0) AS prompt_tokens,
+            COALESCE(SUM(completion_tokens), 0) AS completion_tokens,
+            COALESCE(SUM(total_tokens), 0) AS total_tokens,
+            COALESCE(SUM(cost_usd), 0) AS total_cost_usd
+        FROM usage_records
+        WHERE username = ?
+        """,
+        (username,),
+    )
+    if row is None:
+        return {
+            "username": username,
+            "prompt_tokens": 0,
+            "completion_tokens": 0,
+            "total_tokens": 0,
+            "total_cost_usd": 0.0,
+        }
+    return {
+        "username": username,
+        "prompt_tokens": row["prompt_tokens"],
+        "completion_tokens": row["completion_tokens"],
+        "total_tokens": row["total_tokens"],
+        "total_cost_usd": round(float(row["total_cost_usd"]), 8),
+    }
+
+
+def get_billing_records(username: str, limit: int) -> list[dict[str, Any]]:
+    """获取用户近期账单记录。"""
+    rows = storage.db_fetchall(
+        """
+        SELECT
+            id, username, job_id, model,
+            prompt_tokens, completion_tokens, total_tokens,
+            cost_usd, created_at
+        FROM usage_records
+        WHERE username = ?
+        ORDER BY created_at DESC
+        LIMIT ?
+        """,
+        (username, limit),
+    )
+    return [dict(row) for row in rows]
+

src/gateway.py

@@ -6,29 +6,16 @@ from __future__ import annotations
 import asyncio
 import contextlib
 import html
-import json
 import logging
 import os
-import secrets
 import shutil
-import sqlite3
-import threading
 import uuid
-from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any
 
-import bcrypt
 import httpx
 from fastapi import Depends, FastAPI, File, Form, HTTPException, Request, UploadFile
-from fastapi.responses import (
-    FileResponse,
-    HTMLResponse,
-    JSONResponse,
-    RedirectResponse,
-    Response,
-)
-from itsdangerous import BadSignature, SignatureExpired, TimestampSigner
+from fastapi.responses import FileResponse, HTMLResponse, RedirectResponse, Response
 from pdf2zh_next import BasicSettings
 from pdf2zh_next import OpenAISettings
 from pdf2zh_next import PDFSettings
@@ -36,61 +23,24 @@ from pdf2zh_next import SettingsModel
 from pdf2zh_next import TranslationSettings
 from pdf2zh_next.high_level import do_translate_async_stream
 
-# ── 配置 ──────────────────────────────────────────────────────────────────────
-SESSION_COOKIE = "gw_session"
-SESSION_MAX_AGE = 86400  # 24 hours
-
-SECRET_KEY = os.environ.get("SESSION_SECRET") or secrets.token_hex(32)
-signer = TimestampSigner(SECRET_KEY)
+import auth
+import billing
+import jobs
+import proxy
+import storage
+from web.template_loader import get_static_path, load_template
 
-DATA_DIR = Path(os.environ.get("DATA_DIR", "/data"))
-UPLOAD_DIR = DATA_DIR / "uploads"
-JOB_DIR = DATA_DIR / "jobs"
-DB_PATH = DATA_DIR / "gateway.db"
+# ── 配置 ──────────────────────────────────────────────────────────────────────
 
 INTERNAL_OPENAI_BASE_URL = os.environ.get(
     "INTERNAL_OPENAI_BASE_URL", "http://127.0.0.1:7860/internal/openai/v1"
 )
-OPENAI_UPSTREAM_CHAT_URL = os.environ.get(
-    "OPENAI_UPSTREAM_CHAT_URL", "https://api.openai.com/v1/chat/completions"
-)
-OPENAI_REAL_API_KEY = os.environ.get("OPENAI_API_KEY", "").strip()
 
 FIXED_TRANSLATION_MODEL = "SiliconFlowFree"
 DEFAULT_LANG_IN = os.environ.get("DEFAULT_LANG_IN", "en").strip()
 DEFAULT_LANG_OUT = os.environ.get("DEFAULT_LANG_OUT", "zh").strip()
 TRANSLATION_QPS = int(os.environ.get("TRANSLATION_QPS", "4"))
 
-INTERNAL_KEY_SALT = (os.environ.get("INTERNAL_KEY_SALT") or SECRET_KEY).strip()
-
-# 模型路由表：模型名 -> 上游配置
-MODEL_ROUTE_TABLE: dict[str, dict[str, Any]] = {
-    "SiliconFlowFree": {
-        "route_type": "chatproxy",
-        "base_urls": [
-            "https://api1.pdf2zh-next.com/chatproxy",
-            "https://api2.pdf2zh-next.com/chatproxy",
-        ],
-        "api_key": "",
-    }
-}
-
-# 价格单位：USD / 1M tokens
-DEFAULT_INPUT_PRICE_PER_1M = float(
-    os.environ.get("OPENAI_DEFAULT_INPUT_PRICE_PER_1M", "0.15")
-)
-DEFAULT_OUTPUT_PRICE_PER_1M = float(
-    os.environ.get("OPENAI_DEFAULT_OUTPUT_PRICE_PER_1M", "0.60")
-)
-MODEL_PRICES_PER_1M: dict[str, tuple[float, float]] = {
-    "gpt-4o-mini": (0.15, 0.60),
-    "gpt-4.1-mini": (0.40, 1.60),
-    "gpt-4.1": (2.00, 8.00),
-    "gpt-4o": (2.50, 10.00),
-}
-
-LOCALHOSTS = frozenset({"127.0.0.1", "::1", "localhost"})
-
 logging.basicConfig(
     level=logging.INFO,
     format="%(asctime)s %(levelname)s %(name)s - %(message)s",
@@ -98,202 +48,6 @@ logging.basicConfig(
 logger = logging.getLogger("gateway")
 
 
-# ── 用户加载与认证 ────────────────────────────────────────────────────────────
-def _load_users() -> dict[str, str]:
-    """从 BASIC_AUTH_USERS 加载用户名密码。"""
-    raw = os.environ.get("BASIC_AUTH_USERS", "").replace("\\n", "\n")
-    users: dict[str, str] = {}
-    for line in raw.splitlines():
-        line = line.strip()
-        if not line or line.startswith("#"):
-            continue
-        if ":" not in line:
-            logger.warning("Skipping invalid BASIC_AUTH_USERS line (no colon)")
-            continue
-        username, password = line.split(":", 1)
-        username = username.strip()
-        password = password.strip()
-        if username and password:
-            users[username] = password
-    if not users:
-        logger.error("No valid users found — authentication will always fail")
-    return users
-
-
-USERS = _load_users()
-INTERNAL_KEY_NAMESPACE = uuid.uuid5(uuid.NAMESPACE_DNS, INTERNAL_KEY_SALT)
-
-
-def _make_internal_api_key(username: str) -> str:
-    """基于用户名生成稳定内部 Key（仅服务端使用）。"""
-    value = uuid.uuid5(INTERNAL_KEY_NAMESPACE, username)
-    return f"sk-{value}"
-
-
-INTERNAL_KEY_TO_USER = {
-    _make_internal_api_key(username): username for username in USERS.keys()
-}
-
-
-def _verify_credentials(username: str, password: str) -> bool:
-    """验证用户名密码，支持明文与 bcrypt。"""
-    stored = USERS.get(username)
-    if stored is None:
-        return False
-    if stored.startswith("$2"):
-        return bcrypt.checkpw(password.encode(), stored.encode())
-    return secrets.compare_digest(stored, password)
-
-
-# ── Session ──────────────────────────────────────────────────────────────────
-def _make_session(username: str) -> str:
-    return signer.sign(username).decode()
-
-
-def _verify_session(token: str) -> Optional[str]:
-    try:
-        username = signer.unsign(token, max_age=SESSION_MAX_AGE).decode()
-    except (BadSignature, SignatureExpired):
-        return None
-    if username not in USERS:
-        return None
-    return username
-
-
-def _get_session_user(request: Request) -> Optional[str]:
-    token = request.cookies.get(SESSION_COOKIE)
-    return _verify_session(token) if token else None
-
-
-def _require_user(request: Request) -> str:
-    username = _get_session_user(request)
-    if not username:
-        raise HTTPException(status_code=401, detail="Unauthorized")
-    return username
-
-
-# ── 存储层 ───────────────────────────────────────────────────────────────────
-_db_lock = threading.Lock()
-_db_conn: sqlite3.Connection | None = None
-
-
-def _now_iso() -> str:
-    return datetime.now(timezone.utc).isoformat()
-
-
-def _ensure_data_dirs() -> None:
-    UPLOAD_DIR.mkdir(parents=True, exist_ok=True)
-    JOB_DIR.mkdir(parents=True, exist_ok=True)
-
-
-def _init_db() -> None:
-    global _db_conn
-    _ensure_data_dirs()
-    conn = sqlite3.connect(DB_PATH, check_same_thread=False)
-    conn.row_factory = sqlite3.Row
-    with conn:
-        conn.execute(
-            """
-            CREATE TABLE IF NOT EXISTS jobs (
-                id TEXT PRIMARY KEY,
-                username TEXT NOT NULL,
-                filename TEXT NOT NULL,
-                input_path TEXT NOT NULL,
-                output_dir TEXT NOT NULL,
-                status TEXT NOT NULL,
-                progress REAL NOT NULL DEFAULT 0,
-                message TEXT,
-                error TEXT,
-                model TEXT NOT NULL,
-                lang_in TEXT NOT NULL,
-                lang_out TEXT NOT NULL,
-                cancel_requested INTEGER NOT NULL DEFAULT 0,
-                mono_pdf_path TEXT,
-                dual_pdf_path TEXT,
-                glossary_path TEXT,
-                created_at TEXT NOT NULL,
-                updated_at TEXT NOT NULL,
-                started_at TEXT,
-                finished_at TEXT
-            )
-            """
-        )
-        conn.execute(
-            """
-            CREATE TABLE IF NOT EXISTS usage_records (
-                id INTEGER PRIMARY KEY AUTOINCREMENT,
-                username TEXT NOT NULL,
-                job_id TEXT,
-                model TEXT NOT NULL,
-                prompt_tokens INTEGER NOT NULL,
-                completion_tokens INTEGER NOT NULL,
-                total_tokens INTEGER NOT NULL,
-                cost_usd REAL NOT NULL,
-                created_at TEXT NOT NULL
-            )
-            """
-        )
-        conn.execute(
-            """
-            CREATE INDEX IF NOT EXISTS idx_jobs_user_time
-            ON jobs(username, created_at DESC)
-            """
-        )
-        conn.execute(
-            """
-            CREATE INDEX IF NOT EXISTS idx_usage_user_time
-            ON usage_records(username, created_at DESC)
-            """
-        )
-    _db_conn = conn
-
-
-def _db_execute(sql: str, params: tuple[Any, ...] = ()) -> None:
-    if _db_conn is None:
-        raise RuntimeError("DB is not initialized")
-    with _db_lock, _db_conn:
-        _db_conn.execute(sql, params)
-
-
-def _db_fetchone(sql: str, params: tuple[Any, ...] = ()) -> sqlite3.Row | None:
-    if _db_conn is None:
-        raise RuntimeError("DB is not initialized")
-    with _db_lock:
-        return _db_conn.execute(sql, params).fetchone()
-
-
-def _db_fetchall(sql: str, params: tuple[Any, ...] = ()) -> list[sqlite3.Row]:
-    if _db_conn is None:
-        raise RuntimeError("DB is not initialized")
-    with _db_lock:
-        return _db_conn.execute(sql, params).fetchall()
-
-
-def _update_job(job_id: str, **fields: Any) -> None:
-    if not fields:
-        return
-    fields["updated_at"] = _now_iso()
-    set_clause = ", ".join(f"{k} = ?" for k in fields.keys())
-    params = tuple(fields.values()) + (job_id,)
-    _db_execute(f"UPDATE jobs SET {set_clause} WHERE id = ?", params)
-
-
-def _row_to_job_dict(row: sqlite3.Row) -> dict[str, Any]:
-    job = dict(row)
-    job["artifact_urls"] = {
-        "mono": f"/api/jobs/{job['id']}/artifacts/mono"
-        if job.get("mono_pdf_path")
-        else None,
-        "dual": f"/api/jobs/{job['id']}/artifacts/dual"
-        if job.get("dual_pdf_path")
-        else None,
-        "glossary": f"/api/jobs/{job['id']}/artifacts/glossary"
-        if job.get("glossary_path")
-        else None,
-    }
-    return job
-
-
 # ── 任务执行 ───────────────────────────────────────────────────────────────────
 _job_queue: asyncio.Queue[str] = asyncio.Queue()
 _worker_task: asyncio.Task[None] | None = None
@@ -301,52 +55,9 @@ _running_tasks: dict[str, asyncio.Task[None]] = {}
 _active_job_by_user: dict[str, str] = {}
 
 
-def _calc_cost_usd(model: str, prompt_tokens: int, completion_tokens: int) -> float:
-    model_rates = MODEL_PRICES_PER_1M.get(model, None)
-    if model_rates is None:
-        in_rate = DEFAULT_INPUT_PRICE_PER_1M
-        out_rate = DEFAULT_OUTPUT_PRICE_PER_1M
-    else:
-        in_rate, out_rate = model_rates
-
-    cost = (prompt_tokens * in_rate + completion_tokens * out_rate) / 1_000_000.0
-    return round(cost, 8)
-
-
-def _record_usage(
-    *,
-    username: str,
-    job_id: str | None,
-    model: str,
-    prompt_tokens: int,
-    completion_tokens: int,
-    total_tokens: int,
-) -> None:
-    cost_usd = _calc_cost_usd(model, prompt_tokens, completion_tokens)
-    _db_execute(
-        """
-        INSERT INTO usage_records(
-            username, job_id, model,
-            prompt_tokens, completion_tokens, total_tokens,
-            cost_usd, created_at
-        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-        """,
-        (
-            username,
-            job_id,
-            model,
-            prompt_tokens,
-            completion_tokens,
-            total_tokens,
-            cost_usd,
-            _now_iso(),
-        ),
-    )
-
-
 def _build_settings_for_job(row: sqlite3.Row) -> SettingsModel:
     username = row["username"]
-    internal_key = _make_internal_api_key(username)
+    internal_key = auth._make_internal_api_key(username)
 
     settings = SettingsModel(
         basic=BasicSettings(debug=False, gui=False),
@@ -368,7 +79,7 @@ def _build_settings_for_job(row: sqlite3.Row) -> SettingsModel:
 
 
 async def _run_single_job(job_id: str) -> None:
-    row = _db_fetchone("SELECT * FROM jobs WHERE id = ?", (job_id,))
+    row = jobs.get_job_row(job_id)
     if row is None:
         return
     if row["status"] != "queued":
@@ -378,10 +89,10 @@ async def _run_single_job(job_id: str) -> None:
         return
 
     username = row["username"]
-    _update_job(
+    jobs.update_job(
         job_id,
         status="running",
-        started_at=_now_iso(),
+        started_at=storage.now_iso(),
         message="Translation started",
         progress=0.0,
     )
@@ -397,19 +108,19 @@ async def _run_single_job(job_id: str) -> None:
             if event_type in {"progress_start", "progress_update", "progress_end"}:
                 progress = float(event.get("overall_progress", 0.0))
                 stage = event.get("stage", "")
-                _update_job(
+                jobs.update_job(
                     job_id,
                     progress=max(0.0, min(100.0, progress)),
                     message=f"{stage}" if stage else "Running",
                 )
             elif event_type == "error":
                 error_msg = str(event.get("error", "Unknown translation error"))
-                _update_job(
+                jobs.update_job(
                     job_id,
                     status="failed",
                     error=error_msg,
                     message="Translation failed",
-                    finished_at=_now_iso(),
+                    finished_at=storage.now_iso(),
                 )
                 return
             elif event_type == "finish":
@@ -430,41 +141,41 @@ async def _run_single_job(job_id: str) -> None:
                         elif ".dual.pdf" in name and not dual_path:
                             dual_path = str(file)
 
-                _update_job(
+                jobs.update_job(
                     job_id,
                     status="succeeded",
                     progress=100.0,
                     message="Translation finished",
-                    finished_at=_now_iso(),
+                    finished_at=storage.now_iso(),
                     mono_pdf_path=mono_path or None,
                     dual_pdf_path=dual_path or None,
                     glossary_path=glossary_path or None,
                 )
                 return
 
-        _update_job(
+        jobs.update_job(
             job_id,
             status="failed",
             error="Translation stream ended unexpectedly",
             message="Translation failed",
-            finished_at=_now_iso(),
-        )
+            finished_at=storage.now_iso(),
+    )
     except asyncio.CancelledError:
-        _update_job(
+        jobs.update_job(
             job_id,
             status="cancelled",
             message="Cancelled by user",
-            finished_at=_now_iso(),
+            finished_at=storage.now_iso(),
         )
         raise
     except Exception as exc:  # noqa: BLE001
         logger.exception("Translation job failed: %s", job_id)
-        _update_job(
+        jobs.update_job(
             job_id,
             status="failed",
             error=str(exc),
             message="Translation failed",
-            finished_at=_now_iso(),
+            finished_at=storage.now_iso(),
         )
     finally:
         if _active_job_by_user.get(username) == job_id:
@@ -490,8 +201,8 @@ async def _job_worker() -> None:
 
 def _enqueue_pending_jobs() -> None:
     # 服务重启后，正在运行中的任务标记失败。
-    restart_time = _now_iso()
-    _db_execute(
+    restart_time = storage.now_iso()
+    storage.db_execute(
         """
         UPDATE jobs
         SET status='failed',
@@ -504,99 +215,18 @@ def _enqueue_pending_jobs() -> None:
         (restart_time, restart_time),
     )
 
-    rows = _db_fetchall(
+    rows = storage.db_fetchall(
         "SELECT id FROM jobs WHERE status='queued' ORDER BY created_at ASC"
     )
     for row in rows:
         _job_queue.put_nowait(row["id"])
 
 
-# ── 页面模板 ───────────────────────────────────────────────────────────────────
-_LOGIN_HTML = """\
-<!DOCTYPE html>
-<html lang="zh-CN">
-<head>
-<meta charset="UTF-8">
-<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>登录</title>
-<style>
-  *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
-  body {
-    min-height: 100vh;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    background: linear-gradient(135deg, #f0f2f5 0%, #e4e8f0 100%);
-    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
-  }
-  .card {
-    background: #fff;
-    border-radius: 14px;
-    box-shadow: 0 6px 32px rgba(0, 0, 0, 0.10);
-    padding: 44px 40px;
-    width: 100%;
-    max-width: 400px;
-  }
-  h1 { font-size: 1.5rem; font-weight: 700; color: #111827; margin-bottom: 6px; }
-  p.sub { font-size: 0.875rem; color: #6b7280; margin-bottom: 30px; }
-  label { display: block; font-size: 0.8rem; font-weight: 600; color: #374151; margin-bottom: 6px; }
-  input[type=text], input[type=password] {
-    width: 100%;
-    padding: 11px 14px;
-    border: 1.5px solid #e5e7eb;
-    border-radius: 8px;
-    font-size: 0.95rem;
-    outline: none;
-    transition: border-color 0.15s;
-    margin-bottom: 20px;
-    color: #111827;
-  }
-  input:focus { border-color: #4f6ef7; box-shadow: 0 0 0 3px rgba(79,110,247,0.12); }
-  button {
-    width: 100%;
-    padding: 12px;
-    background: linear-gradient(135deg, #4f6ef7 0%, #3b5bdb 100%);
-    color: #fff;
-    border: none;
-    border-radius: 8px;
-    font-size: 1rem;
-    font-weight: 600;
-    cursor: pointer;
-    transition: opacity 0.15s;
-  }
-  button:hover { opacity: 0.88; }
-  .error {
-    background: #fef2f2;
-    border: 1.5px solid #fecaca;
-    border-radius: 8px;
-    padding: 10px 14px;
-    font-size: 0.875rem;
-    color: #dc2626;
-    margin-bottom: 20px;
-  }
-</style>
-</head>
-<body>
-<div class="card">
-  <h1>欢迎回来</h1>
-  <p class="sub">请先登录后继续</p>
-  __ERROR_BLOCK__
-  <form method="post" action="/login">
-    <label for="u">用户名</label>
-    <input id="u" type="text" name="username" autocomplete="username" required autofocus>
-    <label for="p">密码</label>
-    <input id="p" type="password" name="password" autocomplete="current-password" required>
-    <button type="submit">登录</button>
-  </form>
-</div>
-</body>
-</html>
-"""
-
-
 def _login_page(error: str = "") -> str:
+    """渲染登录页 HTML。"""
+    tpl = load_template("login.html")
     error_block = f'<div class="error">{html.escape(error)}</div>' if error else ""
-    return _LOGIN_HTML.replace("__ERROR_BLOCK__", error_block)
+    return tpl.replace("__ERROR_BLOCK__", error_block)
 
 
 def _dashboard_page(username: str) -> str:
@@ -604,278 +234,12 @@ def _dashboard_page(username: str) -> str:
     safe_lang_in = html.escape(DEFAULT_LANG_IN)
     safe_lang_out = html.escape(DEFAULT_LANG_OUT)
 
-    return f"""<!DOCTYPE html>
-<html lang="zh-CN">
-<head>
-  <meta charset="UTF-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>PDF 翻译控制台</title>
-  <style>
-    :root {{
-      --bg: #f4f7fb;
-      --card: #ffffff;
-      --ink: #0f172a;
-      --sub: #475569;
-      --line: #dbe3ee;
-      --brand: #0f766e;
-      --brand-dark: #115e59;
-      --danger: #b91c1c;
-    }}
-    * {{ box-sizing: border-box; }}
-    body {{
-      margin: 0;
-      color: var(--ink);
-      background: radial-gradient(circle at 15% -20%, #d5f3ef 0, #f4f7fb 52%);
-      font-family: "Segoe UI", Tahoma, Geneva, Verdana, sans-serif;
-    }}
-    .wrap {{ max-width: 1100px; margin: 24px auto; padding: 0 16px 40px; }}
-    .top {{
-      display: flex;
-      align-items: center;
-      justify-content: space-between;
-      margin-bottom: 16px;
-    }}
-    h1 {{ margin: 0; font-size: 1.5rem; }}
-    .user {{ color: var(--sub); font-size: 0.95rem; }}
-    .grid {{ display: grid; grid-template-columns: 1fr 1fr; gap: 14px; }}
-    .card {{
-      background: var(--card);
-      border: 1px solid var(--line);
-      border-radius: 14px;
-      box-shadow: 0 10px 28px rgba(17, 24, 39, 0.06);
-      padding: 16px;
-    }}
-    .card h2 {{ margin: 0 0 10px; font-size: 1.03rem; }}
-    .row {{ display: grid; grid-template-columns: 1fr 1fr; gap: 10px; }}
-    label {{ display: block; margin: 10px 0 6px; font-size: 0.86rem; color: var(--sub); }}
-    input[type=text], select, input[type=file] {{
-      width: 100%; padding: 10px 12px; border-radius: 8px;
-      border: 1px solid var(--line); background: #fff; color: var(--ink);
-    }}
-    button {{
-      border: none; border-radius: 9px; padding: 10px 14px;
-      font-weight: 600; cursor: pointer;
-    }}
-    .primary {{ background: var(--brand); color: #fff; }}
-    .primary:hover {{ background: var(--brand-dark); }}
-    .muted {{ background: #e2e8f0; color: #0f172a; }}
-    .danger {{ background: #fee2e2; color: var(--danger); }}
-    .hint {{ margin-top: 8px; color: var(--sub); font-size: 0.84rem; }}
-    .status {{ margin-top: 10px; min-height: 22px; font-size: 0.9rem; }}
-    table {{ width: 100%; border-collapse: collapse; margin-top: 8px; font-size: 0.88rem; }}
-    th, td {{ border-bottom: 1px solid var(--line); text-align: left; padding: 8px 6px; }}
-    th {{ color: var(--sub); font-weight: 600; }}
-    .mono {{ font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 0.8rem; }}
-    .actions button {{ margin-right: 6px; margin-bottom: 4px; }}
-    .foot {{ margin-top: 20px; color: var(--sub); font-size: 0.82rem; }}
-    @media (max-width: 900px) {{
-      .grid {{ grid-template-columns: 1fr; }}
-      .row {{ grid-template-columns: 1fr; }}
-    }}
-  </style>
-</head>
-<body>
-<div class="wrap">
-  <div class="top">
-    <div>
-      <h1>PDF 翻译控制台</h1>
-      <div class="user">当前用户：<strong>{safe_user}</strong></div>
-    </div>
-    <div><a href="/logout"><button class="muted">退出登录</button></a></div>
-  </div>
-
-  <div class="grid">
-    <section class="card">
-      <h2>新建任务</h2>
-      <form id="jobForm">
-        <label>PDF 文件</label>
-        <input name="file" type="file" accept=".pdf" required />
-
-        <div class="row">
-          <div>
-            <label>源语言</label>
-            <input name="lang_in" type="text" value="{safe_lang_in}" required />
-          </div>
-          <div>
-            <label>目标语言</label>
-            <input name="lang_out" type="text" value="{safe_lang_out}" required />
-          </div>
-        </div>
-
-        <div style="margin-top: 12px;">
-          <button class="primary" type="submit">提交任务</button>
-        </div>
-      </form>
-      <div class="hint">模型由后台固定为 SiliconFlowFree，用户无需选择。</div>
-      <div id="jobStatus" class="status"></div>
-    </section>
-
-    <section class="card">
-      <h2>我的账单</h2>
-      <div id="billingSummary" class="mono">加载中...</div>
-      <table>
-        <thead>
-          <tr>
-            <th>时间 (UTC)</th>
-            <th>模型</th>
-            <th>输入</th>
-            <th>输出</th>
-            <th>总计</th>
-            <th>费用 (USD)</th>
-          </tr>
-        </thead>
-        <tbody id="billingBody"></tbody>
-      </table>
-    </section>
-  </div>
-
-  <section class="card" style="margin-top: 14px;">
-    <h2>我的任务</h2>
-    <table>
-      <thead>
-        <tr>
-          <th>ID</th>
-          <th>文件</th>
-          <th>状态</th>
-          <th>进度</th>
-          <th>模型</th>
-          <th>更新时间 (UTC)</th>
-          <th>操作</th>
-        </tr>
-      </thead>
-      <tbody id="jobsBody"></tbody>
-    </table>
-  </section>
-
-  <div class="foot">内部 OpenAI 接口仅允许 localhost 访问，不会直接暴露给终端用户。</div>
-</div>
-
-<script>
-async function apiJson(url, options = undefined) {{
-  const resp = await fetch(url, options);
-  if (!resp.ok) {{
-    const data = await resp.text();
-    throw new Error(data || `HTTP ${{resp.status}}`);
-  }}
-  return resp.json();
-}}
-
-function esc(s) {{
-  return String(s || "").replace(/[&<>"']/g, (c) => ({{
-    '&': '&amp;',
-    '<': '&lt;',
-    '>': '&gt;',
-    '"': '&quot;',
-    "'": '&#39;'
-  }})[c]);
-}}
-
-async function refreshBilling() {{
-  const summary = await apiJson('/api/billing/me');
-  const rows = await apiJson('/api/billing/me/records?limit=20');
-
-  document.getElementById('billingSummary').textContent =
-    `总 tokens=${{summary.total_tokens}} | 总费用(USD)=${{Number(summary.total_cost_usd).toFixed(6)}}`;
-
-  const body = document.getElementById('billingBody');
-  body.innerHTML = '';
-  for (const r of rows.records) {{
-    const tr = document.createElement('tr');
-    tr.innerHTML = `
-      <td>${{esc(r.created_at)}}</td>
-      <td class="mono">${{esc(r.model)}}</td>
-      <td>${{r.prompt_tokens}}</td>
-      <td>${{r.completion_tokens}}</td>
-      <td>${{r.total_tokens}}</td>
-      <td>${{Number(r.cost_usd).toFixed(6)}}</td>
-    `;
-    body.appendChild(tr);
-  }}
-}}
-
-function actionButtons(job) {{
-  const actions = [];
-  if (job.status === 'queued' || job.status === 'running') {{
-    actions.push(`<button class="danger" onclick="cancelJob('${{job.id}}')">取消</button>`);
-  }}
-  if (job.artifact_urls?.mono) {{
-    actions.push(`<a href="${{job.artifact_urls.mono}}"><button class="muted">单语版</button></a>`);
-  }}
-  if (job.artifact_urls?.dual) {{
-    actions.push(`<a href="${{job.artifact_urls.dual}}"><button class="muted">双语版</button></a>`);
-  }}
-  if (job.artifact_urls?.glossary) {{
-    actions.push(`<a href="${{job.artifact_urls.glossary}}"><button class="muted">术语表</button></a>`);
-  }}
-  return actions.join(' ');
-}}
-
-function statusText(status) {{
-  const statusMap = {{
-    queued: '排队中',
-    running: '进行中',
-    succeeded: '成功',
-    failed: '失败',
-    cancelled: '已取消'
-  }};
-  return statusMap[status] || status;
-}}
-
-async function refreshJobs() {{
-  const data = await apiJson('/api/jobs?limit=50');
-  const body = document.getElementById('jobsBody');
-  body.innerHTML = '';
-
-  for (const job of data.jobs) {{
-    const tr = document.createElement('tr');
-    tr.innerHTML = `
-      <td class="mono">${{esc(job.id)}}</td>
-      <td>${{esc(job.filename)}}</td>
-      <td>${{esc(statusText(job.status))}}${{job.error ? ' / ' + esc(job.error) : ''}}</td>
-      <td>${{Number(job.progress).toFixed(1)}}%</td>
-      <td class="mono">${{esc(job.model)}}</td>
-      <td class="mono">${{esc(job.updated_at)}}</td>
-      <td class="actions">${{actionButtons(job)}}</td>
-    `;
-    body.appendChild(tr);
-  }}
-}}
-
-async function cancelJob(jobId) {{
-  try {{
-    await apiJson(`/api/jobs/${{jobId}}/cancel`, {{ method: 'POST' }});
-    await refreshJobs();
-  }} catch (err) {{
-    alert(`取消失败: ${{err.message}}`);
-  }}
-}}
-
-document.getElementById('jobForm').addEventListener('submit', async (event) => {{
-  event.preventDefault();
-  const status = document.getElementById('jobStatus');
-  status.textContent = '提交中...';
-
-  const formData = new FormData(event.target);
-  try {{
-    const created = await apiJson('/api/jobs', {{ method: 'POST', body: formData }});
-    status.textContent = `任务已入队: ${{created.job.id}}`;
-    event.target.reset();
-    await refreshJobs();
-  }} catch (err) {{
-    status.textContent = `提交失败: ${{err.message}}`;
-  }}
-}});
-
-async function refreshAll() {{
-  await Promise.all([refreshJobs(), refreshBilling()]);
-}}
-
-refreshAll();
-setInterval(refreshAll, 3000);
-</script>
-</body>
-</html>
-"""
+    tpl = load_template("dashboard.html")
+    return (
+        tpl.replace("__USERNAME__", safe_user)
+        .replace("__LANG_IN__", safe_lang_in)
+        .replace("__LANG_OUT__", safe_lang_out)
+    )
 
 
 # ── FastAPI App ───────────────────────────────────────────────────────────────
@@ -887,18 +251,18 @@ _http_client: httpx.AsyncClient | None = None
 async def _startup() -> None:
     global _http_client, _worker_task
 
-    _init_db()
+    storage.init_db()
     _enqueue_pending_jobs()
 
     _http_client = httpx.AsyncClient(timeout=httpx.Timeout(180.0))
     _worker_task = asyncio.create_task(_job_worker(), name="job-worker")
 
-    if not OPENAI_REAL_API_KEY:
+    if not proxy.OPENAI_REAL_API_KEY:
         logger.info(
             "OPENAI_API_KEY is empty, non-routed OpenAI models will fail"
         )
 
-    logger.info("Gateway started. Data dir: %s", DATA_DIR)
+    logger.info("Gateway started. Data dir: %s", storage.DATA_DIR)
 
 
 @app.on_event("shutdown")
@@ -918,11 +282,10 @@ async def _shutdown() -> None:
         await _http_client.aclose()
         _http_client = None
 
-    if _db_conn:
-        _db_conn.close()
+    storage.close_db()
 
 
-# ── 路由：基础与认证 ───────────────────────────────────────────────────────────
+# ── 路由：基础与认证（当前 Space 原型，不保证向后兼容） ─────────────────────
 @app.get("/healthz")
 async def healthz() -> Response:
     return Response("ok", media_type="text/plain")
@@ -930,7 +293,7 @@ async def healthz() -> Response:
 
 @app.get("/login", response_class=HTMLResponse)
 async def login_page(request: Request) -> HTMLResponse:
-    if _get_session_user(request):
+    if auth._get_session_user(request):
         return RedirectResponse("/", status_code=302)
     return HTMLResponse(_login_page())
 
@@ -942,13 +305,13 @@ async def login(
     password: str = Form(...),
 ) -> Response:
     next_url = request.query_params.get("next", "/")
-    if _verify_credentials(username, password):
-        token = _make_session(username)
+    if auth._verify_credentials(username, password):
+        token = auth._make_session(username)
         resp = RedirectResponse(next_url, status_code=303)
         resp.set_cookie(
-            SESSION_COOKIE,
+            auth.SESSION_COOKIE,
             token,
-            max_age=SESSION_MAX_AGE,
+            max_age=auth.SESSION_MAX_AGE,
             httponly=True,
             samesite="lax",
         )
@@ -962,13 +325,14 @@ async def login(
 @app.get("/logout")
 async def logout() -> Response:
     resp = RedirectResponse("/login", status_code=302)
-    resp.delete_cookie(SESSION_COOKIE)
+    resp.delete_cookie(auth.SESSION_COOKIE)
     return resp
 
 
+# ── 路由：页面渲染（HTML） ────────────────────────────────────────────────────
 @app.get("/", response_class=HTMLResponse)
 async def index(request: Request) -> Response:
-    username = _get_session_user(request)
+    username = auth._get_session_user(request)
     if not username:
         return RedirectResponse("/login", status_code=302)
     return HTMLResponse(_dashboard_page(username))
@@ -976,37 +340,29 @@ async def index(request: Request) -> Response:
 
 # ── 路由：任务 API ─────────────────────────────────────────────────────────────
 @app.get("/api/me")
-async def api_me(username: str = Depends(_require_user)) -> dict[str, str]:
+async def api_me(username: str = Depends(auth._require_user)) -> dict[str, str]:
     return {"username": username}
 
 
 @app.get("/api/jobs")
 async def api_list_jobs(
     limit: int = 50,
-    username: str = Depends(_require_user),
+    username: str = Depends(auth._require_user),
 ) -> dict[str, Any]:
     limit = max(1, min(limit, 200))
-    rows = _db_fetchall(
-        """
-        SELECT * FROM jobs
-        WHERE username = ?
-        ORDER BY created_at DESC
-        LIMIT ?
-        """,
-        (username, limit),
-    )
-    return {"jobs": [_row_to_job_dict(row) for row in rows]}
+    jobs_list = jobs.get_jobs_for_user(username=username, limit=limit)
+    return {"jobs": jobs_list}
 
 
 @app.get("/api/jobs/{job_id}")
-async def api_get_job(job_id: str, username: str = Depends(_require_user)) -> dict[str, Any]:
-    row = _db_fetchone(
-        "SELECT * FROM jobs WHERE id = ? AND username = ?",
-        (job_id, username),
-    )
-    if row is None:
+async def api_get_job(
+    job_id: str,
+    username: str = Depends(auth._require_user),
+) -> dict[str, Any]:
+    job = jobs.get_job_for_user(job_id=job_id, username=username)
+    if job is None:
         raise HTTPException(status_code=404, detail="Job not found")
-    return {"job": _row_to_job_dict(row)}
+    return {"job": job}
 
 
 @app.post("/api/jobs")
@@ -1014,7 +370,7 @@ async def api_create_job(
     file: UploadFile = File(...),
     lang_in: str = Form(DEFAULT_LANG_IN),
     lang_out: str = Form(DEFAULT_LANG_OUT),
-    username: str = Depends(_require_user),
+    username: str = Depends(auth._require_user),
 ) -> dict[str, Any]:
     filename = file.filename or "input.pdf"
     if not filename.lower().endswith(".pdf"):
@@ -1022,8 +378,8 @@ async def api_create_job(
 
     job_id = uuid.uuid4().hex
     safe_filename = Path(filename).name
-    input_path = (UPLOAD_DIR / f"{job_id}.pdf").resolve()
-    output_dir = (JOB_DIR / job_id).resolve()
+    input_path = (storage.UPLOAD_DIR / f"{job_id}.pdf").resolve()
+    output_dir = (storage.JOB_DIR / job_id).resolve()
     output_dir.mkdir(parents=True, exist_ok=True)
 
     try:
@@ -1032,60 +388,42 @@ async def api_create_job(
     finally:
         await file.close()
 
-    now = _now_iso()
-    _db_execute(
-        """
-        INSERT INTO jobs(
-            id, username, filename, input_path, output_dir,
-            status, progress, message, error,
-            model, lang_in, lang_out,
-            cancel_requested,
-            created_at, updated_at
-        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-        """,
-        (
-            job_id,
-            username,
-            safe_filename,
-            str(input_path),
-            str(output_dir),
-            "queued",
-            0.0,
-            "Queued",
-            None,
-            FIXED_TRANSLATION_MODEL,
-            lang_in.strip() or DEFAULT_LANG_IN,
-            lang_out.strip() or DEFAULT_LANG_OUT,
-            0,
-            now,
-            now,
-        ),
+    job_dict = jobs.create_job_record(
+        job_id=job_id,
+        username=username,
+        filename=safe_filename,
+        input_path=input_path,
+        output_dir=output_dir,
+        model=FIXED_TRANSLATION_MODEL,
+        lang_in=lang_in.strip() or DEFAULT_LANG_IN,
+        lang_out=lang_out.strip() or DEFAULT_LANG_OUT,
     )
 
     await _job_queue.put(job_id)
-    row = _db_fetchone("SELECT * FROM jobs WHERE id = ?", (job_id,))
-    return {"job": _row_to_job_dict(row)}
+    return {"job": job_dict}
 
 
 @app.post("/api/jobs/{job_id}/cancel")
 async def api_cancel_job(
     job_id: str,
-    username: str = Depends(_require_user),
+    username: str = Depends(auth._require_user),
 ) -> dict[str, Any]:
-    row = _db_fetchone(
-        "SELECT * FROM jobs WHERE id = ? AND username = ?",
-        (job_id, username),
-    )
-    if row is None:
+    row = jobs.get_job_row(job_id)
+    if row is None or row["username"] != username:
         raise HTTPException(status_code=404, detail="Job not found")
 
     status = row["status"]
     if status in {"succeeded", "failed", "cancelled"}:
         return {"status": status, "message": "Job already finished"}
 
-    _update_job(job_id, cancel_requested=1, message="Cancel requested")
+    jobs.update_job(job_id, cancel_requested=1, message="Cancel requested")
     if status == "queued":
-        _update_job(job_id, status="cancelled", finished_at=_now_iso(), progress=0.0)
+        jobs.update_job(
+            job_id,
+            status="cancelled",
+            finished_at=storage.now_iso(),
+            progress=0.0,
+        )
         return {"status": "cancelled", "message": "Job cancelled"}
 
     task = _running_tasks.get(job_id)
@@ -1095,35 +433,15 @@ async def api_cancel_job(
     return {"status": "cancelling", "message": "Cancellation requested"}
 
 
-def _resolve_artifact_path(raw_path: str | None, output_dir: Path) -> Path | None:
-    if not raw_path:
-        return None
-    path = Path(raw_path)
-    if not path.is_absolute():
-        path = (output_dir / path).resolve()
-    else:
-        path = path.resolve()
-
-    if not path.exists():
-        return None
-
-    try:
-        path.relative_to(output_dir)
-    except ValueError:
-        return None
-    return path
-
-
 @app.get("/api/jobs/{job_id}/artifacts/{artifact_type}")
 async def api_download_artifact(
     job_id: str,
     artifact_type: str,
-    username: str = Depends(_require_user),
+    username: str = Depends(auth._require_user),
 ) -> Response:
-    row = _db_fetchone(
-        "SELECT * FROM jobs WHERE id = ? AND username = ?",
-        (job_id, username),
-    )
+    row = jobs.get_job_row(job_id)
+    if row is not None and row["username"] != username:
+        row = None
     if row is None:
         raise HTTPException(status_code=404, detail="Job not found")
 
@@ -1137,7 +455,7 @@ async def api_download_artifact(
         raise HTTPException(status_code=404, detail="Unknown artifact")
 
     output_dir = Path(row["output_dir"]).resolve()
-    path = _resolve_artifact_path(row[column], output_dir)
+    path = jobs.resolve_artifact_path(row[column], output_dir)
     if path is None:
         raise HTTPException(status_code=404, detail="Artifact not found")
 
@@ -1146,303 +464,30 @@ async def api_download_artifact(
 
 # ── 路由：计费 API ─────────────────────────────────────────────────────────────
 @app.get("/api/billing/me")
-async def api_billing_summary(username: str = Depends(_require_user)) -> dict[str, Any]:
-    row = _db_fetchone(
-        """
-        SELECT
-            COALESCE(SUM(prompt_tokens), 0) AS prompt_tokens,
-            COALESCE(SUM(completion_tokens), 0) AS completion_tokens,
-            COALESCE(SUM(total_tokens), 0) AS total_tokens,
-            COALESCE(SUM(cost_usd), 0) AS total_cost_usd
-        FROM usage_records
-        WHERE username = ?
-        """,
-        (username,),
-    )
-    return {
-        "username": username,
-        "prompt_tokens": row["prompt_tokens"],
-        "completion_tokens": row["completion_tokens"],
-        "total_tokens": row["total_tokens"],
-        "total_cost_usd": round(float(row["total_cost_usd"]), 8),
-    }
+async def api_billing_summary(
+    username: str = Depends(auth._require_user),
+) -> dict[str, Any]:
+    return billing.get_billing_summary(username)
 
 
 @app.get("/api/billing/me/records")
 async def api_billing_records(
     limit: int = 50,
-    username: str = Depends(_require_user),
+    username: str = Depends(auth._require_user),
 ) -> dict[str, Any]:
     limit = max(1, min(limit, 200))
-    rows = _db_fetchall(
-        """
-        SELECT
-            id, username, job_id, model,
-            prompt_tokens, completion_tokens, total_tokens,
-            cost_usd, created_at
-        FROM usage_records
-        WHERE username = ?
-        ORDER BY created_at DESC
-        LIMIT ?
-        """,
-        (username, limit),
-    )
-    return {
-        "records": [dict(row) for row in rows],
-    }
-
-
-# ── 路由：内部 OpenAI 兼容接口 ────────────────────────────────────────────────
-def _extract_bearer_token(request: Request) -> str:
-    header = request.headers.get("authorization", "")
-    if not header.lower().startswith("bearer "):
-        raise HTTPException(status_code=401, detail="Missing bearer token")
-    token = header[7:].strip()
-    if not token:
-        raise HTTPException(status_code=401, detail="Missing bearer token")
-    return token
-
-
-def _require_localhost(request: Request) -> None:
-    client = request.client
-    host = client.host if client else ""
-    if host not in LOCALHOSTS:
-        raise HTTPException(status_code=403, detail="Internal endpoint only")
-
-
-def _extract_text_from_message_content(content: Any) -> str:
-    if isinstance(content, str):
-        return content
-    if not isinstance(content, list):
-        return ""
-
-    parts: list[str] = []
-    for item in content:
-        if not isinstance(item, dict):
-            continue
-        if item.get("type") != "text":
-            continue
-        text = item.get("text")
-        if isinstance(text, str):
-            parts.append(text)
-    return "".join(parts)
-
-
-def _extract_text_from_messages(messages: Any) -> str:
-    if not isinstance(messages, list):
-        raise HTTPException(status_code=400, detail="messages must be a list")
-
-    for message in reversed(messages):
-        if not isinstance(message, dict):
-            continue
-        if message.get("role") != "user":
-            continue
-        text = _extract_text_from_message_content(message.get("content"))
-        if text:
-            return text
-
-    for message in reversed(messages):
-        if not isinstance(message, dict):
-            continue
-        text = _extract_text_from_message_content(message.get("content"))
-        if text:
-            return text
-
-    raise HTTPException(status_code=400, detail="messages does not contain text content")
-
-
-def _should_request_json_mode(payload: dict[str, Any]) -> bool:
-    response_format = payload.get("response_format")
-    if not isinstance(response_format, dict):
-        return False
-    return response_format.get("type") == "json_object"
-
-
-def _build_openai_compatible_response(model: str, content: str) -> dict[str, Any]:
-    return {
-        "id": f"chatcmpl-{uuid.uuid4().hex}",
-        "object": "chat.completion",
-        "created": int(datetime.now(timezone.utc).timestamp()),
-        "model": model,
-        "choices": [
-            {
-                "index": 0,
-                "message": {
-                    "role": "assistant",
-                    "content": content,
-                },
-                "finish_reason": "stop",
-            }
-        ],
-        "usage": {
-            "prompt_tokens": 0,
-            "completion_tokens": 0,
-            "total_tokens": 0,
-        },
-    }
-
-
-async def _forward_to_chatproxy(
-    payload: dict[str, Any],
-    model: str,
-    route: dict[str, Any],
-) -> dict[str, Any]:
-    if _http_client is None:
-        raise HTTPException(status_code=500, detail="HTTP client is not ready")
-
-    base_urls = route.get("base_urls", [])
-    if not isinstance(base_urls, list) or not base_urls:
-        raise HTTPException(status_code=500, detail=f"No upstream configured for model {model}")
-
-    request_json = {
-        "text": _extract_text_from_messages(payload.get("messages")),
-    }
-    if _should_request_json_mode(payload):
-        request_json["requestJsonMode"] = True
-
-    api_key = str(route.get("api_key") or "").strip()
-    headers = {"Content-Type": "application/json"}
-    if api_key:
-        headers["Authorization"] = f"Bearer {api_key}"
-
-    last_error = "No available upstream"
-    for base_url in base_urls:
-        try:
-            upstream = await _http_client.post(
-                str(base_url),
-                headers=headers,
-                json=request_json,
-            )
-        except httpx.HTTPError as exc:
-            last_error = str(exc)
-            logger.warning("chatproxy call failed: model=%s url=%s error=%s", model, base_url, exc)
-            continue
-
-        if upstream.status_code >= 400:
-            last_error = f"status={upstream.status_code}"
-            logger.warning(
-                "chatproxy upstream returned error: model=%s url=%s status=%s",
-                model,
-                base_url,
-                upstream.status_code,
-            )
-            continue
-
-        try:
-            body = upstream.json()
-        except Exception as exc:  # noqa: BLE001
-            last_error = f"invalid json response: {exc}"
-            logger.warning(
-                "chatproxy upstream returned invalid json: model=%s url=%s",
-                model,
-                base_url,
-            )
-            continue
-
-        content = body.get("content")
-        if not isinstance(content, str):
-            last_error = "missing content field"
-            logger.warning(
-                "chatproxy upstream missing content: model=%s url=%s body=%s",
-                model,
-                base_url,
-                body,
-            )
-            continue
-
-        return _build_openai_compatible_response(model=model, content=content)
-
-    raise HTTPException(
-        status_code=502,
-        detail=f"All chatproxy upstreams failed for model {model}: {last_error}",
-    )
-
-
 @app.post("/internal/openai/v1/chat/completions")
 async def internal_openai_chat_completions(request: Request) -> Response:
-    _require_localhost(request)
-    token = _extract_bearer_token(request)
-
-    username = INTERNAL_KEY_TO_USER.get(token)
-    if not username:
-        raise HTTPException(status_code=401, detail="Invalid internal API key")
-
-    try:
-        payload = await request.json()
-    except json.JSONDecodeError as exc:
-        raise HTTPException(status_code=400, detail=f"Invalid JSON body: {exc}") from exc
-
-    if payload.get("stream"):
-        raise HTTPException(status_code=400, detail="stream=true is not supported")
-
-    if _http_client is None:
-        raise HTTPException(status_code=500, detail="HTTP client is not ready")
-
-    model = str(payload.get("model") or "").strip()
-    if not model:
-        raise HTTPException(status_code=400, detail="model is required")
-
-    route = MODEL_ROUTE_TABLE.get(model)
-    if route and route.get("route_type") == "chatproxy":
-        response_json = await _forward_to_chatproxy(payload=payload, model=model, route=route)
-        _record_usage(
-            username=username,
-            job_id=_active_job_by_user.get(username),
-            model=model,
-            prompt_tokens=0,
-            completion_tokens=0,
-            total_tokens=0,
-        )
-        return JSONResponse(response_json, status_code=200)
-
-    if not OPENAI_REAL_API_KEY:
-        raise HTTPException(status_code=500, detail="OPENAI_API_KEY is not configured")
-
-    headers = {
-        "Authorization": f"Bearer {OPENAI_REAL_API_KEY}",
-        "Content-Type": "application/json",
-    }
-
-    try:
-        upstream = await _http_client.post(
-            OPENAI_UPSTREAM_CHAT_URL,
-            headers=headers,
-            json=payload,
-        )
-    except httpx.HTTPError as exc:
-        logger.error("Upstream OpenAI call failed: %s", exc)
-        raise HTTPException(status_code=502, detail="Upstream OpenAI request failed") from exc
-
-    response_json: dict[str, Any] | None = None
-    content_type = upstream.headers.get("content-type", "")
-    if "application/json" in content_type.lower():
-        try:
-            response_json = upstream.json()
-        except Exception:  # noqa: BLE001
-            response_json = None
-
-    if upstream.status_code < 400 and response_json is not None:
-        usage = response_json.get("usage") or {}
-        prompt_tokens = int(usage.get("prompt_tokens") or 0)
-        completion_tokens = int(usage.get("completion_tokens") or 0)
-        total_tokens = int(usage.get("total_tokens") or (prompt_tokens + completion_tokens))
-
-        job_id = _active_job_by_user.get(username)
-
-        _record_usage(
-            username=username,
-            job_id=job_id,
-            model=model,
-            prompt_tokens=prompt_tokens,
-            completion_tokens=completion_tokens,
-            total_tokens=total_tokens,
-        )
+    return await proxy.handle_internal_chat_completions(
+        request=request,
+        http_client=_http_client,
+        active_job_by_user=_active_job_by_user,
+    )
 
-    if response_json is not None:
-        return JSONResponse(response_json, status_code=upstream.status_code)
 
-    return Response(
-        content=upstream.content,
-        status_code=upstream.status_code,
-        media_type=content_type or None,
-    )
+# ── 路由：静态资源 ─────────────────────────────────────────────────────────────
+@app.get("/static/dashboard.js")
+async def dashboard_js() -> FileResponse:
+    """提供控制台前端脚本。"""
+    path = get_static_path("dashboard.js")
+    return FileResponse(path, media_type="application/javascript")

src/jobs.py

@@ -0,0 +1,135 @@
+"""任务相关的持久化操作与辅助函数。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import sqlite3
+
+import storage
+
+
+def row_to_job_dict(row: sqlite3.Row) -> dict[str, Any]:
+    """将任务行转换为对外暴露的字典结构。"""
+    job = dict(row)
+    job["artifact_urls"] = {
+        "mono": f"/api/jobs/{job['id']}/artifacts/mono"
+        if job.get("mono_pdf_path")
+        else None,
+        "dual": f"/api/jobs/{job['id']}/artifacts/dual"
+        if job.get("dual_pdf_path")
+        else None,
+        "glossary": f"/api/jobs/{job['id']}/artifacts/glossary"
+        if job.get("glossary_path")
+        else None,
+    }
+    return job
+
+
+def update_job(job_id: str, **fields: Any) -> None:
+    """更新任务记录指定字段。"""
+    if not fields:
+        return
+    fields["updated_at"] = storage.now_iso()
+    set_clause = ", ".join(f"{k} = ?" for k in fields.keys())
+    params = tuple(fields.values()) + (job_id,)
+    storage.db_execute(f"UPDATE jobs SET {set_clause} WHERE id = ?", params)
+
+
+def get_job_row(job_id: str) -> sqlite3.Row | None:
+    """按 ID 获取任务原始行。"""
+    return storage.db_fetchone("SELECT * FROM jobs WHERE id = ?", (job_id,))
+
+
+def get_job_for_user(job_id: str, username: str) -> dict[str, Any] | None:
+    """获取用户可见的任务，如果不存在或不属于该用户返回 None。"""
+    row = storage.db_fetchone(
+        "SELECT * FROM jobs WHERE id = ? AND username = ?",
+        (job_id, username),
+    )
+    if row is None:
+        return None
+    return row_to_job_dict(row)
+
+
+def get_jobs_for_user(username: str, limit: int) -> list[dict[str, Any]]:
+    """列出用户的任务列表，按创建时间倒序。"""
+    rows = storage.db_fetchall(
+        """
+        SELECT * FROM jobs
+        WHERE username = ?
+        ORDER BY created_at DESC
+        LIMIT ?
+        """,
+        (username, limit),
+    )
+    return [row_to_job_dict(row) for row in rows]
+
+
+def create_job_record(
+    *,
+    job_id: str,
+    username: str,
+    filename: str,
+    input_path: Path,
+    output_dir: Path,
+    model: str,
+    lang_in: str,
+    lang_out: str,
+) -> dict[str, Any]:
+    """插入一条新任务并返回任务字典。"""
+    now = storage.now_iso()
+    storage.db_execute(
+        """
+        INSERT INTO jobs(
+            id, username, filename, input_path, output_dir,
+            status, progress, message, error,
+            model, lang_in, lang_out,
+            cancel_requested,
+            created_at, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        """,
+        (
+            job_id,
+            username,
+            filename,
+            str(input_path),
+            str(output_dir),
+            "queued",
+            0.0,
+            "Queued",
+            None,
+            model,
+            lang_in,
+            lang_out,
+            0,
+            now,
+            now,
+        ),
+    )
+    row = storage.db_fetchone("SELECT * FROM jobs WHERE id = ?", (job_id,))
+    if row is None:
+        raise RuntimeError("Failed to fetch job after insert")
+    return row_to_job_dict(row)
+
+
+def resolve_artifact_path(raw_path: str | None, output_dir: Path) -> Path | None:
+    """解析并校验任务产物路径，限制在 output_dir 内部。"""
+    if not raw_path:
+        return None
+    path = Path(raw_path)
+    if not path.is_absolute():
+        path = (output_dir / path).resolve()
+    else:
+        path = path.resolve()
+
+    if not path.exists():
+        return None
+
+    try:
+        path.relative_to(output_dir)
+    except ValueError:
+        return None
+    return path
+

src/proxy.py

@@ -0,0 +1,305 @@
+"""内部 OpenAI 兼容代理逻辑。"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import uuid
+from datetime import datetime, timezone
+from typing import Any
+
+import httpx
+from fastapi import HTTPException, Request
+from fastapi.responses import JSONResponse, Response
+
+import auth
+import billing
+
+logger = logging.getLogger("gateway")
+
+
+OPENAI_UPSTREAM_CHAT_URL = os.environ.get(
+    "OPENAI_UPSTREAM_CHAT_URL", "https://api.openai.com/v1/chat/completions"
+)
+OPENAI_REAL_API_KEY = os.environ.get("OPENAI_API_KEY", "").strip()
+
+LOCALHOSTS = frozenset({"127.0.0.1", "::1", "localhost"})
+
+
+# 模型路由表：模型名 -> 上游配置
+MODEL_ROUTE_TABLE: dict[str, dict[str, Any]] = {
+    "SiliconFlowFree": {
+        "route_type": "chatproxy",
+        "base_urls": [
+            "https://api1.pdf2zh-next.com/chatproxy",
+            "https://api2.pdf2zh-next.com/chatproxy",
+        ],
+        "api_key": "",
+    }
+}
+
+
+def _extract_bearer_token(request: Request) -> str:
+    """从 Authorization 头中提取 Bearer token。"""
+    header = request.headers.get("authorization", "")
+    if not header.lower().startswith("bearer "):
+        raise HTTPException(status_code=401, detail="Missing bearer token")
+    token = header[7:].strip()
+    if not token:
+        raise HTTPException(status_code=401, detail="Missing bearer token")
+    return token
+
+
+def _require_localhost(request: Request) -> None:
+    """限制仅允许本地回环地址访问。"""
+    client = request.client
+    host = client.host if client else ""
+    if host not in LOCALHOSTS:
+        raise HTTPException(status_code=403, detail="Internal endpoint only")
+
+
+def _extract_text_from_message_content(content: Any) -> str:
+    if isinstance(content, str):
+        return content
+    if not isinstance(content, list):
+        return ""
+
+    parts: list[str] = []
+    for item in content:
+        if not isinstance(item, dict):
+            continue
+        if item.get("type") != "text":
+            continue
+        text = item.get("text")
+        if isinstance(text, str):
+            parts.append(text)
+    return "".join(parts)
+
+
+def _extract_text_from_messages(messages: Any) -> str:
+    if not isinstance(messages, list):
+        raise HTTPException(status_code=400, detail="messages must be a list")
+
+    for message in reversed(messages):
+        if not isinstance(message, dict):
+            continue
+        if message.get("role") != "user":
+            continue
+        text = _extract_text_from_message_content(message.get("content"))
+        if text:
+            return text
+
+    for message in reversed(messages):
+        if not isinstance(message, dict):
+            continue
+        text = _extract_text_from_message_content(message.get("content"))
+        if text:
+            return text
+
+    raise HTTPException(status_code=400, detail="messages does not contain text content")
+
+
+def _should_request_json_mode(payload: dict[str, Any]) -> bool:
+    response_format = payload.get("response_format")
+    if not isinstance(response_format, dict):
+        return False
+    return response_format.get("type") == "json_object"
+
+
+def _build_openai_compatible_response(model: str, content: str) -> dict[str, Any]:
+    return {
+        "id": f"chatcmpl-{uuid.uuid4().hex}",
+        "object": "chat.completion",
+        "created": int(datetime.now(timezone.utc).timestamp()),
+        "model": model,
+        "choices": [
+            {
+                "index": 0,
+                "message": {
+                    "role": "assistant",
+                    "content": content,
+                },
+                "finish_reason": "stop",
+            }
+        ],
+        "usage": {
+            "prompt_tokens": 0,
+            "completion_tokens": 0,
+            "total_tokens": 0,
+        },
+    }
+
+
+async def _forward_to_chatproxy(
+    http_client: httpx.AsyncClient,
+    payload: dict[str, Any],
+    model: str,
+    route: dict[str, Any],
+) -> dict[str, Any]:
+    base_urls = route.get("base_urls", [])
+    if not isinstance(base_urls, list) or not base_urls:
+        raise HTTPException(status_code=500, detail=f"No upstream configured for model {model}")
+
+    request_json = {
+        "text": _extract_text_from_messages(payload.get("messages")),
+    }
+    if _should_request_json_mode(payload):
+        request_json["requestJsonMode"] = True
+
+    api_key = str(route.get("api_key") or "").strip()
+    headers = {"Content-Type": "application/json"}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+
+    last_error = "No available upstream"
+    for base_url in base_urls:
+        try:
+            upstream = await http_client.post(
+                str(base_url),
+                headers=headers,
+                json=request_json,
+            )
+        except httpx.HTTPError as exc:
+            last_error = str(exc)
+            logger.warning("chatproxy call failed: model=%s url=%s error=%s", model, base_url, exc)
+            continue
+
+        if upstream.status_code >= 400:
+            last_error = f"status={upstream.status_code}"
+            logger.warning(
+                "chatproxy upstream returned error: model=%s url=%s status=%s",
+                model,
+                base_url,
+                upstream.status_code,
+            )
+            continue
+
+        try:
+            body = upstream.json()
+        except Exception as exc:  # noqa: BLE001
+            last_error = f"invalid json response: {exc}"
+            logger.warning(
+                "chatproxy upstream returned invalid json: model=%s url=%s",
+                model,
+                base_url,
+            )
+            continue
+
+        content = body.get("content")
+        if not isinstance(content, str):
+            last_error = "missing content field"
+            logger.warning(
+                "chatproxy upstream missing content: model=%s url=%s body=%s",
+                model,
+                base_url,
+                body,
+            )
+            continue
+
+        return _build_openai_compatible_response(model=model, content=content)
+
+    raise HTTPException(
+        status_code=502,
+        detail=f"All chatproxy upstreams failed for model {model}: {last_error}",
+    )
+
+
+async def handle_internal_chat_completions(
+    request: Request,
+    http_client: httpx.AsyncClient | None,
+    active_job_by_user: dict[str, str],
+) -> Response:
+    """处理内部 OpenAI 兼容聊天接口请求。"""
+    _require_localhost(request)
+    token = _extract_bearer_token(request)
+
+    username = auth.INTERNAL_KEY_TO_USER.get(token)
+    if not username:
+        raise HTTPException(status_code=401, detail="Invalid internal API key")
+
+    try:
+        payload = await request.json()
+    except json.JSONDecodeError as exc:
+        raise HTTPException(status_code=400, detail=f"Invalid JSON body: {exc}") from exc
+
+    if payload.get("stream"):
+        raise HTTPException(status_code=400, detail="stream=true is not supported")
+
+    if http_client is None:
+        raise HTTPException(status_code=500, detail="HTTP client is not ready")
+
+    model = str(payload.get("model") or "").strip()
+    if not model:
+        raise HTTPException(status_code=400, detail="model is required")
+
+    route = MODEL_ROUTE_TABLE.get(model)
+    if route and route.get("route_type") == "chatproxy":
+        response_json = await _forward_to_chatproxy(
+            http_client=http_client,
+            payload=payload,
+            model=model,
+            route=route,
+        )
+        billing.record_usage(
+            username=username,
+            job_id=active_job_by_user.get(username),
+            model=model,
+            prompt_tokens=0,
+            completion_tokens=0,
+            total_tokens=0,
+        )
+        return JSONResponse(response_json, status_code=200)
+
+    if not OPENAI_REAL_API_KEY:
+        raise HTTPException(status_code=500, detail="OPENAI_API_KEY is not configured")
+
+    headers = {
+        "Authorization": f"Bearer {OPENAI_REAL_API_KEY}",
+        "Content-Type": "application/json",
+    }
+
+    try:
+        upstream = await http_client.post(
+            OPENAI_UPSTREAM_CHAT_URL,
+            headers=headers,
+            json=payload,
+        )
+    except httpx.HTTPError as exc:
+        logger.error("Upstream OpenAI call failed: %s", exc)
+        raise HTTPException(status_code=502, detail="Upstream OpenAI request failed") from exc
+
+    response_json: dict[str, Any] | None = None
+    content_type = upstream.headers.get("content-type", "")
+    if "application/json" in content_type.lower():
+        try:
+            response_json = upstream.json()
+        except Exception:  # noqa: BLE001
+            response_json = None
+
+    if upstream.status_code < 400 and response_json is not None:
+        usage = response_json.get("usage") or {}
+        prompt_tokens = int(usage.get("prompt_tokens") or 0)
+        completion_tokens = int(usage.get("completion_tokens") or 0)
+        total_tokens = int(usage.get("total_tokens") or (prompt_tokens + completion_tokens))
+
+        job_id = active_job_by_user.get(username)
+
+        billing.record_usage(
+            username=username,
+            job_id=job_id,
+            model=model,
+            prompt_tokens=prompt_tokens,
+            completion_tokens=completion_tokens,
+            total_tokens=total_tokens,
+        )
+
+    if response_json is not None:
+        return JSONResponse(response_json, status_code=upstream.status_code)
+
+    return Response(
+        content=upstream.content,
+        status_code=upstream.status_code,
+        media_type=content_type or None,
+    )
+

src/storage.py

@@ -0,0 +1,137 @@
+"""存储层：数据目录与 SQLite 封装。"""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+# 注意：日志仍然复用主网关 logger 名称，方便统一过滤
+import logging
+
+logger = logging.getLogger("gateway")
+
+
+# ── 路径与基本配置 ─────────────────────────────────────────────────────────────
+DATA_DIR = Path(os.environ.get("DATA_DIR", "/data"))
+UPLOAD_DIR = DATA_DIR / "uploads"
+JOB_DIR = DATA_DIR / "jobs"
+DB_PATH = DATA_DIR / "gateway.db"
+
+
+_db_lock = threading.Lock()
+_db_conn: sqlite3.Connection | None = None
+
+
+def now_iso() -> str:
+    """返回当前 UTC 时间的 ISO 字符串。"""
+    return datetime.now(timezone.utc).isoformat()
+
+
+def ensure_data_dirs() -> None:
+    """确保数据目录存在。"""
+    UPLOAD_DIR.mkdir(parents=True, exist_ok=True)
+    JOB_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def init_db() -> None:
+    """初始化 SQLite 数据库与基础表结构。"""
+    global _db_conn
+
+    ensure_data_dirs()
+    conn = sqlite3.connect(DB_PATH, check_same_thread=False)
+    conn.row_factory = sqlite3.Row
+    with conn:
+        conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS jobs (
+                id TEXT PRIMARY KEY,
+                username TEXT NOT NULL,
+                filename TEXT NOT NULL,
+                input_path TEXT NOT NULL,
+                output_dir TEXT NOT NULL,
+                status TEXT NOT NULL,
+                progress REAL NOT NULL DEFAULT 0,
+                message TEXT,
+                error TEXT,
+                model TEXT NOT NULL,
+                lang_in TEXT NOT NULL,
+                lang_out TEXT NOT NULL,
+                cancel_requested INTEGER NOT NULL DEFAULT 0,
+                mono_pdf_path TEXT,
+                dual_pdf_path TEXT,
+                glossary_path TEXT,
+                created_at TEXT NOT NULL,
+                updated_at TEXT NOT NULL,
+                started_at TEXT,
+                finished_at TEXT
+            )
+            """
+        )
+        conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS usage_records (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                username TEXT NOT NULL,
+                job_id TEXT,
+                model TEXT NOT NULL,
+                prompt_tokens INTEGER NOT NULL,
+                completion_tokens INTEGER NOT NULL,
+                total_tokens INTEGER NOT NULL,
+                cost_usd REAL NOT NULL,
+                created_at TEXT NOT NULL
+            )
+            """
+        )
+        conn.execute(
+            """
+            CREATE INDEX IF NOT EXISTS idx_jobs_user_time
+            ON jobs(username, created_at DESC)
+            """
+        )
+        conn.execute(
+            """
+            CREATE INDEX IF NOT EXISTS idx_usage_user_time
+            ON usage_records(username, created_at DESC)
+            """
+        )
+
+    _db_conn = conn
+    logger.info("Database initialized at %s", DB_PATH)
+
+
+def close_db() -> None:
+    """关闭数据库连接，用于应用关闭阶段。"""
+    global _db_conn
+
+    if _db_conn is not None:
+        _db_conn.close()
+        _db_conn = None
+
+
+def db_execute(sql: str, params: tuple[Any, ...] = ()) -> None:
+    """执行写操作 SQL。"""
+    if _db_conn is None:
+        raise RuntimeError("DB is not initialized")
+    with _db_lock, _db_conn:
+        _db_conn.execute(sql, params)
+
+
+def db_fetchone(sql: str, params: tuple[Any, ...] = ()) -> sqlite3.Row | None:
+    """执行查询并返回单行。"""
+    if _db_conn is None:
+        raise RuntimeError("DB is not initialized")
+    with _db_lock:
+        return _db_conn.execute(sql, params).fetchone()
+
+
+def db_fetchall(sql: str, params: tuple[Any, ...] = ()) -> list[sqlite3.Row]:
+    """执行查询并返回多行。"""
+    if _db_conn is None:
+        raise RuntimeError("DB is not initialized")
+    with _db_lock:
+        return _db_conn.execute(sql, params).fetchall()
+

src/web/__init__.py

@@ -0,0 +1,2 @@
+"""Web 相关模板与静态资源包。"""
+

src/web/static/dashboard.js

@@ -0,0 +1,132 @@
+async function apiJson(url, options = undefined) {
+  const resp = await fetch(url, options);
+  if (!resp.ok) {
+    const data = await resp.text();
+    throw new Error(data || `HTTP ${resp.status}`);
+  }
+  return resp.json();
+}
+
+function esc(s) {
+  return String(s || "").replace(/[&<>"']/g, (c) => ({
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;",
+  })[c]);
+}
+
+async function refreshBilling() {
+  const summary = await apiJson("/api/billing/me");
+  const rows = await apiJson("/api/billing/me/records?limit=20");
+
+  document.getElementById("billingSummary").textContent =
+    `总 tokens=${summary.total_tokens} | 总费用(USD)=${Number(
+      summary.total_cost_usd,
+    ).toFixed(6)}`;
+
+  const body = document.getElementById("billingBody");
+  body.innerHTML = "";
+  for (const r of rows.records) {
+    const tr = document.createElement("tr");
+    tr.innerHTML = `
+      <td>${esc(r.created_at)}</td>
+      <td class="mono">${esc(r.model)}</td>
+      <td>${r.prompt_tokens}</td>
+      <td>${r.completion_tokens}</td>
+      <td>${r.total_tokens}</td>
+      <td>${Number(r.cost_usd).toFixed(6)}</td>
+    `;
+    body.appendChild(tr);
+  }
+}
+
+function actionButtons(job) {
+  const actions = [];
+  if (job.status === "queued" || job.status === "running") {
+    actions.push(
+      `<button class="danger" onclick="cancelJob('${job.id}')">取消</button>`,
+    );
+  }
+  if (job.artifact_urls?.mono) {
+    actions.push(
+      `<a href="${job.artifact_urls.mono}"><button class="muted">单语版</button></a>`,
+    );
+  }
+  if (job.artifact_urls?.dual) {
+    actions.push(
+      `<a href="${job.artifact_urls.dual}"><button class="muted">双语版</button></a>`,
+    );
+  }
+  if (job.artifact_urls?.glossary) {
+    actions.push(
+      `<a href="${job.artifact_urls.glossary}"><button class="muted">术语表</button></a>`,
+    );
+  }
+  return actions.join(" ");
+}
+
+function statusText(status) {
+  const statusMap = {
+    queued: "排队中",
+    running: "进行中",
+    succeeded: "成功",
+    failed: "失败",
+    cancelled: "已取消",
+  };
+  return statusMap[status] || status;
+}
+
+async function refreshJobs() {
+  const data = await apiJson("/api/jobs?limit=50");
+  const body = document.getElementById("jobsBody");
+  body.innerHTML = "";
+
+  for (const job of data.jobs) {
+    const tr = document.createElement("tr");
+    tr.innerHTML = `
+      <td class="mono">${esc(job.id)}</td>
+      <td>${esc(job.filename)}</td>
+      <td>${esc(statusText(job.status))}${job.error ? " / " + esc(job.error) : ""}</td>
+      <td>${Number(job.progress).toFixed(1)}%</td>
+      <td class="mono">${esc(job.model)}</td>
+      <td class="mono">${esc(job.updated_at)}</td>
+      <td class="actions">${actionButtons(job)}</td>
+    `;
+    body.appendChild(tr);
+  }
+}
+
+async function cancelJob(jobId) {
+  try {
+    await apiJson(`/api/jobs/${jobId}/cancel`, { method: "POST" });
+    await refreshJobs();
+  } catch (err) {
+    alert(`取消失败: ${err.message}`);
+  }
+}
+
+document.getElementById("jobForm").addEventListener("submit", async (event) => {
+  event.preventDefault();
+  const status = document.getElementById("jobStatus");
+  status.textContent = "提交中...";
+
+  const formData = new FormData(event.target);
+  try {
+    const created = await apiJson("/api/jobs", { method: "POST", body: formData });
+    status.textContent = `任务已入队: ${created.job.id}`;
+    event.target.reset();
+    await refreshJobs();
+  } catch (err) {
+    status.textContent = `提交失败: ${err.message}`;
+  }
+});
+
+async function refreshAll() {
+  await Promise.all([refreshJobs(), refreshBilling()]);
+}
+
+refreshAll();
+setInterval(refreshAll, 3000);
+

src/web/template_loader.py

@@ -0,0 +1,22 @@
+"""简单的模板与静态资源加载工具。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+BASE_DIR = Path(__file__).resolve().parent
+TEMPLATE_DIR = BASE_DIR / "templates"
+STATIC_DIR = BASE_DIR / "static"
+
+
+def load_template(name: str) -> str:
+    """读取模板文件内容。"""
+    path = TEMPLATE_DIR / name
+    return path.read_text(encoding="utf-8")
+
+
+def get_static_path(name: str) -> Path:
+    """返回静态资源的绝对路径路径。"""
+    return (STATIC_DIR / name).resolve()
+

src/web/templates/dashboard.html

@@ -0,0 +1,150 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>PDF 翻译控制台</title>
+  <style>
+    :root {
+      --bg: #f4f7fb;
+      --card: #ffffff;
+      --ink: #0f172a;
+      --sub: #475569;
+      --line: #dbe3ee;
+      --brand: #0f766e;
+      --brand-dark: #115e59;
+      --danger: #b91c1c;
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      color: var(--ink);
+      background: radial-gradient(circle at 15% -20%, #d5f3ef 0, #f4f7fb 52%);
+      font-family: "Segoe UI", Tahoma, Geneva, Verdana, sans-serif;
+    }
+    .wrap { max-width: 1100px; margin: 24px auto; padding: 0 16px 40px; }
+    .top {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      margin-bottom: 16px;
+    }
+    h1 { margin: 0; font-size: 1.5rem; }
+    .user { color: var(--sub); font-size: 0.95rem; }
+    .grid { display: grid; grid-template-columns: 1fr 1fr; gap: 14px; }
+    .card {
+      background: var(--card);
+      border: 1px solid var(--line);
+      border-radius: 14px;
+      box-shadow: 0 10px 28px rgba(17, 24, 39, 0.06);
+      padding: 16px;
+    }
+    .card h2 { margin: 0 0 10px; font-size: 1.03rem; }
+    .row { display: grid; grid-template-columns: 1fr 1fr; gap: 10px; }
+    label { display: block; margin: 10px 0 6px; font-size: 0.86rem; color: var(--sub); }
+    input[type=text], select, input[type=file] {
+      width: 100%; padding: 10px 12px; border-radius: 8px;
+      border: 1px solid var(--line); background: #fff; color: var(--ink);
+    }
+    button {
+      border: none; border-radius: 9px; padding: 10px 14px;
+      font-weight: 600; cursor: pointer;
+    }
+    .primary { background: var(--brand); color: #fff; }
+    .primary:hover { background: var(--brand-dark); }
+    .muted { background: #e2e8f0; color: #0f172a; }
+    .danger { background: #fee2e2; color: var(--danger); }
+    .hint { margin-top: 8px; color: var(--sub); font-size: 0.84rem; }
+    .status { margin-top: 10px; min-height: 22px; font-size: 0.9rem; }
+    table { width: 100%; border-collapse: collapse; margin-top: 8px; font-size: 0.88rem; }
+    th, td { border-bottom: 1px solid var(--line); text-align: left; padding: 8px 6px; }
+    th { color: var(--sub); font-weight: 600; }
+    .mono { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 0.8rem; }
+    .actions button { margin-right: 6px; margin-bottom: 4px; }
+    .foot { margin-top: 20px; color: var(--sub); font-size: 0.82rem; }
+    @media (max-width: 900px) {
+      .grid { grid-template-columns: 1fr; }
+      .row { grid-template-columns: 1fr; }
+    }
+  </style>
+</head>
+<body>
+<div class="wrap">
+  <div class="top">
+    <div>
+      <h1>PDF 翻译控制台</h1>
+      <div class="user">当前用户：<strong>__USERNAME__</strong></div>
+    </div>
+    <div><a href="/logout"><button class="muted">退出登录</button></a></div>
+  </div>
+
+  <div class="grid">
+    <section class="card">
+      <h2>新建任务</h2>
+      <form id="jobForm">
+        <label>PDF 文件</label>
+        <input name="file" type="file" accept=".pdf" required />
+
+        <div class="row">
+          <div>
+            <label>源语言</label>
+            <input name="lang_in" type="text" value="__LANG_IN__" required />
+          </div>
+          <div>
+            <label>目标语言</label>
+            <input name="lang_out" type="text" value="__LANG_OUT__" required />
+          </div>
+        </div>
+
+        <div style="margin-top: 12px;">
+          <button class="primary" type="submit">提交任务</button>
+        </div>
+      </form>
+      <div class="hint">模型由后台固定为 SiliconFlowFree，用户无需选择。</div>
+      <div id="jobStatus" class="status"></div>
+    </section>
+
+    <section class="card">
+      <h2>我的账单</h2>
+      <div id="billingSummary" class="mono">加载中...</div>
+      <table>
+        <thead>
+          <tr>
+            <th>时间 (UTC)</th>
+            <th>模型</th>
+            <th>输入</th>
+            <th>输出</th>
+            <th>总计</th>
+            <th>费用 (USD)</th>
+          </tr>
+        </thead>
+        <tbody id="billingBody"></tbody>
+      </table>
+    </section>
+  </div>
+
+  <section class="card" style="margin-top: 14px;">
+    <h2>我的任务</h2>
+    <table>
+      <thead>
+        <tr>
+          <th>ID</th>
+          <th>文件</th>
+          <th>状态</th>
+          <th>进度</th>
+          <th>模型</th>
+          <th>更新时间 (UTC)</th>
+          <th>操作</th>
+        </tr>
+      </thead>
+      <tbody id="jobsBody"></tbody>
+    </table>
+  </section>
+
+  <div class="foot">内部 OpenAI 接口仅允许 localhost 访问，不会直接暴露给终端用户。</div>
+</div>
+
+<script src="/static/dashboard.js"></script>
+</body>
+</html>
+

src/web/templates/login.html

@@ -0,0 +1,79 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>登录</title>
+<style>
+  *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+  body {
+    min-height: 100vh;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: linear-gradient(135deg, #f0f2f5 0%, #e4e8f0 100%);
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  }
+  .card {
+    background: #fff;
+    border-radius: 14px;
+    box-shadow: 0 6px 32px rgba(0, 0, 0, 0.10);
+    padding: 44px 40px;
+    width: 100%;
+    max-width: 400px;
+  }
+  h1 { font-size: 1.5rem; font-weight: 700; color: #111827; margin-bottom: 6px; }
+  p.sub { font-size: 0.875rem; color: #6b7280; margin-bottom: 30px; }
+  label { display: block; font-size: 0.8rem; font-weight: 600; color: #374151; margin-bottom: 6px; }
+  input[type=text], input[type=password] {
+    width: 100%;
+    padding: 11px 14px;
+    border: 1.5px solid #e5e7eb;
+    border-radius: 8px;
+    font-size: 0.95rem;
+    outline: none;
+    transition: border-color 0.15s;
+    margin-bottom: 20px;
+    color: #111827;
+  }
+  input:focus { border-color: #4f6ef7; box-shadow: 0 0 0 3px rgba(79,110,247,0.12); }
+  button {
+    width: 100%;
+    padding: 12px;
+    background: linear-gradient(135deg, #4f6ef7 0%, #3b5bdb 100%);
+    color: #fff;
+    border: none;
+    border-radius: 8px;
+    font-size: 1rem;
+    font-weight: 600;
+    cursor: pointer;
+    transition: opacity 0.15s;
+  }
+  button:hover { opacity: 0.88; }
+  .error {
+    background: #fef2f2;
+    border: 1.5px solid #fecaca;
+    border-radius: 8px;
+    padding: 10px 14px;
+    font-size: 0.875rem;
+    color: #dc2626;
+    margin-bottom: 20px;
+  }
+</style>
+</head>
+<body>
+<div class="card">
+  <h1>欢迎回来</h1>
+  <p class="sub">请先登录后继续</p>
+  __ERROR_BLOCK__
+  <form method="post" action="/login">
+    <label for="u">用户名</label>
+    <input id="u" type="text" name="username" autocomplete="username" required autofocus>
+    <label for="p">密码</label>
+    <input id="p" type="password" name="password" autocomplete="current-password" required>
+    <button type="submit">登录</button>
+  </form>
+</div>
+</body>
+</html>
+