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/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),
+        )