feat: initial MVP - FastAPI backend + Vue3 frontend + docker-compose

- backend: FastAPI + SQLAlchemy 2.0(async) + asyncpg + Alembic
- 7 API routes: auth/me/articles/sources/bookmarks/subscriptions/admin
- models: User/Source/Article/Bookmark/Subscription/ApiToken
- services: RSS fetcher (feedparser) + Tencent TMT translator with quota + cache + local NLLB fallback
- workers: APScheduler + asyncio pipeline (fetch -> dedupe -> insert -> translate)
- seed scripts: create_user, seed_sources (5 RSS: Reuters/BBC/Al Jazeera/NHK/DW)
- frontend: Vue 3 + Vite + Naive UI + Pinia + vue-router
- pages: Login, Feed (24h), ArticleDetail, Sources, Bookmarks, AdminSources
- deploy: docker-compose (postgres/redis/api/worker/frontend/caddy)
- docs: README, DEPLOY, architecture, acceptance

backend/app/services/translation/service.py

@@ -0,0 +1,146 @@
+"""翻译服务门面:配额检查 + 缓存 + 引擎选择 + 月度计数。"""
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import logging
+from datetime import datetime, timezone
+from typing import Protocol
+
+from app.config import settings
+from app.redis_client import get_redis
+from app.services.translation.base import BaseTranslator, TranslationResult
+from app.services.translation.local import LocalTranslator
+from app.services.translation.tencent import TencentTranslator
+
+logger = logging.getLogger("news.translate.service")
+
+
+# 缓存 key
+def _cache_key(text: str, src: str, tgt: str) -> str:
+    h = hashlib.sha1(f"{src}|{tgt}|{text}".encode()).hexdigest()
+    return f"translation:cache:{h}"
+
+
+def _month_key() -> str:
+    now = datetime.now(timezone.utc)
+    return f"translation:month:{now:%Y%m}"
+
+
+class TranslationService:
+    def __init__(self):
+        self._tencent: BaseTranslator | None = None
+        self._local: BaseTranslator | None = None
+        self._sem = asyncio.Semaphore(3)  # 并发限流
+
+    def _primary(self) -> BaseTranslator:
+        if self._tencent is None:
+            self._tencent = TencentTranslator()
+        return self._tencent
+
+    def _fallback(self) -> BaseTranslator | None:
+        if self._local is None and settings.local_translate_enabled:
+            try:
+                self._local = LocalTranslator()
+            except Exception as e:
+                logger.warning("local translator init failed: %s", e)
+                self._local = None
+        return self._local
+
+    async def can_use_tencent(self, chars: int) -> bool:
+        if not settings.tencentcloud_secret_id:
+            return False
+        r = get_redis()
+        used = int(await r.get(_month_key()) or 0)
+        buffered = int(
+            settings.tencent_tmt_quota_month * (1 - settings.tencent_tmt_quota_buffer)
+        )
+        return (used + chars) <= buffered
+
+    async def add_usage(self, chars: int) -> None:
+        r = get_redis()
+        # 用 INCRBY + EXPIRE 月初;简单做法:每次 set + 设 TTL
+        key = _month_key()
+        async with r.pipeline(transaction=False) as pipe:
+            pipe.incrby(key, chars)
+            # 月底过期(下下月 1 日)
+            now = datetime.now(timezone.utc)
+            if now.month == 12:
+                next_month = now.replace(year=now.year + 1, month=1, day=1)
+            else:
+                next_month = now.replace(month=now.month + 1, day=1)
+            ttl = int((next_month - now).total_seconds()) + 86400
+            pipe.expire(key, ttl)
+            await pipe.execute()
+
+    async def translate(
+        self, text: str, source: str = "auto", target: str = "zh"
+    ) -> TranslationResult:
+        if not text.strip():
+            return TranslationResult(text=text, engine="skip", chars=0)
+
+        chars = len(text)
+        # 1) 缓存
+        r = get_redis()
+        ck = _cache_key(text, source, target)
+        cached = await r.get(ck)
+        if cached is not None:
+            return TranslationResult(text=cached, engine="cache", chars=chars, cached=True)
+
+        # 2) 选引擎
+        use_tencent = await self.can_use_tencent(chars)
+        engine: BaseTranslator
+        if use_tencent:
+            engine = self._primary()
+        else:
+            fb = self._fallback()
+            if fb is None:
+                # 没本地:返回原文 + 标记
+                return TranslationResult(
+                    text=text + "\n\n[本条未翻译:配额耗尽且未启用本地翻译]",
+                    engine="skip",
+                    chars=chars,
+                )
+            engine = fb
+            logger.info("fallback to local translator for %d chars", chars)
+
+        # 3) 调用
+        async with self._sem:
+            try:
+                res = await engine.translate(text, source=source, target=target)
+            except Exception as e:
+                # 失败:降级
+                logger.exception("translate failed with %s: %s", engine.name, e)
+                fb = self._fallback()
+                if fb is not None and engine is not fb:
+                    res = await fb.translate(text, source=source, target=target)
+                else:
+                    res = TranslationResult(
+                        text=text + f"\n\n[翻译失败: {e}]",
+                        engine="skip",
+                        chars=chars,
+                    )
+
+        # 4) 写缓存(无论引擎)
+        try:
+            await r.set(ck, res.text, ex=60 * 60 * 24 * 30)  # 30 天
+        except Exception:
+            pass
+
+        # 5) 计数(只在 tencent 上计)
+        if res.engine == "tencent":
+            try:
+                await self.add_usage(res.chars or chars)
+            except Exception as e:
+                logger.warning("add_usage failed: %s", e)
+
+        return res
+
+
+# 全局单例
+service = TranslationService()
+
+
+# 让后端 worker 直接调
+class _Protocol(Protocol):
+    async def translate(self, text: str, source: str = "auto", target: str = "zh") -> TranslationResult: ...