mindfulness/spec_kit/Client Bootstrap/spec.md

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 配置与平台后台完成相应设置