eryao/.trellis/workspace/zl-q/journal-1.md

# Journal - zl-q

> Development session records for worktree: feat-starter-package-purchase-tracking

---

## Session 1: 新人初始礼包购买追踪功能 - 计划制定

**Date**: 2026-04-16
**Task**: starter-package-purchase-tracking

### Summary

在独立 worktree 中创建新人初始礼包购买追踪功能的实现计划。

### Background

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

### Analysis

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

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 |
|------|---------|
| `.trellis/tasks/04-16-starter-package-purchase-tracking/task.json` | 任务配置 |
| `.trellis/tasks/04-16-starter-package-purchase-tracking/prd.md` | 需求与实现计划 |

### Next Steps

1. 实现 Phase 1：数据库迁移和 Model 更新
2. 实现 Phase 2：后端 API
3. 实现 Phase 3：前端集成
4. 实现 Phase 4：文档与测试

### Status

# **In Progress** - 计划已制定，等待实现


## Session 2: 新人初始礼包购买追踪功能实现

**Date**: 2026-04-16
**Task**: 新人初始礼包购买追踪功能实现

### Summary

(Add summary)

### Main Changes

## 功能概述

实现新人初始礼包购买追踪功能，支持动态套餐配置和按国家/地区区分。

## 后端实现

| 模块 | 变更 |
|------|------|
| 数据库 | 添加 `has_purchased_starter_pack` 字段到 `register_bonus_claims` |
| 配置管理 | 创建 `backend/src/core/config/packages/` 静态配置加载层 |
| 路径工具 | 创建 `backend/src/utils/paths.py` 统一路径管理 |
| API | 新增 `GET /api/v1/points/packages` 返回可用套餐 |
| 默认值 | Profile 默认国家改为 `US`（ISO 3166-1 alpha-2） |

## 前端实现

| 模块 | 变更 |
|------|------|
| 数据模型 | 创建 `ProductCode` 枚举约束，前后端类型安全 |
| API 调用 | 新增 `PointsApi.getPackages()` |
| UI | `CoinCenterScreen` 动态渲染套餐，移除硬编码 |
| l10n | 添加 `settingsCoinPackStarter` 翻译 |

## 配置文件

- `backend/src/core/config/static/packages/us.yaml` - 美国区套餐配置
- `backend/src/core/config/static/packages/default.yaml` - 默认套餐配置

## 技术亮点

- ProductCode 枚举约束：后端 Pydantic Literal + 前端 Dart enum
- 统一路径管理：移除 5 处硬编码路径拼接
- Cross-layer 检查：修复 `profile_api.dart` fallback 不一致问题

## 文件统计

- 38 files changed
- +1452 insertions
- -2535 deletions


### Git Commits

| Hash | Message |
|------|---------|
| `ff40ff9` | (see git log) |
| `fd0df28` | (see git log) |

### Testing

- [OK] (Add test results)

### Status

[OK] **Completed**

### Next Steps

- None - task complete