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