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 和字段
2026-04-16 16:11:09 +08:00
parent 443c0c80ae
commit ff40ff9dd8
38 changed files with 1434 additions and 2517 deletions
@@ -0,0 +1,476 @@
+# 新人初始礼包购买追踪功能
+
+## 1. 需求概述
+
+### 1.1 背景
+
+用户需要追踪是否已购买新人初始礼包（$0.99/60积分），以便前端支付页面决定是否展示该礼包。同时需要将前端硬编码的套餐信息改为后端动态配置，支持按国家/地区区分不同套餐。
+
+### 1.2 核心需求
+
+1. 在 `register_bonus_claims` 表添加字段，标记是否购买了新人初始礼包
+2. 后端提供统一的套餐信息 API，包含新人礼包资格检查
+3. 前端从后端动态获取套餐信息，不再硬编码
+4. 支持按国家/地区（ISO 3166-1 alpha-2）提供不同套餐配置
+5. 修改用户 profile 的默认国家/地区为中国改为美国
+6. **本期不实现**：支付流程、支付验证逻辑
+
+### 1.3 业务规则
+
+- 同一邮箱只能购买一次新人礼包
+- 删除账号后同邮箱重新注册，不刷新新人礼包资格
+- 新人礼包规格：$0.99 / 60 积分（美国区）
+- 不同国家/地区可配置不同套餐和价格
+
+### 1.4 国家/地区标识符
+
+采用 **ISO 3166-1 alpha-2** 标准（两位字母代码）：
+
+| 代码 | 国家/地区 |
+|------|----------|
+| `US` | 美国（默认） |
+| `CN` | 中国大陆 |
+| `TW` | 台湾 |
+| `HK` | 香港 |
+| `JP` | 日本 |
+
+## 2. 技术方案
+
+### 2.1 静态配置文件
+
+#### 文件路径
+
+```
+backend/src/core/config/static/packages/
+├── us.yaml     # 美国区套餐配置
+├── cn.yaml     # 中国区套餐配置（预留）
+└── default.yaml # 默认配置（无匹配时使用）
+```
+
+#### 配置格式（us.yaml）
+
+```yaml
+region: US
+currency: USD
+packages:
+  - product_code: new_user_pack_099_60
+    type: starter
+    price_usd: "0.99"
+    credits: 60
+    badge: null
+    sort_order: 0
+    enabled: true
+    
+  - product_code: basic_pack_499_100
+    type: regular
+    price_usd: "4.99"
+    credits: 100
+    badge: null
+    sort_order: 10
+    enabled: true
+    
+  - product_code: popular_pack_799_210
+    type: regular
+    price_usd: "7.99"
+    credits: 210
+    badge: "Popular"
+    sort_order: 20
+    enabled: true
+    
+  - product_code: premium_pack_1299_415
+    type: regular
+    price_usd: "12.99"
+    credits: 415
+    badge: null
+    sort_order: 30
+    enabled: true
+```
+
+#### 配置字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `region` | string | ISO 3166-1 alpha-2 国家代码 |
+| `currency` | string | 货币代码（ISO 4217） |
+| `packages` | array | 套餐列表 |
+| `packages[].product_code` | string | 产品唯一标识 |
+| `packages[].type` | string | `starter`（新人）或 `regular`（常规） |
+| `packages[].price_usd` | string | 价格（美元） |
+| `packages[].credits` | int | 积分数量 |
+| `packages[].badge` | string? | 标签（如 "Popular"） |
+| `packages[].sort_order` | int | 排序权重 |
+| `packages[].enabled` | bool | 是否启用 |
+
+### 2.2 数据库变更
+
+#### 表：`register_bonus_claims`
+
+当前结构：
+```sql
+- id: UUID PK
+- email_hash: VARCHAR(64) UNIQUE
+- user_email_snapshot: TEXT
+- first_user_id_snapshot: UUID NULL
+- balance_snapshot: BIGINT NULL
+- grant_event_id: VARCHAR(64) UNIQUE
+- created_at / updated_at
+```
+
+新增字段：
+```sql
+- has_purchased_starter_pack: BOOLEAN NOT NULL DEFAULT FALSE
+  -- 标记是否已购买新人初始礼包
+```
+
+#### 迁移文件
+
+- 文件名：`20260416_0001_add_starter_pack_tracking.py`
+- 路径：`backend/alembic/versions/`
+
+### 2.3 后端实现
+
+#### 2.3.1 配置加载层
+
+新建目录结构：
+```
+backend/src/core/config/packages/
+├── __init__.py
+├── loader.py       # 配置加载器
+├── schema.py       # Pydantic 模型
+└── registry.py     # 配置注册表
+```
+
+文件：`backend/src/core/config/packages/schema.py`
+
+```python
+from decimal import Decimal
+from enum import Enum
+from pydantic import BaseModel
+
+class PackageType(str, Enum):
+    STARTER = "starter"
+    REGULAR = "regular"
+
+class PackageConfig(BaseModel):
+    product_code: str
+    type: PackageType
+    price_usd: Decimal
+    credits: int
+    badge: str | None = None
+    sort_order: int = 0
+    enabled: bool = True
+
+class RegionPackagesConfig(BaseModel):
+    region: str
+    currency: str
+    packages: list[PackageConfig]
+```
+
+#### 2.3.2 Model 层
+
+文件：`backend/src/models/register_bonus_claims.py`
+
+新增字段：
+```python
+has_purchased_starter_pack: Mapped[bool] = mapped_column(
+    Boolean, nullable=False, default=False
+)
+```
+
+#### 2.3.3 Repository 层
+
+文件：`backend/src/v1/points/repository.py`
+
+新增方法：
+```python
+async def has_purchased_starter_pack(
+    self,
+    *,
+    email_hash: str,
+) -> bool:
+    """Check if user has purchased starter pack"""
+    claim = await self.get_register_bonus_claim(email_hash=email_hash)
+    if claim is None:
+        return False
+    return bool(claim.has_purchased_starter_pack)
+```
+
+#### 2.3.4 Service 层
+
+文件：`backend/src/v1/points/service.py`
+
+新增方法：
+```python
+async def get_available_packages(
+    self,
+    *,
+    country: str,
+    user_email: str,
+) -> PackagesResult:
+    """Get available packages for user's region with eligibility info"""
+    config = get_packages_config_for_region(country)
+    email_hash = self._build_register_bonus_email_hash(
+        self._normalize_email(user_email)
+    )
+    has_starter = await self._repository.has_purchased_starter_pack(
+        email_hash=email_hash
+    )
+    
+    packages = []
+    for pkg in config.packages:
+        if not pkg.enabled:
+            continue
+        if pkg.type == PackageType.STARTER and has_starter:
+            continue
+        packages.append(PackageInfo(
+            product_code=pkg.product_code,
+            type=pkg.type,
+            price_usd=pkg.price_usd,
+            credits=pkg.credits,
+            badge=pkg.badge,
+            is_starter=pkg.type == PackageType.STARTER,
+            starter_eligible=(pkg.type == PackageType.STARTER and not has_starter),
+        ))
+    
+    return PackagesResult(
+        region=config.region,
+        currency=config.currency,
+        packages=sorted(packages, key=lambda p: p.sort_order),
+    )
+```
+
+#### 2.3.5 Schema 层
+
+文件：`backend/src/v1/points/schemas.py`
+
+新增：
+```python
+class PackageInfo(BaseModel):
+    productCode: str
+    type: Literal["starter", "regular"]
+    priceUsd: Decimal
+    credits: int
+    badge: str | None = None
+    isStarter: bool
+    starterEligible: bool
+    sortOrder: int
+
+class PackagesResponse(BaseModel):
+    region: str
+    currency: str
+    packages: list[PackageInfo]
+```
+
+#### 2.3.6 Router 层
+
+文件：`backend/src/v1/points/router.py`
+
+**删除**原计划的独立路由 `/starter-pack/eligibility`。
+
+新增统一路由：
+```python
+@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:
+    """Get available packages for current user's region"""
+    country = current_user.settings.get("preferences", {}).get("country", "US")
+    result = await service.get_available_packages(
+        country=country,
+        user_email=current_user.email,
+    )
+    return PackagesResponse(
+        region=result.region,
+        currency=result.currency,
+        packages=[
+            PackageInfo(
+                productCode=pkg.product_code,
+                type=pkg.type,
+                priceUsd=pkg.price_usd,
+                credits=pkg.credits,
+                badge=pkg.badge,
+                isStarter=pkg.is_starter,
+                starterEligible=pkg.starter_eligible,
+                sortOrder=pkg.sort_order,
+            )
+            for pkg in result.packages
+        ],
+    )
+```
+
+### 2.4 前端实现
+
+#### 2.4.1 API 调用
+
+文件：`apps/lib/features/points/data/packages_repository.dart`
+
+```dart
+Future<PackagesResult> getPackages() async {
+  final response = await _dio.get('/api/v1/points/packages');
+  return PackagesResult.fromJson(response.data);
+}
+```
+
+#### 2.4.2 数据模型
+
+文件：`apps/lib/features/points/data/models/package_info.dart`
+
+```dart
+enum PackageType { starter, regular }
+
+class PackageInfo {
+  final String productCode;
+  final PackageType type;
+  final Decimal priceUsd;
+  final int credits;
+  final String? badge;
+  final bool isStarter;
+  final bool starterEligible;
+  final int sortOrder;
+  // ...
+}
+```
+
+#### 2.4.3 UI 展示逻辑
+
+文件：`apps/lib/features/settings/presentation/screens/coin_center_screen.dart`
+
+修改逻辑：
+- 页面加载时调用 `GET /api/v1/points/packages`
+- 遍历 `packages` 列表动态渲染卡片
+- `isStarter=true` 且 `starterEligible=true` 时展示新人礼包
+- `isStarter=true` 且 `starterEligible=false` 时跳过（已购买）
+- 移除硬编码的套餐数据
+
+### 2.5 Profile 默认值修改
+
+#### 后端
+
+文件：`backend/src/schemas/domain/profile.py`（如存在）
+
+修改默认值：
+```python
+class PreferenceSettings(BaseModel):
+    interface_language: str = "zh-CN"
+    ai_language: str = "zh-CN"
+    timezone: str = "Asia/Shanghai"
+    country: str = "US"  # 从 "CN" 改为 "US"
+```
+
+#### 前端
+
+文件：`apps/lib/features/settings/data/models/profile_settings.dart`
+
+修改默认值：
+```dart
+class PreferenceSettings {
+  const PreferenceSettings({
+    this.interfaceLanguage = 'zh-CN',
+    this.aiLanguage = 'zh-CN',
+    this.timezone = 'Asia/Shanghai',
+    this.country = 'US',  // 从 'CN' 改为 'US'
+  });
+  // ...
+}
+```
+
+### 2.6 协议文档更新
+
+文件：`docs/protocols/common/user-points-chat-data-protocol.md`
+
+新增章节：
+- `GET /api/v1/points/packages` API 说明
+- `has_purchased_starter_pack` 字段说明
+- 静态配置文件格式说明
+
+## 3. 实现步骤
+
+### Phase 1: 数据库与配置层
+
+1. 创建静态配置文件（`us.yaml`、`default.yaml`）
+2. 创建配置加载器（`backend/src/core/config/packages/`）
+3. 创建 Alembic 迁移文件
+4. 更新 `RegisterBonusClaims` model
+5. 运行迁移验证
+
+### Phase 2: 后端 API
+
+1. 更新 schemas（`PackagesResponse`、`PackageInfo`）
+2. 更新 repository
+3. 更新 service
+4. 更新 router（统一 `/packages` 路由）
+5. 编写单元测试
+6. 本地验证 API
+
+### Phase 3: Profile 默认值
+
+1. 修改后端 schema 默认值
+2. 修改前端 model 默认值
+3. 验证新用户注册后的默认国家
+
+### Phase 4: 前端集成
+
+1. 创建数据模型（`PackageInfo`、`PackagesResult`）
+2. 创建 API 调用层
+3. 更新 `CoinCenterScreen` 动态渲染
+4. 移除硬编码套餐数据
+5. 本地测试
+
+### Phase 5: 文档与验证
+
+1. 更新协议文档
+2. 更新 HTTP error codes（如需要）
+3. 集成测试
+4. Code review
+
+## 4. 测试计划
+
+### 4.1 后端单元测试
+
+文件：`backend/tests/unit/test_packages_service.py`
+
+测试用例：
+- 美国区用户获取套餐列表
+- 新人礼包未购买 → 列表中包含 starter 包
+- 新人礼包已购买 → 列表中不含 starter 包
+- 未配置地区 → 使用默认配置
+
+### 4.2 后端集成测试
+
+文件：`backend/tests/integration/test_packages_api.py`
+
+测试用例：
+- 注册用户查询套餐
+- 不同国家用户获取不同配置
+- 购买后再次查询
+
+### 4.3 前端测试
+
+- 页面加载正确调用 API
+- 动态渲染套餐卡片
+- 新人礼包展示/隐藏逻辑
+
+## 5. 风险与限制
+
+### 5.1 本期限制
+
+- 不实现支付流程
+- 不实现支付验证
+- `has_purchased_starter_pack` 字段暂时只读，后续支付流程会写入
+- 仅实现美国区配置，其他地区预留
+
+### 5.2 后续扩展
+
+- 接入 iOS IAP 支付
+- 实现支付验证与入账
+- 实现退款冲正
+- 添加其他国家/地区配置
+- 价格本地化（多币种支持）
+
+## 6. 参考文档
+
+- 完整支付计划：`docs/plans/ios-new-user-pack-payment-plan.md`
+- 数据协议：`docs/protocols/common/user-points-chat-data-protocol.md`
+- HTTP 错误码：`docs/protocols/common/http-error-codes.md`
+- ISO 3166-1 alpha-2: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
@@ -0,0 +1,153 @@
+{
+  "id": "starter-package-purchase-tracking",
+  "name": "starter-package-purchase-tracking",
+  "title": "新人初始礼包购买追踪 + 动态套餐配置",
+  "description": "在 register_bonus_claims 表添加字段追踪是否购买新人初始礼包，创建静态配置文件管理套餐，提供统一的套餐信息 API",
+  "status": "planning",
+  "dev_type": "fullstack",
+  "scope": ["backend", "apps"],
+  "priority": "P2",
+  "creator": "zl-q",
+  "assignee": "zl-q",
+  "createdAt": "2026-04-16",
+  "completedAt": null,
+  "branch": "worktree/feat-starter-package-purchase-tracking",
+  "base_branch": "dev",
+  "worktree_path": "/home/qzl/Code/eryao/.worktrees/feat-starter-package-purchase-tracking",
+  "current_phase": 0,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [
+    {
+      "id": "static-config",
+      "title": "静态配置：创建套餐配置文件（us.yaml, default.yaml）",
+      "status": "completed",
+      "phase": 1
+    },
+    {
+      "id": "config-loader",
+      "title": "配置加载层：创建 packages loader/schema/registry",
+      "status": "pending",
+      "phase": 1
+    },
+    {
+      "id": "db-migration",
+      "title": "数据库迁移：添加 has_purchased_starter_pack 字段",
+      "status": "pending",
+      "phase": 1
+    },
+    {
+      "id": "backend-model",
+      "title": "后端 Model 层：更新 RegisterBonusClaims",
+      "status": "pending",
+      "phase": 1
+    },
+    {
+      "id": "backend-repository",
+      "title": "后端 Repository 层：添加查询方法",
+      "status": "pending",
+      "phase": 1
+    },
+    {
+      "id": "backend-service",
+      "title": "后端 Service 层：实现套餐获取与资格检查逻辑",
+      "status": "pending",
+      "phase": 1
+    },
+    {
+      "id": "backend-schema",
+      "title": "后端 Schema 层：定义 PackagesResponse/PackageInfo",
+      "status": "pending",
+      "phase": 1
+    },
+    {
+      "id": "backend-router",
+      "title": "后端 Router 层：添加统一 GET /packages 路由",
+      "status": "pending",
+      "phase": 1
+    },
+    {
+      "id": "profile-default-country",
+      "title": "Profile 默认值：country 从 CN 改为 US（前后端）",
+      "status": "pending",
+      "phase": 1
+    },
+    {
+      "id": "backend-tests",
+      "title": "后端单元测试",
+      "status": "pending",
+      "phase": 1
+    },
+    {
+      "id": "frontend-models",
+      "title": "前端数据模型：PackageInfo/PackagesResult",
+      "status": "pending",
+      "phase": 1
+    },
+    {
+      "id": "frontend-api",
+      "title": "前端 API 调用层",
+      "status": "pending",
+      "phase": 1
+    },
+    {
+      "id": "frontend-ui",
+      "title": "前端 UI：CoinCenterScreen 动态渲染套餐",
+      "status": "pending",
+      "phase": 1
+    },
+    {
+      "id": "docs-protocol",
+      "title": "更新协议文档",
+      "status": "pending",
+      "phase": 1
+    },
+    {
+      "id": "integration-test",
+      "title": "集成测试验证",
+      "status": "pending",
+      "phase": 2
+    }
+  ],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [
+    "backend/src/core/config/static/packages/us.yaml",
+    "backend/src/core/config/static/packages/default.yaml",
+    "backend/src/core/config/packages/loader.py",
+    "backend/src/core/config/packages/schema.py",
+    "backend/src/core/config/packages/registry.py",
+    "backend/src/models/register_bonus_claims.py",
+    "backend/src/v1/points/repository.py",
+    "backend/src/v1/points/service.py",
+    "backend/src/v1/points/schemas.py",
+    "backend/src/v1/points/router.py",
+    "apps/lib/features/settings/data/models/profile_settings.dart",
+    "apps/lib/features/settings/presentation/screens/coin_center_screen.dart",
+    "docs/protocols/common/user-points-chat-data-protocol.md"
+  ],
+  "notes": "本期不实现支付流程，仅提供套餐信息查询 API。采用 ISO 3166-1 alpha-2 国家代码。",
+  "meta": {
+    "country_code_standard": "ISO 3166-1 alpha-2",
+    "default_country": "US",
+    "packages_count": 4
+  }
+}
@@ -8,7 +8,7 @@

 <!-- @@@auto:current-status -->
 - **Active File**: `journal-1.md`
- **Total Sessions**: 9
+- **Total Sessions**: 1
 - **Last Active**: 2026-04-16
 <!-- @@@/auto:current-status -->

@@ -19,7 +19,7 @@
 <!-- @@@auto:active-documents -->
 | File | Lines | Status |
 |------|-------|--------|
-| `journal-1.md` | ~477 | Active |
+| `journal-1.md` | ~80 | Active |
 <!-- @@@/auto:active-documents -->

 ---
@@ -29,21 +29,13 @@
 <!-- @@@auto:session-history -->
 | # | Date | Title | Commits |
 |---|------|-------|---------|
-| 9 | 2026-04-16 | 起卦教程首次访问追踪 + Agent时间上下文 | `69b34bd` |
-| 8 | 2026-04-15 | Session deletion anonymization for iOS compliance | `c2b726e` |
-| 7 | 2026-04-15 | 六爻算法修复 + Prompt架构重构 + i18n输出规则 | `9598d16`, `be68681` |
-| 6 | 2026-04-13 | 修复追问链路与上限判定 | - |
-| 5 | 2026-04-13 | feat: 邀请码显示功能 - 后端API + 前端对接 | - |
-| 4 | 2026-04-13 | 绑定积分重注册余额恢复提交 | `c55be6d` |
-| 3 | 2026-04-13 | 积分重注册余额恢复验证 | - |
-| 2 | 2026-04-10 | 静态通知同步 + 积分审计 bug 修复 | `3f3d613` |
-| 1 | 2026-04-10 | 实现站内通知系统 | `3f3d613` |
+| 1 | 2026-04-16 | 新人初始礼包购买追踪功能 - 计划制定 | - |
 <!-- @@@/auto:session-history -->

 ---

 ## Notes

+- Worktree workspace for: `worktree/feat-starter-package-purchase-tracking`
 - Sessions are appended to journal files
 - New journal file created when current exceeds 2000 lines
- Use `add_session.py` to record sessions
@@ -1,477 +1,84 @@
-# Journal - zl-q (Part 1)
+# Journal - zl-q

-> AI development session journal
-> Started: 2026-04-10
+> Development session records for worktree: feat-starter-package-purchase-tracking

 ---

-
-
-## Session 1: 实现站内通知系统
-
-**Date**: 2026-04-10
-**Task**: 实现站内通知系统
-
-### Summary
-
-(Add summary)
-
-### Main Changes
-
-## 完成内容
-
-| 模块 | 描述 |
-|------|------|
-| 协议文档 | `docs/protocols/notification/notification-inbox-protocol.md` 及 `http-error-codes.md` 新增 `NOTIFICATION_NOT_FOUND` |
-| 数据库迁移 | `notifications` + `user_notifications` 两张表, RLS 策略, 索引 |
-| 后端 ORM | `Notification(TimestampMixin, SoftDeleteMixin, Base)` + `UserNotification(TimestampMixin, Base)` |
-| 后端 API | schema/repository/service/router 全套, 4 个端点 (列表/未读数/单条已读/全部已读) |
-| 后端测试 | 19 个单元测试覆盖: 列表权限隔离, 未读数统计, 幂等已读, 越权拒绝, 撤销/删除过滤, payload 解析 |
-| Flutter models | `NotificationPayload` sealed class (none/open_route/open_url) + `NotificationItem` + `NotificationListResult` |
-| Flutter API | `NotificationApi` (list/unreadCount/markRead/markAllRead) |
-| Flutter Repository | 抽象接口 + `NotificationRepositoryImpl` |
-| Flutter Bloc | `NotificationBloc` (ChangeNotifier) 含 Realtime 事件处理 |
-| Flutter UI | `NotificationCenterScreen` + `NotificationListItem` + 首页 badge 集成 |
-| Flutter 测试 | 14 个测试: payload 解析 6 个 + bloc 状态管理 8 个 |
-
-## 验收标准对照
-
- [x] 能为指定用户写入一条站内通知 (ORM + migration 就绪)
- [x] 用户能看到自己的通知列表 (GET /notifications)
- [x] 用户点击通知后可标记为已读 (PATCH /notifications/{id}/read)
- [x] "全部已读"后未读数归零 (PATCH /notifications/mark-all-read)
- [x] 用户 A 不能读取或修改用户 B 的通知 (service 层 user_id 来自 JWT, 测试覆盖)
- [x] 已读接口重复调用不会报错 (幂等实现, 测试覆盖)
- [x] 首页 badge 会随未读数自动更新 (NotificationBloc + ListenableBuilder)
- [x] 撤销或统一删除主通知后, 用户侧列表不再展示 (repository 过滤 status+deleted_at)
-
-
-### Git Commits
-
-| Hash | Message |
-|------|---------|
-| `3f3d613` | (see git log) |
-
-### Testing
-
- [OK] (Add test results)
-
-### Status
-
-[OK] **Completed**
-
-### Next Steps
-
- None - task complete
-
-
-## Session 2: 静态通知同步 + 积分审计 bug 修复
-
-**Date**: 2026-04-10
-**Task**: 静态通知同步 + 积分审计 bug 修复
-
-### Summary
-
-(Add summary)
-
-### Main Changes
-
-## 完成内容
-
-| 功能 | 说明 |
-|------|------|
-| 静态通知 Pydantic Schema | `static_schema.py` — 含 `deleted` 字段支持显式软删除 |
-| 静态通知同步逻辑 | `static_sync.py` — 创建、更新、撤销、软删除、prune、reconcile-targets |
-| CLI 命令 | `sync-notifications` 支持 `--path/--source-key/--dry-run/--prune/--reconcile-targets` |
-| 数据库迁移 | 新增 `source/source_key/source_version/content_hash` 字段 |
-| 示例通知 | `welcome_points.yaml` |
-| 触发脚本 | `infra/scripts/register-notifications.sh` |
-| 协议文档 | `static-notification-sync-protocol.md` |
-| Bug 修复 | `AuditLedgerMetadata` 未序列化直接写 JSONB → `.model_dump(mode="json")` |
-| 单测 | 28 passed（`test_static_notification_sync.py`、`test_notification_service.py`） |
-| 冒烟验证 | 注册→通知→未读数→reconcile-targets→prune 全链路通过 |
-
-**未完成**:
- `notification_updated` Realtime 事件链路
- Flutter 端通知中心页面、badge、Realtime 订阅
-
-**新增文件**:
- `backend/src/core/config/notification/__init__.py`
- `backend/src/core/config/notification/static_schema.py`
- `backend/src/core/config/notification/static_sync.py`
- `backend/src/core/config/static/notification/notifications/welcome_points.yaml`
- `backend/alembic/versions/20260411_0005_add_notification_static_sync_fields.py`
- `backend/tests/unit/test_static_notification_sync.py`
- `docs/protocols/notification/static-notification-sync-protocol.md`
- `infra/scripts/register-notifications.sh`
-
-**修改文件**:
- `backend/src/core/runtime/cli.py`
- `backend/src/models/notification.py`
- `backend/src/v1/points/repository.py`
- `docs/plans/static-notification-sync-plan.md`
-
-
-### Git Commits
-
-| Hash | Message |
-|------|---------|
-| `3f3d613` | (see git log) |
-
-### Testing
-
- [OK] (Add test results)
-
-### Status
-
-[OK] **Completed**
-
-### Next Steps
-
- None - task complete
-
-
-## Session 3: 积分重注册余额恢复验证
-
-**Date**: 2026-04-13
-**Task**: 积分重注册余额恢复验证
-
-### Summary
-
-完成 register_bonus_claims 快照方案的本地迁移与集成测试验证，确认删除账号后重注册可恢复删除前积分余额。
-
-### Main Changes
-
-| Feature | Description |
-|---------|-------------|
-| DB Migration | 通过 `dev-migrate.sh migrate` 应用 `20260413_0004_register_bonus_claims_snapshot`，新增 `first_user_id_snapshot` 与 `balance_snapshot`，移除 `first_user_id`。 |
-| Restore Logic | 注册流程优先读取 `balance_snapshot` 恢复余额；删除账号前写入当前余额快照。 |
-| Integration Tests | 新增未消费删号重注册恢复场景，并更新已有消费后删号重注册断言。 |
-
-**Updated Files**:
- `backend/alembic/versions/20260413_0004_register_bonus_claims_snapshot.py`
- `backend/src/models/register_bonus_claims.py`
- `backend/src/v1/points/repository.py`
- `backend/src/v1/points/service.py`
- `backend/src/v1/users/service.py`
- `backend/tests/integration/test_register_run_delete_reregister.py`
- `backend/tests/unit/test_points_service_audit.py`
- `docs/protocols/common/user-points-chat-data-protocol.md`
-
-**Verification**:
- `uv run pytest backend/tests/unit/test_points_service_audit.py` -> 5 passed
- `uv run pytest backend/tests/integration/test_register_run_delete_reregister.py` -> 2 passed
- Supabase MCP 查询确认 `register_bonus_claims.balance_snapshot` 已写入并与测试行为一致。
-
-
-### Git Commits
-
-(No commits - planning session)
-
-### Testing
-
- [OK] (Add test results)
-
-### Status
-
-[OK] **Completed**
-
-### Next Steps
-
- None - task complete
-
-
-## Session 4: 绑定积分重注册余额恢复提交
-
-**Date**: 2026-04-13
-**Task**: 绑定积分重注册余额恢复提交
-
-### Summary
-
-将删除账号后重注册积分余额恢复 feature 的代码提交与 session 记录绑定。
-
-### Main Changes
-
-| Item | Details |
-|------|---------|
-| Feature Commit | `c55be6d` |
-| Scope | register_bonus_claims 快照字段、删号前余额快照、重注册余额恢复、相关测试与协议更新 |
-
-**Validation**:
- pre-commit hooks passed during commit
- integration: `backend/tests/integration/test_register_run_delete_reregister.py` passed (`2 passed`)
-
-
-### Git Commits
-
-| Hash | Message |
-|------|---------|
-| `c55be6d` | (see git log) |
-
-### Testing
-
- [OK] (Add test results)
-
-### Status
-
-[OK] **Completed**
-
-### Next Steps
-
- None - task complete
-
-
-## Session 5: feat: 邀请码显示功能 - 后端API + 前端对接
-
-**Date**: 2026-04-13
-**Task**: feat: 邀请码显示功能 - 后端API + 前端对接
-
-### Summary
-
-(Add summary)
-
-### Main Changes
-
-## Backend 新增 (src/v1/invite/)
-
-| 文件 | 描述 |
-|------|------|
-| schemas.py | `MyInviteCodeResponse` (code, used_count) |
-| repository.py | `InviteCodeRepository.get_by_owner_id()` |
-| service.py | `InviteCodeService.get_my_invite_code()` |
-| dependencies.py | 依赖注入 |
-| router.py | `GET /api/v1/invite/me` |
-
-修改: `src/v1/router.py` - 注册 invite_router
-
-## Frontend 新增/修改 (apps/lib/features/settings/)
-
-新增:
- `data/models/my_invite_code.dart` - `MyInviteCode` 数据模型
- `data/apis/invite_api.dart` - API 调用
- `data/repositories/invite_repository.dart` - Repository 封装
-
-修改:
- `invite_screen.dart` - 移除 mock 数据，改为调用真实 API，增加 loading/error 状态
- `settings_screen.dart` - 接收 `InviteRepository` 参数
- `home_screen.dart` - 创建并传递 `InviteRepository` 实例
-
-**验证**: ruff check ✅ / flutter analyze ✅
-
-
-### Git Commits
-
-(No commits - planning session)
-
-### Testing
-
- [OK] (Add test results)
-
-### Status
-
-[OK] **Completed**
-
-### Next Steps
-
- None - task complete
-
-
-## Session 6: 修复追问链路与上限判定
-
-**Date**: 2026-04-13
-**Task**: 修复追问链路与上限判定
-
-### Summary
-
-定位并修复 follow_up 上下文解析报错；将追问上限改为基于 assistant 回复数；补充单测与集成测试并通过。
-
-### Main Changes
-
-| 项目 | 说明 |
-|------|------|
-| 追问报错根因 | `worker-agent.log` 中 `AgentChatMessageMetadata` 校验失败，原因是历史 metadata 存在 snake_case 字段与 alias 契约不一致 |
-| 结构修复 | `divination` 相关模型启用 `populate_by_name=True`，允许 snake_case/alias 一致解析；用户消息缓存写入统一 `by_alias=True` |
-| 上限逻辑 | 会话运行上限由按 user 消息数改为按 assistant 消息数统计 |
-| 回归测试 | 新增 `backend/tests/unit/test_runtime_context_messages.py` 覆盖 snake_case metadata 场景 |
-| 集成测试 | 新增 `backend/tests/integration/test_follow_up_flow.py`，验证 chat->follow_up 成功、assistant=2 后再次 follow_up 返回 409 |
-
-**验证结果**:
- `uv run ruff check`（相关文件）通过
- `uv run pytest backend/tests/unit/test_runtime_context_messages.py backend/tests/unit/test_runtime_models_worker_output.py backend/tests/unit/test_history_message_schema.py` 通过
- `./infra/scripts/app.sh restart` 后，`uv run pytest backend/tests/integration/test_follow_up_flow.py` 通过
-
-
-### Git Commits
-
-(No commits - planning session)
-
-### Testing
-
- [OK] (Add test results)
-
-### Status
-
-[OK] **Completed**
-
-### Next Steps
-
- None - task complete
-
-
-## Session 7: 六爻算法修复 + Prompt架构重构 + i18n输出规则
-
-**Date**: 2026-04-15
-**Task**: 六爻算法修复 + Prompt架构重构 + i18n输出规则
-
-### Summary
-
-(Add summary)
-
-### Main Changes
-
-## 概述
-
-本次会话完成了六爻核心算法的全面审计修复、prompt架构重构清理、以及多语言输出规则适配。
-
-### 算法修复 (P0/P1)
-
-| 问题 | 修复内容 |
-|------|----------|
-| P0-1 空亡判断 | 改为仅从日柱计算，年月空亡仅标注不断事 |
-| P0-2 暗动逻辑 | 重写为静爻+旺相+日冲三条件 |
-| P1-1 月破 | 独立标注 |
-| P1-2 动不为空/旺不为空 | 补充判断 |
-| P1-3 三合局 | 新增判断逻辑 |
-| P1-4 反吟伏吟 | 新增判断逻辑 |
-| P1-5 日辰十二长生 | 新增字段 `riChenZhangSheng` |
-| P1-6 回头生克 | 新增判断逻辑 |
-
-### Prompt架构重构
-
- **删除 `_build_env_section`**：不再向prompt泄露用户上下文（user_context、timezone、client_time等）
- **简化语言判断**：删除 `if is_chinese` 分支，`_LANGUAGE_LABELS` 已覆盖全部语言映射
- **安全规则改为六爻专属**：只回答六爻占卜相关问题，拒绝无关提问
- **`_WORKER_OUTPUT_RULES` 多语言适配**：zh-CN/zh-Hant/en 三版本，按 `ai_language` 分发
- **`_WORKER_ROLE_PLAYING` 始终中文**：保证六爻专业性不受语言切换影响
- **`sign_level` 枚举统一**：所有语言版本强制使用简体中文枚举值（上上签/中上签/中下签/下下签），前端负责显示映射
- **`worker_rules.py` 独立文件**管理多语言规则
-
-### 清理死代码
-
- 删除 `UserPreferences`/`RuntimePromptContext` 及全部辅助函数
- 删除 runner 中 `runtime_client_time` 参数链路
- 删除 `SystemAgentRuntimeConfig.extra_context`
- 删除 `sections.py` 中 `env` section marker
- 删除 `AgentPromptRegistry` 死代码
- runner 中 `ai_language` 从 `user_context.settings.preferences` 提取传入prompt
-
-### 安全规则
-
- `AGENTS.md` 添加 Git Safety 规则（禁止未经批准的破坏性git操作）
- `.opencode/opencode.json` 添加高危git命令审批配置
-
-### 测试
-
- 新增 22 个六爻算法单元测试
- 重写 7 个 prompt 测试适配新签名
- 全部 85 个单元测试通过
-
-**修改文件 (14)**:
- `backend/src/core/divination/derivation.py`
- `backend/src/schemas/domain/divination.py`
- `apps/lib/features/divination/data/models/divination_backend_models.dart`
- `backend/src/core/agentscope/prompts/system_prompt.py`
- `backend/src/core/agentscope/prompts/agent_prompt.py`
- `backend/src/core/agentscope/prompts/worker_rules.py` (新)
- `backend/src/core/agentscope/prompts/sections.py`
- `backend/src/core/agentscope/prompts/user_prompt.py`
- `backend/src/core/agentscope/runtime/runner.py`
- `backend/tests/unit/test_agentscope_prompts.py`
- `backend/tests/unit/test_divination_derivation.py` (新)
- `docs/plans/liuyao-algorithm-audit.md`
- `AGENTS.md`
- `.opencode/opencode.json`
-
-
-### Git Commits
-
-| Hash | Message |
-|------|---------|
-| `9598d16` | (see git log) |
-| `be68681` | (see git log) |
-
-### Testing
-
- [OK] (Add test results)
-
-### Status
-
-[OK] **Completed**
-
-### Next Steps
-
- None - task complete
-
-
-## Session 8: Session deletion anonymization for iOS compliance
-
-**Date**: 2026-04-15
-**Task**: Session deletion anonymization for iOS compliance
-
-### Summary
-
-Replace soft-delete with anonymize + hard-delete. Add anonymous_session_snapshots table for analytics. Remove points_ledger.biz_id FK constraint for snapshot-style reference.
-
-### Main Changes
-
-
-
-### Git Commits
-
-| Hash | Message |
-|------|---------|
-| `c2b726e` | (see git log) |
-
-### Testing
-
- [OK] (Add test results)
-
-### Status
-
-[OK] **Completed**
-
-### Next Steps
-
- None - task complete
-
-
-## Session 9: 起卦教程首次访问追踪 + Agent时间上下文
+## Session 1: 新人初始礼包购买追踪功能 - 计划制定

 **Date**: 2026-04-16
-**Task**: 起卦教程首次访问追踪 + Agent时间上下文
+**Task**: starter-package-purchase-tracking

 ### Summary

-实现了起卦教程首次访问追踪功能，包括后端 ProfileSettings 添加 DivinationTutorialSettings 字段、前端三处起卦页面添加首次访问检测和弹窗提示、使用本地状态管理避免并发覆盖问题、Agent系统提示添加时间上下文信息。
+在独立 worktree 中创建新人初始礼包购买追踪功能的实现计划。

-### Main Changes
+### Background

+用户需求：追踪用户是否已购买新人初始礼包（$0.99/60积分），以便前端支付页面决定是否展示该礼包。

+### Analysis

-### Git Commits
+1. **现有数据结构分析**
+   - `register_bonus_claims` 表已存在，用于注册送分去重
+   - 表结构包含：`email_hash`（唯一）、`user_email_snapshot`、`first_user_id_snapshot`、`balance_snapshot`、`grant_event_id`
+   - 已支持删除账号后重注册恢复余额的功能

-| Hash | Message |
+2. **设计方案**
+   - 在 `register_bonus_claims` 添加 `has_purchased_starter_pack` 字段
+   - 利用现有 `email_hash` 唯一约束保证同一邮箱只能购买一次
+   - 后端提供 `/api/v1/points/starter-pack/eligibility` API
+   - 前端根据 API 返回决定是否展示礼包
+
+3. **参考现有实现**
+   - 已有计划文档：`docs/plans/ios-new-user-pack-payment-plan.md`
+   - 完整支付计划包含：支付订单表、支付事件审计表、验单流程等
+   - 本期仅实现资格查询，不涉及支付流程
+
+### Implementation Plan
+
+#### Phase 1: 数据库层
+- 创建 Alembic 迁移：`20260416_0001_add_starter_pack_tracking.py`
+- 添加字段：`has_purchased_starter_pack BOOLEAN NOT NULL DEFAULT FALSE`
+- 更新 Model：`backend/src/models/register_bonus_claims.py`
+
+#### Phase 2: 后端 API
+- Schema：定义 `StarterPackEligibilityResponse`、`StarterPackInfo`
+- Repository：添加 `has_purchased_starter_pack()` 方法
+- Service：实现 `check_starter_pack_eligibility()` 逻辑
+- Router：添加 `GET /api/v1/points/starter-pack/eligibility` 路由
+
+#### Phase 3: 前端集成
+- 创建 API 调用层
+- 更新支付页面 UI 展示逻辑
+
+#### Phase 4: 文档与测试
+- 更新协议文档
+- 编写单元测试和集成测试
+
+### Key Decisions
+
+1. **字段命名**：`has_purchased_starter_pack`（布尔型），简洁明确
+2. **API 设计**：仅返回资格状态和礼包信息，不涉及支付逻辑
+3. **本期限制**：
+   - 不实现支付流程
+   - 不实现支付验证
+   - `has_purchased_starter_pack` 字段暂时只读
+
+### Files Created
+
+| File | Purpose |
 |------|---------|
-| `69b34bd` | (see git log) |
-
-### Testing
-
- [OK] (Add test results)
-
-### Status
-
-[OK] **Completed**
+| `.trellis/tasks/04-16-starter-package-purchase-tracking/task.json` | 任务配置 |
+| `.trellis/tasks/04-16-starter-package-purchase-tracking/prd.md` | 需求与实现计划 |

 ### Next Steps

- None - task complete
+1. 实现 Phase 1：数据库迁移和 Model 更新
+2. 实现 Phase 2：后端 API
+3. 实现 Phase 3：前端集成
+4. 实现 Phase 4：文档与测试
+
+### Status
+
+# **In Progress** - 计划已制定，等待实现