init

spec_kit/Client Bootstrap/spec.md

@@ -0,0 +1,129 @@
+# 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 配置与平台后台完成相应设置
+