qzl
ff40ff9dd8
- 数据库：添加 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 和字段
2.8 KiB
2.8 KiB
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
-
现有数据结构分析
register_bonus_claims表已存在，用于注册送分去重- 表结构包含：
email_hash（唯一）、user_email_snapshot、first_user_id_snapshot、balance_snapshot、grant_event_id - 已支持删除账号后重注册恢复余额的功能
-
设计方案
- 在
register_bonus_claims添加has_purchased_starter_pack字段 - 利用现有
email_hash唯一约束保证同一邮箱只能购买一次 - 后端提供
/api/v1/points/starter-pack/eligibilityAPI - 前端根据 API 返回决定是否展示礼包
- 在
-
参考现有实现
- 已有计划文档：
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
- 字段命名：
has_purchased_starter_pack（布尔型），简洁明确 - API 设计：仅返回资格状态和礼包信息，不涉及支付逻辑
- 本期限制：
- 不实现支付流程
- 不实现支付验证
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
- 实现 Phase 1：数据库迁移和 Model 更新
- 实现 Phase 2：后端 API
- 实现 Phase 3：前端集成
- 实现 Phase 4：文档与测试