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/产品层面接受系统限制，并通过缓存提升体验
+

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

spec_kit/Client Bootstrap/tasks.md

@@ -0,0 +1,130 @@
+# Client Bootstrap（任务清单）
+
+> 说明：本清单根据 `plan.md` 拆解，要求“可执行、可验收、可标记”。  
+> 标记规则：执行完成后将对应项从 `- [ ]` 改为 `- [x]`，并把“状态”改为 **已完成**；进行中改为 **进行中**；阻塞写明原因与解除条件。
+
+## 0. 清单状态说明
+
+- **状态**：未开始 / 进行中 / 已完成 / 阻塞
+- **阻塞**：必须写明阻塞点（例如“缺少 Expo 工程代码”）与下一步需要谁提供什么
+
+## 1. 文档完善（README 为准入门）
+
+- [x] **更新 `client/README.md` 的包管理器命令统一为 pnpm**  
+  - **状态**：已完成  
+  - **内容**：将 `npm install`、`npm run *` 改为 `pnpm install`、`pnpm *`（或在 README 中明确“团队统一 pnpm”且给出 pnpm 命令为主）  
+  - **验收**：README 中安装/启动/平台命令不混用 npm/pnpm
+
+- [x] **补充 i18n “设置页切换语言”的落地说明**  
+  - **状态**：已完成  
+  - **内容**：在多语言章节增加“语言优先级：用户设置 > 设备语言 > 默认回退（zh-CN）”与“设置入口建议位置”  
+  - **验收**：README 的 i18n 规则与 `spec.md/plan.md` 完全一致
+
+## 2. 初始化 Expo 工程（若仓库尚未提交客户端代码）
+
+> 若 `client/` 下已经存在 Expo 工程（`package.json`、`app.json/app.config.*`），跳过本章节并在任务上标记“已完成（已存在）”。
+
+- [x] **在 `client/` 初始化 Expo + TypeScript 工程**  
+  - **状态**：已完成  
+  - **命令**：
+    - `cd client`
+    - `npx create-expo-app@latest .`（按提示选择 TypeScript 模板）
+  - **产出**：生成 `package.json`、`app.json/app.config.*`、`assets/`、入口代码等  
+  - **验收**：`client/` 下存在可运行的 Expo 工程基础文件
+
+- [x] **切换为 pnpm 并安装依赖**  
+  - **状态**：已完成  
+  - **命令**：
+    - `cd client`
+    - `pnpm install`
+  - **验收**：依赖安装成功，可执行 `pnpm start`
+
+## 3. 建立标准目录结构（目标态）
+
+- [x] **创建标准目录骨架（`app/` + `src/` + `assets/`）**  
+  - **状态**：已完成  
+  - **目录**：
+    - `app/`（expo-router 路由目录，若采用）
+    - `src/components/`
+    - `src/constants/`
+    - `src/features/push/`
+    - `src/features/widget/`
+    - `src/features/cards/`
+    - `src/hooks/`
+    - `src/i18n/locales/`
+    - `src/services/`
+    - `src/store/`
+    - `src/types/`
+    - `src/utils/`
+  - **验收**：目录与 `client/README.md` 中的“标准目录结构”一致
+
+## 4. 接入 i18n 基座（CN/EN/ES/PT/TC）
+
+- [x] **引入 i18n 依赖并记录版本**  
+  - **状态**：已完成（i18next@25.8.0 / react-i18next@16.5.4 / expo-localization@17.0.8 / AsyncStorage@2.2.0）  
+  - **依赖**：`i18next`、`react-i18next`、`expo-localization`（如需持久化再加 `@react-native-async-storage/async-storage`）  
+  - **验收**：`package.json` 中依赖齐全，且能正常打包/运行
+
+- [x] **创建语言资源文件（5 份）**  
+  - **状态**：已完成  
+  - **文件**：
+    - `src/i18n/locales/zh-CN.json`
+    - `src/i18n/locales/en.json`
+    - `src/i18n/locales/es.json`
+    - `src/i18n/locales/pt.json`
+    - `src/i18n/locales/zh-TW.json`
+  - **内容要求**：至少包含 `common.ok/common.cancel` 等最小 key 集合（五种语言都要齐全）  
+  - **验收**：同一 key 在 5 个文件都存在，不允许缺 key
+
+- [x] **实现 `src/i18n/index.ts` 初始化与语言优先级**  
+  - **状态**：已完成  
+  - **规则**：
+    - ① 用户设置语言（存在则优先）
+    - ② 设备语言（在支持列表内）
+    - ③ 默认回退（`zh-CN` 或团队指定默认）
+  - **验收**：能在运行时切换语言并立即生效；重启后仍保持用户选择
+
+- [x] **提供语言设置的状态存储与 API（供设置页调用）**  
+  - **状态**：已完成（已提供 `getLanguagePreference/setLanguagePreference/changeLanguage/clearLanguagePreference`）  
+  - **建议**：`src/store/` 或 `src/features/settings/`（如后续新增）暴露 `setLanguage/getLanguage`  
+  - **验收**：设置页接入时只需调用一个清晰接口即可完成切换
+
+## 5. 环境变量与联调基座
+
+- [x] **补齐 `.env.example` 并规范 `.env.dev/.env.prod`**  
+  - **状态**：已完成（已创建 `.env.example`；注意该文件在当前环境会被 globalignore 过滤，终端可见但编辑工具不可见）  
+  - **字段**：`EXPO_PUBLIC_API_BASE_URL`、`EXPO_PUBLIC_ENV`  
+  - **验收**：文档与实际读取方式一致；真机联调注意事项明确
+
+- [ ] **实现 API 客户端封装（`src/services/`）**  
+  - **状态**：未开始  
+  - **要求**：从 `EXPO_PUBLIC_API_BASE_URL` 读取 baseURL；统一错误处理与超时策略（先给默认）  
+  - **验收**：任意页面可通过统一 client 发起请求，且环境切换能影响 baseURL
+
+## 6. 模块骨架（push/widget/cards）
+
+- [ ] **Push 模块：权限/Token/上报接口占位**  
+  - **状态**：未开始  
+  - **要求**：提供最小 API（例如 `requestPermission() / getToken() / reportToken()`）  
+  - **验收**：模块对外 API 清晰，后续联调只需补实现不需改结构
+
+- [ ] **Widget 模块：数据模型/缓存/刷新策略文档化与占位**  
+  - **状态**：未开始  
+  - **要求**：定义“情绪文案数据结构”、缓存 key、刷新建议（强调 iOS 限制）  
+  - **验收**：能明确后续 iOS 小组件实现需要的数据与刷新行为
+
+- [ ] **Cards 模块：数据模型与卡片滑动组件占位**  
+  - **状态**：未开始  
+  - **验收**：后续 UI 实现可以直接在该模块内扩展，不破坏目录约定
+
+## 7. EAS Build（iOS 打包链路）
+
+- [ ] **创建并配置 `eas.json`（development profile）**  
+  - **状态**：未开始  
+  - **要求**：区分 dev/prod；注入对应环境变量；bundle id 符合约定  
+  - **验收**：可触发 iOS development 构建并产出安装包/构建产物
+
+- [ ] **验证 iOS 构建最小闭环**  
+  - **状态**：未开始  
+  - **验收**：构建成功；App 能启动；基础 i18n 与环境变量读取无崩溃
+