feat(notification): 通知标题和正文支持多语言

- 通知静态配置支持 title/body i18n
- 前端通知列表和详情页展示本地化内容
- 新增数据库迁移脚本
- 更新通知协议文档

backend/src/v1/notifications/router.py

@@ -1,11 +1,13 @@
 from __future__ import annotations
 
+from datetime import datetime
 from typing import Annotated
 
 from fastapi import APIRouter, Depends, Query
 
 from core.logging import get_logger
 from core.auth.models import CurrentUser
+from core.http.errors import ApiProblemError, problem_payload
 from v1.notifications.dependencies import get_notification_service
 from v1.notifications.schemas import (
     MarkAllReadResponse,
@@ -13,33 +15,42 @@ from v1.notifications.schemas import (
     NotificationListResponse,
     UnreadCountResponse,
 )
-from v1.notifications.service import NotificationService
+from v1.notifications.service import NotificationService, normalize_locale
 from v1.users.dependencies import get_current_user
 
 router = APIRouter(prefix="/notifications", tags=["notifications"])
 logger = get_logger("v1.notifications.router")
 
 
+def _parse_cursor(cursor: str | None) -> datetime | None:
+    if cursor is None:
+        return None
+    try:
+        return datetime.fromisoformat(cursor.replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise ApiProblemError(
+            status_code=422,
+            detail=problem_payload(
+                code="NOTIFICATION_INVALID_CURSOR",
+                detail="Notification cursor must be an ISO 8601 datetime",
+                params={"cursor": cursor},
+            ),
+        ) from exc
+
+
 @router.get("", response_model=NotificationListResponse)
 async def list_notifications(
     service: Annotated[NotificationService, Depends(get_notification_service)],
     current_user: Annotated[CurrentUser, Depends(get_current_user)],
     limit: int = Query(default=20, ge=1, le=50),
     cursor: str | None = Query(default=None),
+    locale: str | None = Query(default=None),
 ) -> NotificationListResponse:
-    from datetime import datetime
-
-    parsed_cursor = None
-    if cursor is not None:
-        try:
-            parsed_cursor = datetime.fromisoformat(cursor.replace("Z", "+00:00"))
-        except (ValueError, AttributeError):
-            parsed_cursor = None
-
     result = await service.list_notifications(
         user_id=current_user.id,
         limit=limit,
-        cursor=parsed_cursor,
+        cursor=_parse_cursor(cursor),
+        locale=normalize_locale(locale),
     )
     logger.info(
         "Notification list fetched",
@@ -89,14 +100,13 @@ async def mark_notification_read(
     notification_id: str,
     service: Annotated[NotificationService, Depends(get_notification_service)],
     current_user: Annotated[CurrentUser, Depends(get_current_user)],
+    locale: str | None = Query(default=None),
 ) -> NotificationItemResponse:
     from uuid import UUID
 
     try:
         uid = UUID(notification_id)
     except ValueError:
-        from core.http.errors import ApiProblemError, problem_payload
-
         raise ApiProblemError(
             status_code=404,
             detail=problem_payload(
@@ -108,6 +118,7 @@ async def mark_notification_read(
     item = await service.mark_read(
         user_notification_id=uid,
         user_id=current_user.id,
+        locale=normalize_locale(locale),
     )
     logger.info(
         "Notification marked as read",

backend/src/v1/notifications/service.py

@@ -13,6 +13,35 @@ from v1.notifications.schemas import (
     NotificationPayload,
 )
 
+DEFAULT_LOCALE = "zh"
+SUPPORTED_LOCALES = frozenset({"zh", "zh_Hant", "en"})
+
+
+def resolve_i18n_text(i18n_dict: dict[str, str], locale: str) -> str:
+    if not i18n_dict:
+        return ""
+    if locale in i18n_dict:
+        return i18n_dict[locale]
+    if DEFAULT_LOCALE in i18n_dict:
+        return i18n_dict[DEFAULT_LOCALE]
+    return ""
+
+
+def normalize_locale(raw: str | None) -> str:
+    if raw is None:
+        return DEFAULT_LOCALE
+    locale = raw.strip()
+    if locale in SUPPORTED_LOCALES:
+        return locale
+    lower = locale.lower().replace("-", "_")
+    if lower in ("zh_cn", "zh_hans", "zh"):
+        return "zh"
+    if lower in ("zh_tw", "zh_hant", "zh_hk"):
+        return "zh_Hant"
+    if lower.startswith("en"):
+        return "en"
+    return DEFAULT_LOCALE
+
 
 @dataclass(frozen=True)
 class NotificationListItem:
@@ -44,6 +73,7 @@ class NotificationService:
         user_id: UUID,
         limit: int = 20,
         cursor: datetime | None = None,
+        locale: str = DEFAULT_LOCALE,
     ) -> NotificationListResult:
         actual_limit = min(limit, 50)
         rows = await self._repository.list_notifications(
@@ -65,8 +95,8 @@ class NotificationService:
                     id=un.id,
                     notification_id=n.id,
                     type=n.type,
-                    title=n.title,
-                    body=n.body,
+                    title=resolve_i18n_text(n.title, locale),
+                    body=resolve_i18n_text(n.body, locale),
                     payload=payload,
                     is_read=un.is_read,
                     read_at=un.read_at,
@@ -83,7 +113,11 @@ class NotificationService:
         return await self._repository.get_unread_count(user_id=user_id)
 
     async def mark_read(
-        self, *, user_notification_id: UUID, user_id: UUID
+        self,
+        *,
+        user_notification_id: UUID,
+        user_id: UUID,
+        locale: str = DEFAULT_LOCALE,
     ) -> NotificationListItem:
         result = await self._repository.get_user_notification(
             user_notification_id=user_notification_id,
@@ -109,8 +143,8 @@ class NotificationService:
             id=un.id,
             notification_id=n.id,
             type=n.type,
-            title=n.title,
-            body=n.body,
+            title=resolve_i18n_text(n.title, locale),
+            body=resolve_i18n_text(n.body, locale),
             payload=payload,
             is_read=True,
             read_at=un.read_at or datetime.now(timezone.utc),