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** - 计划已制定，等待实现