feat: 新人初始礼包购买追踪功能

- 数据库：添加 has_purchased_starter_pack 字段到 register_bonus_claims
- 后端：创建静态配置管理套餐信息，支持按国家/地区区分
- 后端：新增 GET /api/v1/points/packages API 返回可用套餐
- 后端：创建 utils/paths.py 统一路径管理
- 前端：动态获取套餐信息，移除硬编码
- 前端：添加 ProductCode 枚举约束，前后端类型安全
- 配置：Profile 默认国家改为 US（ISO 3166-1 alpha-2）
- 文档：更新协议文档说明新 API 和字段

backend/src/core/config/initial/init_data.py

@@ -15,6 +15,7 @@ from core.logging import get_logger
 from models.llm import Llm
 from models.llm_factory import LlmFactory
 from models.system_agents import SystemAgents
+from utils.paths import get_llm_catalog_config_path, get_system_agents_config_path
 
 logger = get_logger("core.config.initial.init_data")
 
@@ -48,9 +49,7 @@ class SystemAgentsYaml(BaseModel):
 
 
 def _default_catalog_path() -> Path:
-    return (
-        Path(__file__).resolve().parents[1] / "static" / "database" / "llm_catalog.yaml"
-    )
+    return get_llm_catalog_config_path()
 
 
 def load_llm_catalog(catalog_path: Path | None = None) -> dict[str, Any]:
@@ -77,12 +76,7 @@ def load_llm_catalog(catalog_path: Path | None = None) -> dict[str, Any]:
 
 
 def _default_system_agents_path() -> Path:
-    return (
-        Path(__file__).resolve().parents[1]
-        / "static"
-        / "database"
-        / "system_agents.yaml"
-    )
+    return get_system_agents_config_path()
 
 
 def load_system_agents(catalog_path: Path | None = None) -> dict[str, Any]:

backend/src/core/config/notification/static_sync.py

@@ -24,6 +24,7 @@ from core.config.notification.static_schema import (
 from models.auth_user import AuthUser
 from models.notification import Notification
 from models.user_notification import UserNotification
+from utils.paths import get_notification_config_dir
 
 logger = get_logger("core.config.notification.static_sync")
 
@@ -41,12 +42,7 @@ class StaticNotificationSyncResult:
 
 
 def default_static_notification_path() -> Path:
-    return (
-        Path(__file__).resolve().parents[1]
-        / "static"
-        / "notification"
-        / "notifications"
-    )
+    return get_notification_config_dir()
 
 
 def load_static_notification_documents(

backend/src/core/config/packages/__init__.py

@@ -0,0 +1,21 @@
+from core.config.packages.registry import (
+    clear_packages_cache,
+    get_packages_config_for_region,
+)
+from core.config.packages.schema import (
+    PackageConfig,
+    PackageType,
+    ProductCode,
+    RegionPackagesConfig,
+    load_packages_config,
+)
+
+__all__ = [
+    "clear_packages_cache",
+    "get_packages_config_for_region",
+    "load_packages_config",
+    "PackageConfig",
+    "PackageType",
+    "ProductCode",
+    "RegionPackagesConfig",
+]

backend/src/core/config/packages/registry.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from core.config.packages.schema import (
+    RegionPackagesConfig,
+    load_packages_config,
+)
+from utils.paths import get_default_package_config_path, get_package_config_path
+
+
+_CONFIG_CACHE: dict[str, RegionPackagesConfig] = {}
+
+
+def get_packages_config_for_region(country: str) -> RegionPackagesConfig:
+    if country in _CONFIG_CACHE:
+        return _CONFIG_CACHE[country]
+
+    region_file = get_package_config_path(country)
+    if region_file.exists():
+        config = load_packages_config(region_file)
+        _CONFIG_CACHE[country] = config
+        return config
+
+    default_file = get_default_package_config_path()
+    if not default_file.exists():
+        raise RuntimeError(f"No default packages config found: {default_file}")
+
+    config = load_packages_config(default_file)
+    _CONFIG_CACHE[country] = config
+    return config
+
+
+def clear_packages_cache() -> None:
+    global _CONFIG_CACHE
+    _CONFIG_CACHE = {}

backend/src/core/config/packages/schema.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from enum import Enum
+from pathlib import Path
+from typing import ClassVar, Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+
+class PackageType(str, Enum):
+    STARTER = "starter"
+    REGULAR = "regular"
+
+
+ProductCode = Literal[
+    "new_user_pack",
+    "basic_pack",
+    "popular_pack",
+    "premium_pack",
+]
+
+
+class PackageConfig(BaseModel):
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
+
+    product_code: ProductCode
+    type: PackageType
+    price: float = Field(ge=0)
+    credits: int = Field(ge=1)
+    sort_order: int = Field(default=0, ge=0)
+    enabled: bool = Field(default=True)
+
+
+class RegionPackagesConfig(BaseModel):
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
+
+    region: str = Field(min_length=1, max_length=8)
+    currency: str = Field(min_length=1, max_length=8)
+    packages: list[PackageConfig] = Field(min_length=1)
+
+
+def load_packages_config(path: Path) -> RegionPackagesConfig:
+    with path.open("r", encoding="utf-8") as file:
+        loaded: object = yaml.safe_load(file) or {}
+    if not isinstance(loaded, dict):
+        raise ValueError(f"Invalid packages config format: {path}")
+    try:
+        return RegionPackagesConfig.model_validate(loaded)
+    except ValidationError as exc:
+        raise ValueError(f"Invalid packages config data: {path}") from exc

backend/src/core/config/static/packages/default.yaml

@@ -0,0 +1,30 @@
+region: DEFAULT
+currency: USD
+packages:
+  - product_code: new_user_pack
+    type: starter
+    price: 0.99
+    credits: 60
+    sort_order: 0
+    enabled: true
+    
+  - product_code: basic_pack
+    type: regular
+    price: 4.99
+    credits: 100
+    sort_order: 10
+    enabled: true
+    
+  - product_code: popular_pack
+    type: regular
+    price: 7.99
+    credits: 210
+    sort_order: 20
+    enabled: true
+    
+  - product_code: premium_pack
+    type: regular
+    price: 12.99
+    credits: 415
+    sort_order: 30
+    enabled: true

backend/src/core/config/static/packages/us.yaml

@@ -0,0 +1,30 @@
+region: US
+currency: USD
+packages:
+  - product_code: new_user_pack
+    type: starter
+    price: 0.99
+    credits: 60
+    sort_order: 0
+    enabled: true
+    
+  - product_code: basic_pack
+    type: regular
+    price: 4.99
+    credits: 100
+    sort_order: 10
+    enabled: true
+    
+  - product_code: popular_pack
+    type: regular
+    price: 7.99
+    credits: 210
+    sort_order: 20
+    enabled: true
+    
+  - product_code: premium_pack
+    type: regular
+    price: 12.99
+    credits: 415
+    sort_order: 30
+    enabled: true

backend/src/core/divination/gua_catalog_loader.py

@@ -5,6 +5,8 @@ from functools import lru_cache
 import json
 from pathlib import Path
 
+from utils.paths import get_gua_catalog_path
+
 
 @dataclass(frozen=True)
 class GuaCatalogItem:
@@ -24,8 +26,7 @@ class GuaCatalogItem:
 
 
 def _resolve_catalog_file() -> Path:
-    current = Path(__file__).resolve()
-    target = current.parent / "data/gua_catalog.json"
+    target = get_gua_catalog_path()
     if not target.exists():
         raise FileNotFoundError(f"gua_catalog.json not found: {target}")
     return target