Files

吕新雨 049995692d init

2026-01-28 20:50:17 +08:00

6.4 KiB

Raw Blame History

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+ 为前提）：

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

6.4 KiB Raw Blame History Unescape Escape