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/alembic/versions/20260416_0001_add_starter_pack_tracking.py

@@ -0,0 +1,32 @@
+"""add has_purchased_starter_pack to register_bonus_claims
+
+Revision ID: 20260416_0001
+Revises: 20260413_0004
+Create Date: 2026-04-16 12:00:00
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = "20260416_0001"
+down_revision: Union[str, Sequence[str], None] = "20260415_0002"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "register_bonus_claims",
+        sa.Column(
+            "has_purchased_starter_pack",
+            sa.Boolean(),
+            nullable=False,
+            server_default=sa.text("false"),
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("register_bonus_claims", "has_purchased_starter_pack")

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

backend/src/models/register_bonus_claims.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import uuid
 
-from sqlalchemy import BigInteger, String, Text, UniqueConstraint
+from sqlalchemy import BigInteger, Boolean, String, Text, UniqueConstraint
 from sqlalchemy.dialects.postgresql import UUID
 from sqlalchemy.orm import Mapped, mapped_column
 
@@ -30,3 +30,6 @@ class RegisterBonusClaims(TimestampMixin, Base):
     )
     balance_snapshot: Mapped[int | None] = mapped_column(BigInteger, nullable=True)
     grant_event_id: Mapped[str] = mapped_column(String(64), nullable=False)
+    has_purchased_starter_pack: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=False
+    )

backend/src/schemas/shared/user.py

@@ -14,7 +14,7 @@ class PreferenceSettings(BaseModel):
     interface_language: str = "zh-CN"
     ai_language: str = "zh-CN"
     timezone: str = "Asia/Shanghai"
-    country: str = "CN"
+    country: str = "US"
 
     @field_validator("interface_language", "ai_language")
     @classmethod

backend/src/utils/__init__.py

@@ -0,0 +1,29 @@
+from utils.paths import (
+    get_config_root,
+    get_database_config_dir,
+    get_default_package_config_path,
+    get_divination_data_dir,
+    get_gua_catalog_path,
+    get_llm_catalog_config_path,
+    get_notification_config_dir,
+    get_package_config_path,
+    get_packages_config_dir,
+    get_src_root,
+    get_static_config_dir,
+    get_system_agents_config_path,
+)
+
+__all__ = [
+    "get_config_root",
+    "get_database_config_dir",
+    "get_default_package_config_path",
+    "get_divination_data_dir",
+    "get_gua_catalog_path",
+    "get_llm_catalog_config_path",
+    "get_notification_config_dir",
+    "get_package_config_path",
+    "get_packages_config_dir",
+    "get_src_root",
+    "get_static_config_dir",
+    "get_system_agents_config_path",
+]

backend/src/utils/paths.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def get_src_root() -> Path:
+    return Path(__file__).parent.parent
+
+
+def get_config_root() -> Path:
+    return get_src_root() / "core/config"
+
+
+def get_static_config_dir() -> Path:
+    return get_config_root() / "static"
+
+
+def get_packages_config_dir() -> Path:
+    return get_static_config_dir() / "packages"
+
+
+def get_database_config_dir() -> Path:
+    return get_static_config_dir() / "database"
+
+
+def get_notification_config_dir() -> Path:
+    return get_static_config_dir() / "notification/notifications"
+
+
+def get_divination_data_dir() -> Path:
+    return get_src_root() / "core/divination/data"
+
+
+def get_package_config_path(country: str) -> Path:
+    return get_packages_config_dir() / f"{country.lower()}.yaml"
+
+
+def get_default_package_config_path() -> Path:
+    return get_packages_config_dir() / "default.yaml"
+
+
+def get_llm_catalog_config_path() -> Path:
+    return get_database_config_dir() / "llm_catalog.yaml"
+
+
+def get_system_agents_config_path() -> Path:
+    return get_database_config_dir() / "system_agents.yaml"
+
+
+def get_gua_catalog_path() -> Path:
+    return get_divination_data_dir() / "gua_catalog.json"

backend/src/v1/agent/system_agents_config.py

@@ -16,17 +16,11 @@ from schemas.agent.runtime_config import (
     MessageContextConfig,
     RuntimeConfig,
 )
+from utils.paths import get_system_agents_config_path
 
 
 def _default_system_agents_path() -> Path:
-    return (
-        Path(__file__).resolve().parents[2]
-        / "core"
-        / "config"
-        / "static"
-        / "database"
-        / "system_agents.yaml"
-    )
+    return get_system_agents_config_path()
 
 
 def _load_system_agents_yaml(path: Path | None = None) -> dict[str, object]:

backend/src/v1/points/repository.py

@@ -10,6 +10,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from models.agent_chat_message import AgentChatMessage
 from models.points_audit_ledger import PointsAuditLedger
 from models.points_ledger import PointsLedger
+from models.profile import Profile
 from models.register_bonus_claims import RegisterBonusClaims
 from models.user_points import UserPoints
 from schemas.domain.points import (
@@ -189,3 +190,22 @@ class PointsRepository:
         claim.balance_snapshot = int(balance_snapshot)
         await self._session.flush()
         return True
+
+    async def has_purchased_starter_pack(
+        self,
+        *,
+        email_hash: str,
+    ) -> bool:
+        claim = await self.get_register_bonus_claim(email_hash=email_hash)
+        if claim is None:
+            return False
+        return bool(claim.has_purchased_starter_pack)
+
+    async def get_profile_settings(
+        self,
+        *,
+        user_id: UUID,
+    ) -> dict[str, object] | None:
+        stmt = select(Profile.settings).where(Profile.id == user_id).limit(1)
+        row = (await self._session.execute(stmt)).scalar_one_or_none()
+        return row

backend/src/v1/points/router.py

@@ -6,7 +6,7 @@ from fastapi import APIRouter, Depends
 
 from core.auth.models import CurrentUser
 from v1.points.dependencies import get_points_service
-from v1.points.schemas import PointsBalanceResponse
+from v1.points.schemas import PackagesResponse, PackageInfo, PointsBalanceResponse
 from v1.points.service import PointsService
 from v1.users.dependencies import get_current_user
 
@@ -26,3 +26,31 @@ async def get_points_balance(
         runCost=result.run_cost,
         canRun=result.can_run,
     )
+
+
+@router.get("/packages", response_model=PackagesResponse)
+async def get_available_packages(
+    service: Annotated[PointsService, Depends(get_points_service)],
+    current_user: Annotated[CurrentUser, Depends(get_current_user)],
+) -> PackagesResponse:
+    result = await service.get_available_packages(
+        user_id=current_user.id,
+        user_email=current_user.email or "",
+    )
+
+    return PackagesResponse(
+        region=result.region,
+        currency=result.currency,
+        packages=[
+            PackageInfo(
+                productCode=pkg.product_code,
+                type=pkg.type.value,
+                price=pkg.price,
+                credits=pkg.credits,
+                isStarter=pkg.is_starter,
+                starterEligible=pkg.starter_eligible,
+                sortOrder=pkg.sort_order,
+            )
+            for pkg in result.packages
+        ],
+    )

backend/src/v1/points/schemas.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from typing import Literal
+
 from pydantic import BaseModel, ConfigDict, Field
 
 
@@ -11,3 +13,23 @@ class PointsBalanceResponse(BaseModel):
     available_balance: int = Field(alias="availableBalance", ge=0)
     run_cost: int = Field(alias="runCost", gt=0)
     can_run: bool = Field(alias="canRun")
+
+
+class PackageInfo(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, serialize_by_alias=True)
+
+    product_code: str = Field(alias="productCode", min_length=1, max_length=128)
+    type: Literal["starter", "regular"]
+    price: float = Field(ge=0)
+    credits: int = Field(ge=1)
+    is_starter: bool = Field(alias="isStarter")
+    starter_eligible: bool = Field(alias="starterEligible")
+    sort_order: int = Field(alias="sortOrder", ge=0)
+
+
+class PackagesResponse(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, serialize_by_alias=True)
+
+    region: str = Field(min_length=1, max_length=8)
+    currency: str = Field(min_length=1, max_length=8)
+    packages: list[PackageInfo]

backend/src/v1/points/service.py

@@ -4,9 +4,13 @@ from dataclasses import dataclass
 from decimal import Decimal
 import hashlib
 import hmac
-from typing import Literal
+from typing import TYPE_CHECKING, Literal
 from uuid import UUID, uuid4
 
+from core.config.packages import (
+    PackageType,
+    get_packages_config_for_region,
+)
 from core.config.settings import config
 from core.http.errors import ApiProblemError, problem_payload
 from schemas.domain.points import (
@@ -18,8 +22,12 @@ from schemas.domain.points import (
 )
 from schemas.enums import PointsBizType, PointsChangeType, PointsOperatorType
 from schemas.domain.points import ApplyPointsChangeCommand
+from schemas.shared.user import parse_profile_settings
 from v1.points.repository import PointsRepository
 
+if TYPE_CHECKING:
+    pass
+
 RUN_POINTS_COST = 20
 
 
@@ -55,6 +63,24 @@ class RegisterBonusResult:
     event_id: str
 
 
+@dataclass(frozen=True)
+class PackageInfoResult:
+    product_code: str
+    type: PackageType
+    price: float
+    credits: int
+    sort_order: int
+    is_starter: bool
+    starter_eligible: bool
+
+
+@dataclass(frozen=True)
+class PackagesResult:
+    region: str
+    currency: str
+    packages: list[PackageInfoResult]
+
+
 class PointsService:
     def __init__(self, repository: PointsRepository) -> None:
         self._repository = repository
@@ -408,3 +434,50 @@ class PointsService:
             digestmod=hashlib.sha256,
         )
         return digest.hexdigest()
+
+    async def get_available_packages(
+        self,
+        *,
+        user_id: UUID,
+        user_email: str,
+    ) -> PackagesResult:
+        settings_raw = await self._repository.get_profile_settings(user_id=user_id)
+        settings = parse_profile_settings(settings_raw)
+        country = settings.preferences.country
+
+        pkg_config = get_packages_config_for_region(country)
+        normalized_email = self._normalize_email(user_email)
+
+        has_starter = False
+        if normalized_email:
+            email_hash = self._build_register_bonus_email_hash(normalized_email)
+            has_starter = await self._repository.has_purchased_starter_pack(
+                email_hash=email_hash
+            )
+
+        packages: list[PackageInfoResult] = []
+        for pkg in pkg_config.packages:
+            if not pkg.enabled:
+                continue
+            if pkg.type == PackageType.STARTER and has_starter:
+                continue
+
+            packages.append(
+                PackageInfoResult(
+                    product_code=pkg.product_code,
+                    type=pkg.type,
+                    price=pkg.price,
+                    credits=pkg.credits,
+                    sort_order=pkg.sort_order,
+                    is_starter=pkg.type == PackageType.STARTER,
+                    starter_eligible=(
+                        pkg.type == PackageType.STARTER and not has_starter
+                    ),
+                )
+            )
+
+        return PackagesResult(
+            region=pkg_config.region,
+            currency=pkg_config.currency,
+            packages=sorted(packages, key=lambda p: p.sort_order),
+        )