init

spec_kit/Client Bootstrap/plan.md

@@ -0,0 +1,127 @@
+# Client Bootstrap（技术计划）
+
+## 1. 计划目标
+
+基于 `spec.md` 的约束，落地一套可执行的客户端工程初始化方案，保证：
+
+- 开发者可本地启动与联调
+- dev/prod 环境区分清晰
+- i18n 支持 CN/EN/ES/PT/TC 并支持动态切换
+- 目录结构标准化，可持续扩展
+- EAS Build iOS 打包流程可执行
+
+## 2. 默认技术决策（本计划采用）
+
+- **Node.js**：建议 **20.x LTS**（最低 **18.x LTS**）
+- **包管理器**：pnpm（建议 **9.x**，最低 **8.x**）
+- **路由**：优先采用 `expo-router`（使用 `app/` 目录）
+  - 若项目已使用 React Navigation，则保留 `src/navigation/` + `src/screens/` 的方案（见“可替代方案”）
+- **i18n**：`i18next` + `react-i18next` + `expo-localization`
+- **环境变量**：`.env.dev` / `.env.prod` + `EXPO_PUBLIC_` 前缀
+- **网络层**：统一封装 `src/services/`（Axios 或 Fetch 二选一，先按 Axios 预留结构）
+- **状态管理**：Zustand（与现有 `spec.md` 一致）
+
+## 3. 目录与模块规划
+
+### 3.1 顶层目录（目标态）
+
+- `app/`：路由入口（expo-router）
+- `src/`：业务代码
+  - `src/features/`：按功能域拆分（push/widget/cards）
+  - `src/services/`：API 封装
+  - `src/store/`：状态管理
+  - `src/i18n/`：多语言资源与初始化
+  - `src/components/`、`src/hooks/`、`src/utils/`、`src/constants/`、`src/types/`
+- `assets/`：静态资源
+- `app.json` 或 `app.config.ts`：Expo 配置与环境区分入口
+- `eas.json`：EAS 配置（如启用）
+
+### 3.2 关键模块拆分
+
+- **i18n 模块**（`src/i18n/`）
+  - `index.ts`：初始化（默认语言、回退语言、资源注册、与系统语言对齐）
+  - `locales/*.json`：`zh-CN/en/es/pt/zh-TW` 五份资源
+  - （可选）`types.ts`：语言码类型与 key 约束
+- **Push 模块**（`src/features/push/`）
+  - 权限申请
+  - Token 获取与上报（接口对齐点在联调阶段确认）
+- **Widget 模块**（`src/features/widget/`）
+  - 数据读取与缓存策略（先定义接口与缓存层，再落地 iOS 扩展实现）
+- **Cards 模块**（`src/features/cards/`）
+  - 卡片滑动交互组件与数据模型
+
+## 4. 环境区分与配置计划
+
+### 4.1 环境变量与模板
+
+- 提供 `.env.example`（至少包含 `EXPO_PUBLIC_API_BASE_URL`、`EXPO_PUBLIC_ENV`）
+- 本地开发使用 `.env.dev`，生产构建使用 `.env.prod`
+- README 明确：
+  - 真机联调时 `localhost` 替换为局域网 IP
+  - 环境变量不入库
+
+### 4.2 Bundle ID 与构建标识
+
+- dev：`com.damer.mindfulness.dev`
+- prod：`com.damer.mindfulness`
+- 在 `eas.json` 中按 profile 区分环境变量注入与 bundle id（当工程文件落地后执行）
+
+## 5. 多语言（i18n）落地计划
+
+### 5.1 语言码与策略
+
+- 支持：`zh-CN` / `en` / `es` / `pt` / `zh-TW`
+- 默认：优先使用用户当前**设备语言**（在支持列表内时生效）
+- 回退：设备语言不在支持列表时，回退到 `zh-CN`（或团队指定的默认语言）
+
+### 5.2 动态切换与持久化
+
+- 提供“语言设置”入口（后续 UI 落地），允许用户手动切换语言
+- 切换语言后写入本地存储（例如 AsyncStorage）
+- App 启动时语言选择优先级：
+  - ① 用户设置（若存在）
+  - ② 设备语言（在支持列表内）
+  - ③ 默认回退（`zh-CN` 或团队指定默认）
+
+### 5.3 文案规范
+
+- key 点分层：`common.*`、`push.*`、`cards.*`、`widget.*`
+- 插值：`{{name}}` 等形式统一
+- 禁止代码内拼接长句（降低翻译成本）
+
+## 6. 推送与小组件（一期能力）计划
+
+### 6.1 推送
+
+- 客户端：权限 -> token -> 上报
+- 后端：保存 token -> 定时任务 -> 推送内容配置
+- 联调产出：token 上报接口、字段、鉴权、错误码约定（后续任务阶段细化）
+
+### 6.2 小组件
+
+- 先定义“数据模型 + 缓存策略 + 刷新策略”的规范
+- 明确限制：刷新频率受 iOS 系统控制，文档中强调体验目标为“尽力而为”
+
+## 7. 执行步骤（落地顺序）
+
+1. **补齐客户端 README**：确保启动/环境/i18n/目录/EAS 指引完整（已完成基础版本）
+2. **初始化 Expo 工程（如尚未提交）**：生成 `package.json`、`app.json/app.config.*`、`assets/` 等
+3. **建立标准目录结构**：创建 `app/`、`src/` 与各子目录
+4. **接入 i18n 基座**：完成语言码、资源文件、初始化与切换策略
+5. **接入环境变量读取**：确保 dev/prod 可影响 API Base URL
+6. **预留 push/widget/cards 的模块骨架**：先放类型与接口占位，等待业务实现
+7. **EAS 配置与 iOS 构建跑通**：编写 `eas.json` 并验证 development profile 构建链路
+
+## 8. 可替代方案（不影响目标的变体）
+
+- **路由不使用 expo-router**：使用 React Navigation
+  - 目录：`src/navigation/` + `src/screens/`
+  - 仍保留 `src/features/`、`src/services/`、`src/i18n/` 等不变
+- **网络层使用 Fetch**：保持 `src/services/` 统一封装，替换实现即可
+
+## 9. 风险与回滚策略
+
+- **真机联调失败**：优先排查局域网 IP、代理/防火墙、后端端口映射；必要时使用内网穿透
+- **推送配置复杂**：先在 dev profile 跑通 token->推送最小闭环，再扩展定时策略
+- **小组件刷新不稳定**：在 UI/产品层面接受系统限制，并通过缓存提升体验
+