# Onboarding App Shell（高层规范）

## 1. 背景与目标

本需求用于落地客户端的“首次进入体验 + 主应用壳 + 关键入口”，包含：

- 3–5 页可跳过的 Onboarding（问题页均可跳过）
- Push 设置页（可跳过）
- 进入主 App：支持“点赞/讨厌”交互
- 收藏夹入口
- 通用设置入口：版本信息、iOS 小组件入口

### 目标

- **首次体验顺畅**：用户可完成或跳过 Onboarding 与 Push 设置，不阻塞进入主功能
- **主功能可用**：进入主 App 后可对内容进行“点赞/讨厌”，并能进入收藏夹与设置
- **入口清晰**：收藏夹与设置入口明显且可从主界面到达
- **状态可持久化**：Onboarding 完成状态、Push 设置选择（是否跳过）、点赞/讨厌记录、收藏记录可持久化

### 非目标（本阶段不做）

- 不实现完整推送业务闭环（仅做“设置入口/引导”，且可跳过）
- 不实现真实推荐算法（内容来源可先用本地 mock 或固定列表）
- iOS 小组件不要求完整上线交互（先做“入口/说明/引导”即可，实际小组件实现可拆分到后续模块）

## 2. 用户流程（高层）

### 2.1 首次启动

1. App 启动
2. Onboarding（3–5 页）
   - 每页都提供 **跳过**（Skip）
   - 支持上一页/下一页（可选）
3. Push 设置页（可选进入，且可跳过）
4. 进入主 App（内容卡片/列表）并可点赞/讨厌

### 2.2 非首次启动

- 若已完成（或跳过）Onboarding：直接进入主 App

## 3. 功能需求（高层）

### 3.1 Onboarding（3–5 页，问题可跳过）

- **页数**：3–5 页（可配置）
- **内容**：以“问题/偏好收集”为主（具体题目可后续在内容配置中迭代）
- **跳过策略**：
  - 每页可跳过（不强制填写）
  - 最终可一键跳过整个 Onboarding
- **视觉反馈**：
  - 进度指示（例如 1/5 或进度条）
  - 清晰的“下一步/跳过”按钮

### 3.2 Push 设置（可跳过）

- 提供一页“开启通知”的引导与说明
- 支持：
  - **立即开启**（触发权限申请）
  - **稍后**（跳过）
- 用户选择需持久化（用于后续在设置页再次引导）

### 3.3 主 App：点赞/讨厌

- 主界面展示一条“情绪文字/正念短句/卡片内容”
- 支持两种操作：
  - **点赞（Like）**
  - **讨厌（Dislike）**
- 行为结果：
  - 记录用户操作（本地持久化）
  - 点赞内容可进入收藏夹（或点赞即收藏，具体规则在实现时确认）

### 3.4 收藏夹入口

- 主界面提供“收藏夹”入口
- 收藏夹展示已收藏内容列表
- 支持取消收藏（可选）

### 3.5 通用设置入口

设置页至少包含：

- **版本信息**：展示 App 版本号（和可选的 build number）
- **iOS 小组件**：入口/说明
  - 提供“如何添加小组件”的引导文案
  - 若后续实现小组件配置页，可从此入口进入
- **通知设置**（可选，但建议有）：
  - 展示当前通知状态
  - 允许用户再次进入系统设置开启通知（iOS/Android 跳转能力按平台支持情况实现）

## 4. 数据与持久化（高层）

需要持久化的最小集合：

- `onboarding.completed`: boolean
- `push.promptState`: `enabled | skipped | unknown`
- `content.reactions`: 记录内容 ID 与 like/dislike
- `favorites.items`: 收藏内容列表（按 ID 存储）

> 说明：本期可采用本地存储（例如 AsyncStorage）；后续可扩展为与后端同步。

## 5. 页面与导航（建议）

- `Onboarding`（多页）
- `PushPrompt`（可跳过）
- `Home`（点赞/讨厌）
- `Favorites`（收藏夹）
- `Settings`（通用设置：版本、iOS 小组件）

若使用 `expo-router`：

- Onboarding 可用分组路由（例如 `(onboarding)`）管理，并在完成后跳转到 `(tabs)` 或 `Home`

## 6. 验收标准

- 首次进入：
  - 可完成或跳过 Onboarding（任意页可跳过）
  - Push 设置页可跳过
  - 最终一定能进入主 App
- 主功能：
  - 主界面可对内容执行点赞/讨厌并记录
  - 存在收藏夹入口且可看到收藏内容
  - 存在设置入口且能看到版本与 iOS 小组件入口/说明
- 持久化：
  - 重启 App 后，Onboarding 不会重复出现（除非主动清除状态）
  - 点赞/收藏记录仍存在

## 7. 风险与注意事项

- 通知权限申请时机：过早弹窗可能导致拒绝率上升，建议通过引导页解释后再触发
- iOS 小组件能力受系统限制：刷新频率与内容更新不保证严格实时
- 内容来源：若暂未接后端，需提供可替换的 mock 内容与唯一 ID 方案