mindfulness/spec_kit/App Push/tasks.md

App Push｜每日提醒推送（客户端 + 后端）｜Tasks

阶段：任务清单（tasks）

依赖：spec_kit/App Push/spec.md、spec_kit/App Push/plan.md

---

0. 约束与共识（本期已确认）

• 每日次数：0～5 条/天
• 发送窗口：9:00～24:00（按客户端上报时区）
• 时间点：窗口内 随机抖动
• 勿扰：不做
• 文案：使用后端推荐模块的 Push 场景个性化模板（降风险）

---

1. 客户端（Expo RN）

1.1 UUID（client_user_id）

• 在 client/src/storage/appStorage.ts（或新模块）实现：
  • getOrCreateClientUserId(): Promise<string>
  • 首次生成 UUID 并持久化，后续复用

1.2 Push 权限与 token

• 接入获取 Expo Push Token 的封装（例如 src/features/push/）：
  • 获取权限状态
  • 请求权限
  • 获取 Expo Push Token
• 在 Onboarding / push 引导完成后：
  • granted 时：获取 token + 调 register
  • 未 granted：仅保存本地设置，不阻塞进入主功能

1.3 “每日提醒次数”入口

• Onboarding：新增/复用一个步骤页面
  • 选择 0～5 次（0 表示关闭）
  • 支持跳过
  • 完成后写本地存储，并调用后端 preferences
• 个人主页弹窗：
  • 修复“测试模式强制无权限”的逻辑
  • 次数限制 0～5；关闭等价 0
  • denied 时提示去系统设置
  • 修改后写本地存储，并调用后端 preferences

1.4 接口封装

• 新增 client/src/services/pushApi.ts
  • registerPushToken(...)
  • setPushPreferences(...)
  • getPushPreferences(...)（可选）
• 统一使用 client/src/utils/http.ts 的请求封装

1.5 联调开关与日志

• 开发环境输出必要日志（不打印敏感信息）：
  • client_user_id 生成结果
  • 权限状态与 token 是否获取成功
  • register/preferences 的请求是否成功与错误原因

---

2. 后端（FastAPI）

2.1 数据模型与迁移

• 新增表（或等价模型）：
  • push_tokens
  • push_preferences
  • push_send_log（幂等防重复）
• 增加迁移脚本（Alembic 或项目现有迁移机制）

注意：不执行任何破坏性数据库操作；运行迁移前若涉及真实库，需要你明确回复“允许操作数据库”。

2.2 API

• POST /v1/push/register
  • 幂等：env + app_id + push_token 唯一
  • 更新 client_user_id 归属与 last_seen_at
• PUT /v1/push/preferences
  • 校验 times_per_day ∈ [0,5]
  • enabled=false 或 times_per_day=0 时停止后续推送
• GET /v1/push/preferences
  • 返回当前偏好与更新时间
• POST /v1/push/test（仅 dev）
  • 立即向该用户发送一条测试推送（用于真机联调）

2.3 Expo 推送发送器

• 实现 send_expo_push(token, title, body, data?)
  • 处理 Expo 返回错误并对不可恢复错误停用 token
  • 记录发送结果到 push_send_log

2.4 推送文案（推荐模板）

• 在推送任务中调用后端推荐模块的 Push 场景模板：
  • 输入：client_user_id、语言/时区（可选）
  • 输出：title/body
  • 默认“降个性化/降风险”

---

3. 定时任务（每日计划 + ETA 发送）

• 每日“计划生成任务”
  • 扫描 enabled && times_per_day>0 用户
  • 按用户时区在 9:00～24:00 生成 N 个随机抖动时间点
  • 写入 push_send_log（唯一键保证幂等）
  • 投递 ETA 发送任务（或按项目现有任务系统实现）
• ETA “发送任务”
  • 拉取当次发送所需 token/偏好
  • 生成文案（推荐模板）
  • 调用 Expo push 发送
  • 更新 push_send_log 状态

---

4. 验收与回归

• iOS 真机：权限申请、token 获取、test 推送可达
• Android 真机：权限申请、token 获取、test 推送可达
• 修改次数：后端计划生成正确（一天内不超发）
• 关闭：后端停止后续推送（不再生成计划/不再发送）