qzl
225 lines
6.2 KiB
Markdown
225 lines
6.2 KiB
Markdown
# 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
|
||
|
||
|
||
## Session 3: 修复通知 targets 约束、合并注册脚本、路径缩短及清理重复索引
|
||
|
||
**Date**: 2026-04-16
|
||
**Task**: 修复通知 targets 约束、合并注册脚本、路径缩短及清理重复索引
|
||
|
||
### Summary
|
||
|
||
(Add summary)
|
||
|
||
### Main Changes
|
||
|
||
## 完成的四项任务
|
||
|
||
| 任务 | 描述 |
|
||
|------|------|
|
||
| 重复索引清理 | 创建 Alembic migration drop `ix_llm_factory_name` 和 `ix_llms_model_code` |
|
||
| 脚本合并 | `register-notifications.sh` 合并到 `dev-migrate.sh sync-notifications` 子命令 |
|
||
| 路径缩短 | `static/notification/notifications/` → `static/notifications/` |
|
||
| Targets 语义约束 | `NotificationTargetMode` 枚举 + 注册流程按 target_mode 分发通知 |
|
||
|
||
## 关键变更
|
||
|
||
| 模块 | 变更 |
|
||
|------|------|
|
||
| 枚举 | `NotificationTargetMode` (new_users/exist_users/all_users/user_ids) |
|
||
| ORM | `Notification.target_mode` VARCHAR + CHECK constraint |
|
||
| 注册流程 | `RegisterBonusResult.is_first_registration` 区分首次注册 |
|
||
| 通知分发 | `link_notifications_for_registered_user` 按 target_mode 过滤 |
|
||
| YAML | `welcome_points.yaml` mode 改为 `new_users` |
|
||
| 死代码 | 删除 `link_published_notifications_to_user` |
|
||
|
||
## 数据库 Migration
|
||
|
||
- `20260416_0002_drop_duplicate_llm_indexes.py` - 清理重复索引
|
||
- `20260416_0003_add_notification_target_mode.py` - 添加 target_mode 列
|
||
|
||
## 测试
|
||
|
||
- 44 个单元测试
|
||
- 1 个集成测试 (注册 + 重新注册通知分发)
|
||
- 全部通过
|
||
|
||
## 文件统计
|
||
|
||
- 26 files changed
|
||
- +1011 insertions
|
||
- -49 deletions
|
||
|
||
|
||
### Git Commits
|
||
|
||
| Hash | Message |
|
||
|------|---------|
|
||
| `c79c773` | (see git log) |
|
||
|
||
### Testing
|
||
|
||
- [OK] (Add test results)
|
||
|
||
### Status
|
||
|
||
[OK] **Completed**
|
||
|
||
### Next Steps
|
||
|
||
- None - task complete
|