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 与环境变量读取无崩溃
+

spec_kit/Onboarding App Shell/spec.md

@@ -0,0 +1,132 @@
+# Onboarding App Shell（高层规范）
+
+## 1. 背景与目标
+
+本需求用于落地客户端的“首次进入体验 + 主应用壳 + 关键入口”，包含：
+
+- 3–5 页可跳过的 Onboarding（问题页均可跳过）
+- Push 设置页（可跳过）
+- 进入主 App：支持“点赞/讨厌”交互
+- 收藏夹入口
+- 通用设置入口：版本信息、iOS 小组件入口
+
+### 目标
+
+- **首次体验顺畅**：用户可完成或跳过 Onboarding 与 Push 设置，不阻塞进入主功能
+- **主功能可用**：进入主 App 后可对内容进行“点赞/讨厌”，并能进入收藏夹与设置
+- **入口清晰**：收藏夹与设置入口明显且可从主界面到达
+- **状态可持久化**：Onboarding 完成状态、Push 设置选择（是否跳过）、点赞/讨厌记录、收藏记录可持久化
+
+### 非目标（本阶段不做）
+
+- 不实现完整推送业务闭环（仅做“设置入口/引导”，且可跳过）
+- 不实现真实推荐算法（内容来源可先用本地 mock 或固定列表）
+- iOS 小组件不要求完整上线交互（先做“入口/说明/引导”即可，实际小组件实现可拆分到后续模块）
+
+## 2. 用户流程（高层）
+
+### 2.1 首次启动
+
+1. App 启动
+2. Onboarding（3–5 页）
+   - 每页都提供 **跳过**（Skip）
+   - 支持上一页/下一页（可选）
+3. Push 设置页（可选进入，且可跳过）
+4. 进入主 App（内容卡片/列表）并可点赞/讨厌
+
+### 2.2 非首次启动
+
+- 若已完成（或跳过）Onboarding：直接进入主 App
+
+## 3. 功能需求（高层）
+
+### 3.1 Onboarding（3–5 页，问题可跳过）
+
+- **页数**：3–5 页（可配置）
+- **内容**：以“问题/偏好收集”为主（具体题目可后续在内容配置中迭代）
+- **跳过策略**：
+  - 每页可跳过（不强制填写）
+  - 最终可一键跳过整个 Onboarding
+- **视觉反馈**：
+  - 进度指示（例如 1/5 或进度条）
+  - 清晰的“下一步/跳过”按钮
+
+### 3.2 Push 设置（可跳过）
+
+- 提供一页“开启通知”的引导与说明
+- 支持：
+  - **立即开启**（触发权限申请）
+  - **稍后**（跳过）
+- 用户选择需持久化（用于后续在设置页再次引导）
+
+### 3.3 主 App：点赞/讨厌
+
+- 主界面展示一条“情绪文字/正念短句/卡片内容”
+- 支持两种操作：
+  - **点赞（Like）**
+  - **讨厌（Dislike）**
+- 行为结果：
+  - 记录用户操作（本地持久化）
+  - 点赞内容可进入收藏夹（或点赞即收藏，具体规则在实现时确认）
+
+### 3.4 收藏夹入口
+
+- 主界面提供“收藏夹”入口
+- 收藏夹展示已收藏内容列表
+- 支持取消收藏（可选）
+
+### 3.5 通用设置入口
+
+设置页至少包含：
+
+- **版本信息**：展示 App 版本号（和可选的 build number）
+- **iOS 小组件**：入口/说明
+  - 提供“如何添加小组件”的引导文案
+  - 若后续实现小组件配置页，可从此入口进入
+- **通知设置**（可选，但建议有）：
+  - 展示当前通知状态
+  - 允许用户再次进入系统设置开启通知（iOS/Android 跳转能力按平台支持情况实现）
+
+## 4. 数据与持久化（高层）
+
+需要持久化的最小集合：
+
+- `onboarding.completed`: boolean
+- `push.promptState`: `enabled | skipped | unknown`
+- `content.reactions`: 记录内容 ID 与 like/dislike
+- `favorites.items`: 收藏内容列表（按 ID 存储）
+
+> 说明：本期可采用本地存储（例如 AsyncStorage）；后续可扩展为与后端同步。
+
+## 5. 页面与导航（建议）
+
+- `Onboarding`（多页）
+- `PushPrompt`（可跳过）
+- `Home`（点赞/讨厌）
+- `Favorites`（收藏夹）
+- `Settings`（通用设置：版本、iOS 小组件）
+
+若使用 `expo-router`：
+
+- Onboarding 可用分组路由（例如 `(onboarding)`）管理，并在完成后跳转到 `(tabs)` 或 `Home`
+
+## 6. 验收标准
+
+- 首次进入：
+  - 可完成或跳过 Onboarding（任意页可跳过）
+  - Push 设置页可跳过
+  - 最终一定能进入主 App
+- 主功能：
+  - 主界面可对内容执行点赞/讨厌并记录
+  - 存在收藏夹入口且可看到收藏内容
+  - 存在设置入口且能看到版本与 iOS 小组件入口/说明
+- 持久化：
+  - 重启 App 后，Onboarding 不会重复出现（除非主动清除状态）
+  - 点赞/收藏记录仍存在
+
+## 7. 风险与注意事项
+
+- 通知权限申请时机：过早弹窗可能导致拒绝率上升，建议通过引导页解释后再触发
+- iOS 小组件能力受系统限制：刷新频率与内容更新不保证严格实时
+- 内容来源：若暂未接后端，需提供可替换的 mock 内容与唯一 ID 方案
+

spec_kit/Project Bootstrap/plan.md

@@ -0,0 +1,152 @@
+# Project Bootstrap（技术计划）
+
+## 1. 目标与约束（来自 spec）
+
+- 目标：完成项目初始化可落地的工程与基础设施约定（client/server + dev/prod 隔离 + MySQL/Redis 命名与访问边界）。
+- 关键选择：
+  - 后端依赖：`requirements.txt` + `pip`
+  - 定时/异步：Celery + Redis
+  - 环境：仅 dev / prod
+  - Redis 隔离：ACL + key 前缀（`dev:*` / `pro:*`）
+  - 部署：**不在本需求中提供 Docker 起 MySQL/Redis**（MySQL/Redis 已部署），后端通过环境变量连接
+  - 数据库迁移：Alembic
+  - Redis 生产环境：**maxmemory=256MB 硬限制**
+
+## 2. 总体方案
+
+### 2.1 MySQL（schema 隔离）
+
+- prod schema：`mindfulness`
+- dev schema：`mindfulness_dev`
+- 字符集：`utf8mb4`
+- 连接方式：后端通过 `DATABASE_URL`（SQLAlchemy Async）连接到对应 schema
+
+### 2.2 Redis（ACL + 前缀隔离 + 内存限制）
+
+- 单 Redis 实例（同机同容器可行）。
+- 通过 **ACL 用户**限制不同环境只能访问各自前缀：
+  - dev 用户：只能访问 `dev:*`
+  - prod 用户：只能访问 `pro:*`
+- 应用侧硬约束：所有 Redis key 必须带环境前缀（`dev:` / `pro:`）。
+- 生产 maxmemory：`256mb`，并采用“少用 Redis、短 TTL、避免任务积压”的策略。
+
+> 重要：Celery broker 以“可靠投递”为优先，计划中默认 **不启用** Celery result backend（或启用时必须设置 TTL）。
+
+### 2.3 运行方式（不限定部署形态）
+
+本需求只要求：
+
+- MySQL 与 Redis **已可访问**
+- 后端通过 `.env.dev/.env.prod`（或等价环境变量注入方式）获取连接信息
+- API/Celery/Beat 以任意进程管理方式运行（Docker/systemd/进程托管均可），但需满足验收项
+
+## 3. 目录与文件落地清单
+
+> 本计划只定义“应该创建/调整什么”，具体文件内容在 tasks 阶段逐项实现。
+
+### 3.1 后端依赖与启动入口（server）
+
+- `server/requirements.txt`
+- `server/app/main.py`（FastAPI 入口）
+- `server/app/core/config.py`（pydantic-settings，按 `APP_ENV` 加载 `.env.dev/.env.prod`）
+- `server/app/worker.py`（Celery app 入口）
+- `server/alembic.ini` + `server/alembic/`（迁移脚手架）
+- `server/.env.example`（字段结构，不含真实值）
+
+### 3.2 基础设施（infra）
+
+本需求不强制创建 `infra/`（因为 MySQL/Redis 已部署）。
+
+可选新增（仅用于“文档化配置/备份参考”，不要求参与部署）：
+
+- `infra/redis/users.acl`（ACL 用户定义备份）
+- `infra/redis/redis.prod.conf`（prod 配置备份，包含 maxmemory=256mb）
+- `infra/mysql/init/00-create-schemas.sql`（创建 `mindfulness_dev/mindfulness` 的 SQL 备份）
+
+## 4. Redis ACL 与 maxmemory 的落地方案
+
+### 4.1 ACL 文件（`infra/redis/users.acl`）
+
+> 若 Redis 已在服务器配置完成，本节用于“约定与验收”。
+
+- 定义 `dev_user`、`pro_user` 两个账号
+- 分别限制 key pattern：
+  - dev：`~dev:*`
+  - prod：`~pro:*`
+- 建议禁用默认用户，避免未授权访问（推荐）：`user default off`
+
+### 4.2 Redis 配置（`infra/redis/redis.prod.conf`）
+
+> 若 Redis 已在服务器配置完成，本节用于“约定与验收”。
+
+- `maxmemory 256mb`
+- `maxmemory-policy noeviction`（队列场景优先“不丢任务”，宁可让写入失败报警）
+- 开启 ACL（例如 `aclfile .../users.acl`）
+
+### 4.3 应用侧约束（在代码实现时落地）
+
+为确保 ACL 真的起作用，需要做到：
+
+- **所有业务 key 带前缀**：例如 `dev:cache:...` / `pro:cache:...`
+- **Celery 队列名带前缀**：例如 `dev:push` / `pro:push`
+- **禁用或限制 result backend**：默认不启用；如启用必须设置短 TTL（例如 1 小时/1 天）
+- **任务参数保持小**：只传 id，不传长文本/大 payload，避免队列膨胀导致 Redis 触顶
+
+## 5. 环境变量与配置约定
+
+### 5.1 后端 `.env.dev/.env.prod`（字段示例）
+
+- `APP_ENV=dev|prod`
+- `DATABASE_URL=.../mindfulness_dev`（dev）或 `.../mindfulness`（prod）
+- `REDIS_URL=redis://<user>:<pass>@redis:6379/0`
+- `CELERY_BROKER_URL=redis://<user>:<pass>@redis:6379/0`
+- `CELERY_RESULT_BACKEND`：默认不配置（或仅在 dev 开启）
+
+### 5.2 密钥管理
+
+- `.env.dev/.env.prod` 不进仓库
+- 提供 `.env.example` 仅展示字段结构
+
+## 6. 实施步骤（建议顺序）
+
+### 阶段 A：验证现有 MySQL/Redis 与隔离策略
+
+- Redis：ACL 生效验证（dev 用户无法访问 `pro:*`，prod 用户无法访问 `dev:*`）
+- Redis：prod 配置验证（`maxmemory=256mb` 生效）
+- MySQL：确认 `mindfulness_dev` 与 `mindfulness` 两个 schema 已创建（若未创建则创建）
+
+### 阶段 B：后端最小可运行骨架
+
+- `requirements.txt` 固化依赖
+- FastAPI 最小健康检查接口（如 `/healthz`）
+- SQLAlchemy 连接与基础会话
+- Alembic 初始化与一次空迁移验证
+
+### 阶段 C：Celery 最小闭环
+
+- Celery app 初始化，broker 指向 Redis（按环境选择 dev_user/pro_user）
+- 1 个示例任务（例如打印/写库）验证 worker 可消费
+- 如需要定时：beat 定时触发任务验证
+
+## 7. 验收与自检清单（plan 阶段定义）
+
+- **环境隔离**
+  - dev 连接 `mindfulness_dev`，prod 连接 `mindfulness`
+  - dev 的 Redis 凭证无法读写 `pro:*`，反之亦然
+- **资源约束**
+  - prod Redis `maxmemory=256mb` 生效
+  - 不启用（或短 TTL）result backend，避免长期堆积
+- **可运行性**
+  - FastAPI 能启动并提供基础接口
+  - Celery worker 能消费任务，beat（如启用）能触发定时任务
+
+## 8. 风险与应对
+
+- Redis 256MB 触顶风险：
+  - 控制队列积压（worker 数量/并发）
+  - 禁用或缩短结果存储 TTL
+  - 任务 payload 只传 id
+- 多环境同机误用风险：
+  - 强制不同 ACL 用户 + 前缀
+  - Celery 队列名带前缀，避免互相消费
+

spec_kit/Project Bootstrap/spec.md

@@ -0,0 +1,155 @@
+# Project Bootstrap（高层规范）
+
+## 1. 背景与目标
+
+本需求用于完成「正念 APP」项目的**仓库初始化与工程约定落地**，覆盖客户端（React Native + Expo）与后端（FastAPI）的基础目录结构、文档、环境区分与基础设施依赖（MySQL / Redis）隔离策略，为一期功能（推送、小组件、情绪卡片）后续迭代提供稳定底座。
+
+### 目标
+
+- **仓库结构清晰**：`client/`、`server/`、`infra/`、`scripts/`、`.gitea/` 等职责明确
+- **环境可区分（dev / prod）**：客户端与后端均支持 dev/prod 两套配置，不混用资源
+- **数据库命名可持续**：MySQL schema 命名统一、可扩展、可一键区分环境
+- **Redis 隔离可控**：通过 Redis ACL + key 前缀隔离 dev/pro 数据访问，满足同机部署需求
+- **文档可执行**：新人按 README 可完成本地启动、配置、联调（允许依赖尚未完全落地时使用占位说明）
+
+### 非目标（本阶段不做）
+
+- 不在本阶段实现完整业务接口与表结构（仅定义约定与边界）
+- 不在本阶段实现推送业务全链路（仅确定任务调度与资源隔离策略）
+- 不在本阶段完成生产级监控/告警/灰度（后续需求承接）
+
+## 2. 范围与交付物
+
+### 范围
+
+- 仓库根目录结构与职责约定
+- 客户端/后端 README 规范化（可运行步骤、配置说明、常见问题）
+- dev/prod 环境区分策略（配置文件命名、变量命名、密钥管理）
+- MySQL schema 命名约定
+- Redis ACL 与 key 前缀隔离约定
+
+### 交付物
+
+- **根 README**：项目概览、目录结构、一期功能说明、技术栈与环境区分说明
+- **`client/README.md`**：客户端启动/调试/环境切换/打包规范
+- **`server/README.md`**：后端启动/配置/迁移/任务调度（Celery）说明
+- **基础设施约定**（文档层面）：
+  - MySQL：schema 命名与字符集约定
+  - Redis：ACL 用户与 key 前缀隔离方案（dev/pro）
+
+## 3. 用户与核心使用场景
+
+- **开发者（单人或小团队）**
+  - 能快速在本地启动 client/server 并联调
+  - 能明确 dev/prod 使用的数据库与 Redis 资源不互相污染
+- **运维/部署执行者**
+  - 能根据文档完成最小化部署（即使暂不容器化，也应明确运行依赖）
+
+## 4. 功能需求（高层）
+
+### 4.1 仓库结构与职责边界
+
+- `client/`：React Native + Expo 客户端工程
+- `server/`：FastAPI 后端工程
+- `infra/`：Docker / k8s / nginx 等基础设施（可后置，但需预留）
+- `scripts/`：构建/部署脚本（可后置，但需预留）
+- `.gitea/`：CI/CD 工作流（可后置，但需预留）
+
+### 4.2 环境区分（dev / prod）
+
+- **客户端**：使用 `.env.dev` / `.env.prod`，不提交真实 `.env`，提供 `.env.example`
+- **后端**：使用 `.env.dev` / `.env.prod`，不提交真实 `.env`，提供 `.env.example`
+- **资源隔离原则**：
+  - dev/pro 必须使用**不同的 MySQL schema**
+  - dev/pro 必须使用**不同的 Redis 访问权限（ACL）与 key 前缀**
+
+### 4.3 MySQL 命名约定（schema / 表 / 字段）
+
+- **schema（数据库名）**：
+  - prod：`mindfulness`
+  - dev：`mindfulness_dev`
+- **字符集**：统一 `utf8mb4`
+- **命名风格**：统一小写 + 下划线（snake_case）
+- **约束命名**（建议，便于迁移与排障）：
+  - 唯一索引：`uq_<table>_<column>`
+  - 普通索引：`ix_<table>_<column>`
+  - 外键：`fk_<fromtable>_<column>__<totable>`
+
+### 4.4 Redis 使用范围与隔离约定
+
+#### 4.4.1 使用范围
+
+- Redis 主要用于：
+  - Celery broker（任务队列）
+  - （可选）短 TTL 缓存
+- 约束：
+  - **不允许**把大对象（长文本/图片/base64）直接写入 Redis
+  - 若启用 Celery 结果存储（result backend），必须设置 TTL，避免无限增长
+  - 若生产环境有资源限制（例如 `maxmemory=256MB`），需在文档中明确并按“少用、短 TTL、避免积压”的策略执行
+
+#### 4.4.2 dev/pro ACL + key 前缀隔离
+
+Redis 单实例同机部署时，采用 ACL 限制不同环境只能访问自己的 key 前缀：
+
+- dev：只能访问 `dev:*`
+- prod：只能访问 `pro:*`
+
+ACL 规则示例（以 Redis 6+ 为前提）：
+
+```text
+# Dev 用户，只能访问 dev:* 前缀
+user dev_user on >devpassword ~dev:* +@all
+
+# Pro 用户，只能访问 pro:* 前缀
+user pro_user on >propassword ~pro:* +@all
+```
+
+应用侧约定：
+
+- 所有 Redis key 必须以环境前缀开头（dev 用 `dev:`，prod 用 `pro:`）
+- Celery 队列名/键名建议也带环境前缀，避免同机多环境互相影响
+
+## 5. 技术与工程规范（高层）
+
+### 5.1 文档规范
+
+- README 必须包含：
+  - 环境准备（版本要求）
+  - 安装依赖与启动命令
+  - dev/prod 配置与 `.env.example` 说明
+  - 数据库/缓存/队列依赖说明
+  - 常见问题与排障建议
+
+### 5.2 密钥与敏感信息管理
+
+- 禁止将真实 IP/账号/密码/Token 写入仓库文档与代码
+- 所有敏感信息通过 `.env.dev/.env.prod` 注入
+- 仓库仅提供 `.env.example` 展示字段结构
+
+### 5.3 后端 Python 版本与依赖安装方式
+
+- **Python 版本基线**：建议 **Python 3.11+**（与 FastAPI / SQLAlchemy 2.x 异步生态兼容性更好）
+- **依赖管理方式（二选一，团队需统一）**：
+  - **方案 A：`requirements.txt` + `pip`**
+    - 安装：`pip install -r requirements.txt`
+    - 适用：简单直接，适合快速启动与小团队
+
+
+> 约定：后端 README 需要明确项目采用的方案 A 或方案 B，并给出可复制执行的安装与启动命令。
+
+## 6. 验收标准
+
+- 仓库层面：
+  - 目录结构与根 README 清晰，能让新成员理解项目模块划分
+- 环境隔离层面：
+  - 明确 dev/pro MySQL schema 分别为 `mindfulness_dev` 与 `mindfulness`
+  - 明确 Redis 使用 ACL 限制 dev/pro 前缀访问，并写清 key 前缀约定
+- 文档可执行层面：
+  - `client/README.md` 与 `server/README.md` 至少能指导完成“本地启动 + 配置注入”的完整流程（若代码未落地，需明确占位与替换点）
+
+## 7. 风险与注意事项
+
+- Redis 若设置较小 `maxmemory`，在任务积压或无 TTL 的缓存策略下可能触发内存压力，需要通过限流、缩短 TTL、提高消费能力解决
+- dev/pro 同机部署时，除 ACL 外还需避免队列名、key 名混用；建议在配置中显式标注环境前缀
+- 推送依赖外部网络（Expo），需在任务侧加入超时与重试策略，避免偶发失败导致体验不稳定
+

spec_kit/Project Bootstrap/tasks.md

@@ -0,0 +1,125 @@
+# Project Bootstrap（任务清单）
+
+> 说明：本清单用于把 `plan.md` 拆成“可逐条执行”的任务。执行完成后请把对应项从 `[ ]` 勾选为 `[x]`。
+
+## 0. 约定与前置
+
+- [ ] **确认后端依赖管理方式**：使用 `requirements.txt + pip`
+- [ ] **确认环境**：仅 dev / prod
+- [ ] **确认 Redis 方案**：单实例 + ACL（`dev:*`/`pro:*`）+ prod `maxmemory=256mb`（硬限制）
+- [ ] **确认迁移工具**：Alembic
+- [ ] **确认部署方式**：MySQL/Redis 已部署，后端通过环境变量连接（不做 Docker 起 MySQL/Redis）
+
+## A. 现有 MySQL/Redis 验证与环境隔离确认
+
+### A1. MySQL（schema）确认
+
+- [ ] 确认 dev schema：`mindfulness_dev` 已存在（字符集 `utf8mb4`）
+- [ ] 确认 prod schema：`mindfulness` 已存在（字符集 `utf8mb4`）
+
+### A2. Redis（ACL + maxmemory=256MB）确认
+
+- [ ] 确认 Redis 已启用 ACL，并存在账号：
+  - [ ] `dev_user` 仅允许访问 `~dev:*`
+  - [ ] `pro_user` 仅允许访问 `~pro:*`
+- [ ] 确认生产环境 Redis 内存限制：
+  - [ ] `maxmemory=256mb` 生效
+  - [ ] `maxmemory-policy=noeviction` 生效（队列优先，不丢任务）
+
+### A3. Redis ACL 验收（必须可复现）
+
+- [ ] 使用 `dev_user` 写入 `dev:test=1` 成功
+- [ ] 使用 `dev_user` 写入 `pro:test=1` 失败（权限不足）
+- [ ] 使用 `pro_user` 写入 `pro:test=1` 成功
+- [ ] 使用 `pro_user` 写入 `dev:test=1` 失败（权限不足）
+
+### A4. 可选：把现有配置“备份到仓库”（不参与部署）
+
+- [ ] （可选）新建 `infra/redis/users.acl`（把线上 ACL 规则复制备份，注意去掉真实密码）
+- [ ] （可选）新建 `infra/redis/redis.prod.conf`（把线上关键参数备份：maxmemory/noeviction/aclfile 等）
+- [ ] （可选）新建 `infra/mysql/init/00-create-schemas.sql`（备份 schema 创建脚本）
+
+## B. 后端工程骨架（server/）落地
+
+> 当前 `server/` 目录可能尚未创建代码文件，本阶段目标是“能启动、能连库、能跑迁移、能跑 Celery”。
+
+### B1. 依赖与环境变量模板
+
+- [ ] 新增 `server/requirements.txt`
+  - [ ] FastAPI、uvicorn
+  - [ ] SQLAlchemy 2.x（异步）+ MySQL driver（如 `aiomysql`）
+  - [ ] pydantic-settings（pydantic v2）
+  - [ ] alembic
+  - [ ] celery、redis（Python 客户端）
+  - [ ] pytest
+- [ ] 新增 `server/.env.example`（仅字段结构，不含真实值）
+  - [ ] `APP_ENV=dev|prod`
+  - [ ] `DATABASE_URL=.../mindfulness_dev`（dev）或 `.../mindfulness`（prod）
+  - [ ] `REDIS_URL=redis://<user>:<pass>@<REDIS_HOST>:6379/0`
+  - [ ] `CELERY_BROKER_URL=redis://<user>:<pass>@<REDIS_HOST>:6379/0`
+  - [ ] （默认不写）`CELERY_RESULT_BACKEND`
+
+### B2. FastAPI 最小入口
+
+- [ ] 新增 `server/app/main.py`
+  - [ ] 创建 FastAPI 实例 `app`
+  - [ ] 增加健康检查接口 `/healthz`
+- [ ] 新增 `server/app/core/config.py`
+  - [ ] 使用 `pydantic-settings`
+  - [ ] 根据 `APP_ENV` 加载 `.env.dev` / `.env.prod`
+
+### B3. SQLAlchemy 与数据库连接
+
+- [ ] 新增 `server/app/db/`（目录）
+- [ ] 新增 `server/app/db/session.py`
+  - [ ] 从 `DATABASE_URL` 创建 async engine
+  - [ ] 提供 session 工厂
+
+### B4. Alembic 初始化
+
+- [ ] 初始化 Alembic：
+  - [ ] 生成 `server/alembic.ini`
+  - [ ] 生成 `server/alembic/`（env.py / versions/）
+  - [ ] 配置从环境变量读取数据库连接
+- [ ] 验收：
+  - [ ] 能执行 `alembic revision -m "init"`（即使空迁移也可）
+  - [ ] 能执行 `alembic upgrade head`
+
+## C. Celery 最小闭环（Redis broker + 队列前缀）
+
+### C1. Celery 入口与任务示例
+
+- [ ] 新增 `server/app/worker.py`
+  - [ ] Celery 初始化使用 `CELERY_BROKER_URL`
+  - [ ] 默认 **不启用** result backend（或仅 dev 可选）
+  - [ ] 配置默认队列名带环境前缀（例如 `dev:push` / `pro:push`）
+- [ ] 新增 1 个示例任务（例如 `server/app/tasks/ping.py`）
+  - [ ] 任务只传小参数（如字符串/ID）
+
+### C2. Worker/Beat 启动与验收
+
+- [ ] Worker 验收：
+  - [ ] `celery -A app.worker:celery_app worker -l info` 可启动
+  - [ ] 发送任务后能被消费
+- [ ] Beat（如需要定时）：
+  - [ ] `celery -A app.worker:celery_app beat -l info` 可启动
+  - [ ] 能按周期触发示例任务
+
+## D. 文档与验收补全
+
+### D1. 更新 README 与约定一致
+
+- [ ] 更新 `server/README.md`
+  - [ ] 明确：`requirements.txt + pip` 作为依赖安装方式
+  - [ ] 明确：dev/pro MySQL schema（`mindfulness_dev`/`mindfulness`）
+  - [ ] 明确：Redis ACL + key 前缀、prod `maxmemory=256mb` 硬限制
+  - [ ] 明确：Celery 默认不启用 result backend（或启用需 TTL）
+- [ ] （可选）更新根 `README.md`
+  - [ ] 追加：基础设施依赖与 dev/pro 隔离约定摘要
+
+### D2. 最终验收清单（完成后统一勾选）
+
+- [ ] **环境隔离**：dev/pro MySQL schema 与 Redis ACL 均生效
+- [ ] **资源约束**：prod Redis `maxmemory=256mb` 生效
+- [ ] **可运行性**：FastAPI/Celery 可启动并完成最小任务闭环（依赖通过环境变量连接现有 MySQL/Redis）
+

spec_kit/overview.md

@@ -0,0 +1,38 @@
+# Spec Kit Overview
+
+本文件用于简短记录当前项目每个 spec 的核心内容摘要，便于快速总览与追踪变更。
+
+## Client Bootstrap
+
+- **目标**：初始化正念 APP 客户端工程规范，确保可运行、可切环境、可多语言扩展、目录标准化、可 EAS 打包
+- **核心范围**：客户端工程骨架与文档（`client/README.md`）、环境变量约定、i18n（CN/EN/ES/PT/TC）、推送/小组件/卡片滑动的一期能力约束
+- **主要约定**：
+  - 环境：`.env.dev` / `.env.prod`，推荐 `EXPO_PUBLIC_` 前缀
+  - 语言码：`zh-CN/en/es/pt/zh-TW`
+  - 目录：`app/`（可选 expo-router）+ `src/`（features/services/store/utils 等）+ `assets/`
+  - 打包：EAS Build，dev/prod bundle id 约定
+- **阶段产物**：
+  - `spec_kit/Client Bootstrap/spec.md`
+  - `spec_kit/Client Bootstrap/plan.md`
+  - `spec_kit/Client Bootstrap/tasks.md`
+- **已完成编码（阶段性）**：
+  - Expo 工程已在 `client/` 初始化，并完成 `pnpm install`
+  - i18n 基座已接入：5 份语言资源 + 设备语言优先/设置可切换/持久化 + 入口初始化
+
+## Project Bootstrap
+
+- **目标**：完成项目仓库初始化与工程约定落地，明确 client/server 结构、dev/pro 环境隔离、MySQL/Redis 资源命名与访问边界
+- **核心范围**：根目录结构与文档、dev/pro 配置策略、MySQL schema 命名（`mindfulness_dev`/`mindfulness`）、Redis ACL + key 前缀隔离（`dev:*`/`pro:*`）
+- **主要约定**：
+  - MySQL：prod=`mindfulness`，dev=`mindfulness_dev`，统一 `utf8mb4` 与 snake_case
+  - Redis：单实例，通过 ACL 限制不同用户只能访问对应前缀；应用侧强制 key 使用 `dev:`/`pro:` 前缀
+  - 安全：真实 IP/账号/密码/Token 不写入仓库，仅提供 `.env.example` 结构
+- **阶段产物**：
+  - `spec_kit/Project Bootstrap/spec.md`
+
+## Onboarding App Shell
+
+- **目标**：落地首次进入体验（Onboarding 3–5 页可跳过 + Push 设置可跳过）与主应用壳（点赞/讨厌、收藏夹入口、通用设置入口）
+- **核心范围**：Onboarding 多页流程、Push 引导页、主界面反应操作（Like/Dislike）、收藏夹、设置页（版本、iOS 小组件入口/说明）
+- **阶段产物**：
+  - `spec_kit/Onboarding App Shell/spec.md`