130 lines
5.2 KiB
Markdown
130 lines
5.2 KiB
Markdown
# 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 配置与平台后台完成相应设置
|
||
|