# Client Bootstrap（高层规范）

## 1. 背景与目标

本需求用于初始化「正念 APP」客户端工程的高层规范，确保项目具备一致的工程结构、环境区分、国际化、多端调试与打包流程，并为后续推送、小组件、情绪卡片等一期功能落地提供清晰边界。

### 目标

- **工程可运行**：开发者可在本地启动 Expo 开发服务器并在模拟器/真机调试
- **环境可切换**：支持 dev/prod 两套环境变量与配置切换
- **多语言可扩展**：支持 CN/EN/ES/PT/TC 五种语言，并具备动态切换与回退策略
- **目录标准化**：采用标准 Expo + TypeScript 目录结构，便于持续扩展
- **打包可执行**：支持 EAS Build 的 iOS 打包流程（dev/prod 基本约定）

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

- 不在本阶段实现完整业务 UI/交互细节（以工程骨架与规范为主）
- 不在本阶段实现后端接口与数据库设计（由 `server/` 侧需求承接）
- 不保证小组件在所有刷新频率下的严格准时（受 iOS 系统限制）

## 2. 范围与交付物

### 范围

- 客户端工程初始化与文档化（`client/`）
- 推送/小组件/卡片滑动的高层能力约束与接口对齐点（不实现具体代码亦可）
- 国际化（i18n）规范与资源组织方式

### 交付物

- **`client/README.md`**：可运行、可联调、可打包、可扩展的客户端说明文档
- **客户端工程目录结构规范**：`app/`（可选 expo-router）+ `src/` 的职责划分
- **i18n 规范**：语言码、资源文件组织、回退策略、动态切换策略

## 3. 用户与核心使用场景

- **用户**：宝妈群体（情绪支持与正念练习）
- **开发者场景**：
  - 新成员可按文档快速启动项目并联调后端
  - 能在 dev/prod 之间切换并进行 iOS 构建
  - 能新增一条文案并同步到五种语言资源中

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

### 4.1 基础工程能力

- 支持 Expo 本地启动与 iOS/Android 运行入口
- 支持网络请求基座（Axios 或 Fetch）与 API Base URL 配置
- 支持状态管理基座（Zustand ）

### 4.2 环境区分（dev / prod）

- 客户端使用 `.env.dev` / `.env.prod` 管理环境变量
- `.env` 不提交到 Git，提供 `.env.example` 作为模板
- 推荐使用 `EXPO_PUBLIC_` 前缀的公开变量（如 `EXPO_PUBLIC_API_BASE_URL`）
- dev/prod 的 bundle id 约定：
  - dev：`com.damer.mindfulness.dev`
  - prod：`com.damer.mindfulness`

### 4.3 多语言（CN/EN/ES/PT/TC）

- 支持语言码：
  - CN：`zh-CN`
  - EN：`en`
  - ES：`es`
  - PT：`pt`
  - TC：`zh-TW`
- 推荐方案：`i18next` + `react-i18next` + `expo-localization`
- 文案 key 需稳定（点分层），支持插值，避免字符串拼接
- **默认语言选择**：优先使用用户当前**设备语言**（在支持列表内时生效）
- **手动切换**：在“设置”中支持切换语言，切换后持久化（例如 AsyncStorage），并在后续启动中优先生效
- **回退策略**：设备语言不在支持列表时，回退到 `zh-CN`（或团队指定的默认语言）
- 如后端需要多语言（如推送文案），语言码需与客户端一致，并在接口中明确 `lang`

### 4.4 推送（一期能力约束）

- 客户端需能：
  - 申请通知权限
  - 获取 Push Token
  - 将 Token 上报后端（接口字段与鉴权方式由联调阶段确认）
- 后端需能：
  - 保存 Token
  - 按策略触发定时推送（固定时间/用户自定义时间）
  - 支持后台配置推送内容并更新

### 4.5 iOS 小组件（一期能力约束）

- 展示：当前情绪文字 + 背景图/渐变
- 支持：小/中/大三种尺寸
- 数据源：本地缓存或后端拉取（需定义刷新/缓存策略）
- 刷新：可配置刷新频率，但需接受 iOS 系统限制导致的不确定性

### 4.6 情绪卡片滑动（一期能力约束）

- 展示情绪卡片列表
- 左右滑动切换下一张（类似 Tinder）
- 收藏/分享作为后续迭代（不纳入本阶段验收）

## 5. 技术与工程规范

### 5.1 目录结构（标准建议）

- 推荐 `expo-router`：使用 `app/` 作为路由目录
- 业务代码统一放入 `src/`，并按功能域拆分 `features/`
- 资源放入 `assets/`
- 配置文件：`app.json` 或 `app.config.ts`、`eas.json`、`package.json`

### 5.2 依赖与工具（建议）

- Node.js：LTS
- 包管理器：pnpm（团队统一）
- Expo：推荐通过 `npx expo` 使用，避免全局版本漂移
- iOS 真机调试：macOS + Xcode（如需）

## 6. 验收标准

- 文档层面：
  - `client/README.md` 明确：启动方式、环境变量、联调方式、EAS 构建方式、多语言规范、标准目录结构
- 工程层面（当客户端代码提交后）：
  - 可在本地 `pnpm install` 后启动并运行到 iOS/Android
  - 可切换 dev/prod 环境变量并影响 API Base URL
  - i18n 可在运行时切换到 `zh-CN/en/es/pt/zh-TW` 并生效

## 7. 风险与注意事项

- iOS 小组件刷新频率受系统限制：规范中应强调“尽力而为”的体验目标
- 真机联调 `localhost` 不可用：需使用局域网 IP 或内网穿透
- 推送与证书/配置相关：需在 EAS 配置与平台后台完成相应设置