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