init

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），需在任务侧加入超时与重试策略，避免偶发失败导致体验不稳定
+