新增文档说明

spec_kit/Splash Consent/plan.md

@@ -0,0 +1,112 @@
+# Splash Consent（技术计划）
+
+## 1. 计划目标
+
+实现客户端开屏页（Splash/Welcome）与首次协议同意逻辑：
+
+- 使用 `client/assets/images/index/` 的图片作为主视觉（例如 `index_flowers.png`）
+- 底部渐变按钮颜色：`#F69F7B → #F99CC0`
+- 按钮下方提供「隐私协议」「用户使用协议」外部链接入口（先用占位链接）
+- **仅首次出现按钮**：当 `consent.accepted=true` 后不再展示同意按钮与协议入口
+- 同意后进入现有启动分发：`app/index.tsx`（继续走 Onboarding/App Shell）
+
+## 2. 默认技术决策
+
+- **路由**：沿用 `expo-router`
+- **持久化**：沿用 `AsyncStorage`
+- **协议打开方式**：外部链接（`expo-web-browser` 或 `Linking.openURL`）
+- **渐变实现**：使用 `expo-linear-gradient`（Expo 官方）
+
+## 3. 路由与流程设计
+
+### 3.1 新增路由
+
+- `app/(splash)/splash.tsx`：开屏页（图片 + 首次同意按钮/协议入口）
+- `app/(splash)/_layout.tsx`：可选（一般无需 header）
+
+### 3.2 启动分发逻辑（与现有流程集成）
+
+当前已存在启动分发 `app/index.tsx`（根据 `onboarding.completed` 跳转）。
+
+本需求将启动分发扩展为两段判断：
+
+1. 若 `consent.accepted !== true`：跳转到 `/(splash)/splash`
+2. 若 `consent.accepted === true`：沿用原逻辑（进入 Onboarding 或 `/(app)/home`）
+
+> 注意：你确认的是“隐藏按钮而不是隐藏页面”。因此当 `consent.accepted=true` 时，开屏页不需要停留；可直接跳过该页进入原启动分发。
+
+## 4. 数据与持久化
+
+### 4.1 Key
+
+- `consent.accepted`: boolean
+
+### 4.2 存储封装
+
+在现有 `src/storage/appStorage.ts` 中补充：
+
+- `getConsentAccepted(): Promise<boolean>`
+- `setConsentAccepted(accepted: boolean): Promise<void>`
+
+并确保所有 UI 不直接硬编码 key。
+
+## 5. UI 细节与交互
+
+### 5.1 开屏布局（建议）
+
+- 主视觉图片：
+  - 使用 `index_flowers.png`
+  - 适配：`resizeMode="contain"` 或按实际视觉调整（不裁切关键内容）
+- 底部区域（贴近安全区）：
+  - 渐变按钮（圆角、阴影/投影轻微）
+  - 协议入口（两段文字按钮，左右排列或一行内间隔）
+
+### 5.2 渐变按钮（仅首次出现）
+
+- 展示条件：`consent.accepted !== true`
+- 点击行为：
+  - 写入 `consent.accepted=true`
+  - 跳转到 `/`（触发 `app/index.tsx` 继续分发）
+
+### 5.3 协议入口（外部链接，先占位）
+
+- 「隐私协议」：`https://example.com/privacy`
+- 「用户使用协议」：`https://example.com/terms`
+
+打开方式：
+
+- 优先：`expo-web-browser` 打开外部链接
+- 兜底：`Linking.openURL`
+
+## 6. i18n 文案
+
+新增 key（至少 `zh-CN/en`，其余语言可逐步补齐）：
+
+- `consent.title`（可选）
+- `consent.agree`（按钮文案：同意并继续）
+- `consent.privacy`（隐私协议）
+- `consent.terms`（用户使用协议）
+
+## 7. 实施步骤
+
+1. 新增 `consent.accepted` 的存储读写方法
+2. 新增 `/(splash)/splash` 页面（图片 + 渐变按钮 + 协议入口）
+3. 修改 `app/index.tsx`：在 onboarding 分发前插入 consent gate
+4. 接入 `expo-linear-gradient` 并完成按钮 UI
+5. 接入外部链接打开（先占位 URL）
+6. 补齐 i18n key（至少 zh-CN/en）
+7. 自测：
+   - 首次启动：显示按钮与入口；同意后进入 Onboarding/App
+   - 再次启动：不再出现同意按钮，直接进入后续流程
+
+## 8. 验收标准
+
+- 首次启动：
+  - 展示开屏图片
+  - 渐变按钮颜色正确（`#F69F7B → #F99CC0`）
+  - 协议入口可点击并打开外部链接
+  - 点击同意后进入后续流程
+- 非首次启动：
+  - 不再出现同意按钮与协议入口
+  - 直接进入后续流程（Onboarding/App Shell）
+

spec_kit/Splash Consent/spec.md

@@ -0,0 +1,103 @@
+# Splash Consent（高层规范）
+
+## 1. 背景与目标
+
+客户端需要一个开屏页（Splash/Welcome），用于展示品牌视觉并在**首次加载**时让用户同意隐私协议与用户使用协议。用户同意后进入后续流程（Onboarding/App）。
+
+### 目标
+
+- **视觉开屏**：使用 `client/assets/images/index/` 下的图片资源作为主视觉
+- **首次同意**：底部渐变按钮仅在首次加载时出现，用于“同意并继续”
+- **协议入口**：按钮下方提供「隐私协议」「用户使用协议」入口，用户可点击查看
+- **状态持久化**：同意后不再显示该按钮（后续启动直接进入后续流程）
+
+### 非目标（本阶段不做）
+
+- 不实现复杂的协议版本管理（如协议更新后重新弹出），后续可扩展
+- 不实现后端拉取协议内容（可先使用本地静态页面或外链）
+
+## 2. 范围与交付物
+
+### 范围
+
+- 新增开屏页 UI 与路由接入
+- 新增“首次同意”状态的本地持久化
+- 协议入口（跳转到 WebView/外部浏览器/内置页面，方案在实现阶段确定）
+
+### 交付物
+
+- 开屏页（含图片、按钮、协议入口）
+- 本地持久化 key 约定与读写逻辑
+- README/文档更新（可选）
+
+## 3. 视觉与交互需求
+
+### 3.1 主视觉
+
+- 使用 `client/assets/images/index/` 下的图片资源（例如 `index_flowers.png`）
+- 布局建议：
+  - 图片居中或铺满上半部分（按实际设计微调）
+  - 适配不同屏幕尺寸，确保不变形/不裁切关键内容
+
+### 3.2 底部渐变按钮（仅首次出现）
+
+- **出现条件**：仅在首次加载且未同意协议时显示
+- **按钮文案**：建议“同意并继续”（文案可后续调整，需支持 i18n）
+- **按钮渐变色**：从 `#F69F7B` 到 `#F99CC0`
+- **点击行为**：
+  - 写入本地状态：用户已同意
+  - 跳转到后续流程入口（例如 Onboarding 或 Home 的启动分发）
+
+### 3.3 协议入口
+
+- 位于按钮下方，展示：
+  - **隐私协议**
+  - **用户使用协议**
+- 点击行为：打开对应协议内容
+  - 支持外链或内置页面（实现阶段确认）
+
+## 4. 首次加载判定与持久化
+
+### 4.1 判定规则
+
+- **首次加载定义**：App 首次启动且用户未完成协议同意
+
+### 4.2 存储 Key（建议）
+
+- `consent.accepted`: boolean
+
+> 说明：后续如需协议版本化，可扩展为 `consent.versionAccepted = <version>`。
+
+## 5. 路由与流程（与现有客户端集成）
+
+### 5.1 流程顺序（建议）
+
+1. App 启动
+2. 若 `consent.accepted !== true`：进入开屏页（展示按钮与协议入口）
+3. 用户点击“同意并继续”后：
+   - 写入 `consent.accepted=true`
+   - 进入后续流程（例如 Onboarding/App Shell 的启动分发）
+
+### 5.2 与现有功能的关系
+
+- 开屏页位于 Onboarding 之前（更符合“先同意协议再使用”的要求）
+- 同意后按既有规则继续：
+  - 已完成 onboarding：进入 Home
+  - 未完成 onboarding：进入 Onboarding
+
+## 6. 验收标准
+
+- 首次启动：
+  - 出现开屏页，展示图片
+  - 底部渐变按钮可见，颜色正确（`#F69F7B` → `#F99CC0`）
+  - “隐私协议/用户使用协议”可点击打开
+  - 点击“同意并继续”后进入后续流程
+- 非首次启动：
+  - 不再出现“同意按钮”（且开屏页按产品要求可直接跳过或不再展示）
+  - 直接进入后续流程
+
+## 7. 风险与注意事项
+
+- 协议内容来源若为外链，需要保证链接长期可用；若为本地页面，需要考虑后续更新机制
+- iOS 不同机型安全区（底部 Home Indicator）需保证按钮与协议入口不被遮挡
+

spec_kit/Splash Consent/tasks.md

@@ -0,0 +1,109 @@
+# Splash Consent（任务清单）
+
+> 说明：本清单根据 `plan.md` 拆解，要求“可执行、可验收、可标记”。  
+> 标记规则：执行完成后将对应项从 `- [ ]` 改为 `- [x]`，并把“状态”改为 **已完成**；进行中改为 **进行中**；阻塞写明原因与解除条件。
+
+## 0. UI 参考（本次实现对齐）
+
+- **参考截图**：你提供的开屏页样式（花束插画 + 文案 + 圆角渐变按钮 + 协议入口）
+- **图片资源**：`client/assets/images/index/index_flowers.png`
+- **按钮渐变色**：`#F69F7B` → `#F99CC0`
+- **交互约束**：
+  - 仅首次（未同意）显示“同意按钮 + 协议入口”
+  - 同意后写入本地 `consent.accepted=true`，并进入既有启动分发 `app/index.tsx`
+
+## 1. 依赖与基础设施
+
+- [ ] **安装并接入渐变组件（Expo 官方）**  
+  - **状态**：未开始  
+  - **命令**：
+
+```bash
+cd client
+pnpm add expo-linear-gradient
+```
+
+  - **验收**：项目可正常启动，页面可渲染渐变按钮
+
+- [ ] **确认外部链接打开方式（expo-web-browser）可用**  
+  - **状态**：未开始  
+  - **说明**：已存在依赖则跳过安装；否则安装 `expo-web-browser`（当前项目初始化模板通常已包含）  
+  - **验收**：能通过代码打开 `https://example.com/*` 外链
+
+## 2. 本地存储：协议同意状态
+
+- [ ] **在 `src/storage/appStorage.ts` 增加 consent 读写方法**  
+  - **状态**：未开始  
+  - **Key**：`consent.accepted`  
+  - **新增 API（建议）**：
+    - `getConsentAccepted(): Promise<boolean>`
+    - `setConsentAccepted(accepted: boolean): Promise<void>`
+  - **验收**：不在 UI 代码里硬编码 key；重启后状态仍然保留
+
+## 3. 路由与启动分发接入
+
+- [ ] **新增开屏路由：`app/(splash)/splash.tsx`**  
+  - **状态**：未开始  
+  - **要求**：
+    - 展示主视觉图片（`index_flowers.png`）
+    - 底部区域包含：渐变按钮 + 协议入口（仅未同意时显示）
+  - **验收**：路由可访问并正常渲染 UI
+
+- [ ] **修改 `app/index.tsx`：增加 consent gate**  
+  - **状态**：未开始  
+  - **规则**：
+    - 若 `consent.accepted !== true`：跳转到 `/(splash)/splash`
+    - 否则沿用原逻辑（Onboarding / Home）
+  - **验收**：首次启动先到开屏；同意后进入既有分发
+
+## 4. 开屏页 UI 落地（对齐参考图）
+
+- [ ] **布局与样式实现（适配安全区）**  
+  - **状态**：未开始  
+  - **布局建议（可微调）**：
+    - 顶部：插画居中，`resizeMode="contain"`
+    - 中部：主文案（支持 i18n）
+    - 底部：渐变按钮（圆角/阴影轻微）+ 协议入口（文本按钮）
+    - 注意底部 Home Indicator 安全区
+  - **验收**：不同屏幕尺寸下不遮挡、不溢出，整体视觉接近参考图
+
+- [ ] **渐变按钮（仅首次出现）**  
+  - **状态**：未开始  
+  - **颜色**：`#F69F7B` → `#F99CC0`  
+  - **点击行为**：
+    - `setConsentAccepted(true)`
+    - `router.replace('/')`（回到启动分发）
+  - **验收**：点击后按钮不再出现（重启仍不出现），并进入后续流程
+
+- [ ] **协议入口（外部链接，占位 URL）**  
+  - **状态**：未开始  
+  - **链接**：
+    - 隐私协议：`https://example.com/privacy`
+    - 用户使用协议：`https://example.com/terms`
+  - **打开方式**：优先 `expo-web-browser`，兜底 `Linking.openURL`
+  - **验收**：点击可打开外链；失败时不崩溃（可 toast/alert 提示）
+
+## 5. i18n 文案补齐
+
+- [ ] **新增开屏相关 i18n key（至少 zh-CN/en，尽量补齐 5 语）**  
+  - **状态**：未开始  
+  - **建议 key**：
+    - `consent.title`（可选）
+    - `consent.subtitle`（可选）
+    - `consent.agree`
+    - `consent.privacy`
+    - `consent.terms`
+  - **验收**：开屏页不出现硬编码长句；切换语言可生效
+
+## 6. 自测与验收
+
+- [ ] **首次启动流程自测**  
+  - **状态**：未开始  
+  - **路径**：Splash（显示按钮/协议入口）→ 同意 → 进入 `app/index.tsx` 分发（Onboarding/Home）  
+  - **验收**：与 `spec.md` / `plan.md` 验收一致
+
+- [ ] **非首次启动流程自测**  
+  - **状态**：未开始  
+  - **路径**：直接进入 `app/index.tsx` 分发（不再出现同意按钮与协议入口）  
+  - **验收**：同意状态持久化生效
+