261 lines
7.3 KiB
Markdown
261 lines
7.3 KiB
Markdown
> For AI assistants: Read this entire file before writing any code. All decisions here are final.
|
||
|
||
# 本地开发手册 (Local Development Manual)
|
||
|
||
本手册为 Fonrey 项目本地环境搭建与开发验证的权威指南。旨在帮助新入场开发人员或 AI agent 快速启动项目并确保开发环境与生产环境的技术决策一致。
|
||
|
||
## §0 文档定位 + 变更历史表
|
||
|
||
| 日期 | 变更人 | 变更内容 | 版本 |
|
||
|---|---|---|---|
|
||
| 2026-06-04 | Sisyphus-Junior | 初始化本地开发手册，整合 ADR 与技术总纲决策 | v1.0 |
|
||
|
||
---
|
||
|
||
## §1 前置依赖
|
||
|
||
运行 Fonrey 前，请确保本地环境已安装以下基础组件：
|
||
|
||
- **操作系统**: 推荐 Linux (Ubuntu 22.04+) 或 macOS。Windows 用户建议使用 WSL2。
|
||
- **Python**: 3.12+
|
||
- **Node.js**: 20.x+ (用于 Tailwind CSS 编译)
|
||
- **Docker & Docker Compose**: 必须，用于运行数据库、缓存与消息队列。
|
||
- **PostgreSQL**: 16.x (通过 Docker 运行)
|
||
- **Redis**: 7.x (通过 Docker 运行)
|
||
- **浏览器**: 最新版 Google Chrome 或 Chromium (用于 Playwright E2E 测试)
|
||
|
||
---
|
||
|
||
## §2 仓库初始化
|
||
|
||
按照以下步骤克隆仓库并安装依赖：
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
git clone <repository_url> fonrey
|
||
cd fonrey
|
||
|
||
# 创建虚拟环境
|
||
python -m venv venv
|
||
source venv/bin/activate # Linux/macOS
|
||
# .\venv\Scripts\activate # Windows
|
||
|
||
# 安装 Python 依赖
|
||
pip install --upgrade pip
|
||
pip install -r requirements.txt
|
||
pip install -r requirements/test.txt # 仅开发环境需要
|
||
|
||
# 安装前端依赖
|
||
npm install
|
||
```
|
||
|
||
---
|
||
|
||
## §3 环境变量 (`.env`)
|
||
|
||
在项目根目录创建 `.env` 文件。以下为必需项清单及示例值：
|
||
|
||
```bash
|
||
# Django 基础配置
|
||
DEBUG=True
|
||
SECRET_KEY=django-insecure-development-key-change-me
|
||
ALLOWED_HOSTS=localhost,127.0.0.1,.fonrey.test
|
||
|
||
# 数据库配置 (需配合 Docker Compose)
|
||
DATABASE_URL=postgres://fonrey_user:fonrey_password@localhost:5432/fonrey_db
|
||
# 如果使用 PgBouncer
|
||
# DATABASE_URL=postgres://fonrey_user:fonrey_password@localhost:6432/fonrey_db
|
||
|
||
# Redis 配置
|
||
REDIS_URL=redis://localhost:6379/0
|
||
|
||
# Celery 配置
|
||
CELERY_BROKER_URL=redis://localhost:6379/1
|
||
CELERY_RESULT_BACKEND=redis://localhost:6379/1
|
||
|
||
# Cloudflare R2 / S3 存储 (本地开发推荐使用 MinIO)
|
||
AWS_ACCESS_KEY_ID=minio_admin
|
||
AWS_SECRET_ACCESS_KEY=minio_password
|
||
AWS_STORAGE_BUCKET_NAME=fonrey-media
|
||
AWS_S3_ENDPOINT_URL=http://localhost:9000
|
||
AWS_S3_REGION_NAME=auto
|
||
|
||
# Sentry (本地开发可选)
|
||
SENTRY_DSN=
|
||
|
||
# 加密密钥 (AES-256-GCM，必须为 32 字节 Base64)
|
||
FIELD_ENCRYPTION_KEY=your-32-byte-base64-encoded-key
|
||
```
|
||
|
||
---
|
||
|
||
## §4 数据库与缓存启动
|
||
|
||
推荐使用 Docker Compose 快速拉起基础服务。项目根目录应包含 `docker-compose.yml`：
|
||
|
||
```bash
|
||
# 启动 PostgreSQL, Redis, MinIO
|
||
docker-compose up -d
|
||
|
||
# 验证服务状态
|
||
docker-compose ps
|
||
```
|
||
|
||
**PgBouncer 提示**: 生产环境强制使用 PgBouncer 进行连接池管理。本地开发环境下，如果需要模拟高并发连接，可开启 docker-compose 中的 pgbouncer 服务并将 `DATABASE_URL` 指向 6432 端口。
|
||
|
||
---
|
||
|
||
## §5 django-tenants 初始化
|
||
|
||
由于项目采用 `django-tenants` 多租户架构，必须先初始化公共 Schema (public schema)：
|
||
|
||
```bash
|
||
# 1. 运行公共 Schema 的迁移
|
||
python manage.py migrate_schemas --shared
|
||
|
||
# 2. 创建第一个租户 (手动交互或使用脚本)
|
||
# 注意：在本地开发时，建议将租户域名映射到 .fonrey.test
|
||
```
|
||
|
||
---
|
||
|
||
## §6 测试租户与种子数据
|
||
|
||
目前项目尚未完成自动化 seed 命令。建议通过以下方式手动创建测试环境：
|
||
|
||
### 6.1 创建初始租户 (建议命令)
|
||
*预期放置位置: `apps/tenant/management/commands/setup_dev_tenant.py`*
|
||
|
||
```bash
|
||
# 尚未实现，需后续补写。目前请进入 python shell 手动创建：
|
||
python manage.py shell
|
||
>>> from apps.tenant.models import Tenant, Domain
|
||
>>> tenant = Tenant.objects.create(schema_name='test_tenant', name='测试经纪公司')
|
||
>>> Domain.objects.create(domain='test.fonrey.test', tenant=tenant, is_primary=True)
|
||
```
|
||
|
||
### 6.2 导入枚举种子数据
|
||
```bash
|
||
# 导入 ENUMS.md 定义的公共枚举值
|
||
python manage.py loaddata shared/fixtures/enum_labels.json
|
||
```
|
||
|
||
---
|
||
|
||
## §7 后端启动
|
||
|
||
本地开发环境直接使用 Django 开发服务器即可。生产环境必须使用 Gunicorn + Uvicorn。
|
||
|
||
```bash
|
||
# 本地开发模式
|
||
python manage.py runserver 8000
|
||
```
|
||
|
||
---
|
||
|
||
## §8 Celery 与 Celery Beat 启动
|
||
|
||
涉及异步任务（如图片处理、导出、配房）时，必须启动 Worker 和 Beat：
|
||
|
||
```bash
|
||
# 启动 Worker
|
||
celery -A core worker -l info
|
||
|
||
# 启动 Beat (定时任务)
|
||
celery -A core beat -l info
|
||
```
|
||
|
||
---
|
||
|
||
## §9 前端资源
|
||
|
||
Fonrey 依赖 Tailwind CSS 进行样式构建。
|
||
|
||
```bash
|
||
# 开发模式：监听文件变化并实时编译
|
||
npm run dev
|
||
|
||
# 生产构建
|
||
npm run build
|
||
```
|
||
|
||
---
|
||
|
||
## §10 静态资源与对象存储本地替代方案
|
||
|
||
本地开发建议使用 MinIO 替代 Cloudflare R2。
|
||
|
||
1. 修改 `.env` 中的 `AWS_S3_ENDPOINT_URL` 指向 MinIO 地址。
|
||
2. 确保已手动或通过脚本创建了 `media` 和 `releases` 桶。
|
||
3. 访问 `http://localhost:9001` 进入 MinIO 控制台。
|
||
|
||
---
|
||
|
||
## §11 测试运行手册
|
||
|
||
所有测试基于 `pytest` 运行。
|
||
|
||
### 11.1 运行单元与集成测试
|
||
```bash
|
||
# 运行全量测试
|
||
pytest
|
||
|
||
# 按目录跑集成测试
|
||
pytest tests/integration/property/
|
||
|
||
# 查看覆盖率
|
||
pytest --cov=apps --cov=core
|
||
```
|
||
|
||
### 11.2 运行 E2E 测试 (Playwright)
|
||
```bash
|
||
# 安装浏览器驱动 (仅需一次)
|
||
playwright install chromium
|
||
|
||
# 运行 E2E
|
||
pytest tests/e2e/
|
||
```
|
||
|
||
---
|
||
|
||
## §12 dev / staging / production 配置差异表
|
||
|
||
| 配置项 | Local Dev | Staging | Production |
|
||
|---|---|---|---|
|
||
| DEBUG | True | False | False |
|
||
| 多租户驱动 | django-tenants | django-tenants | django-tenants |
|
||
| 数据库 | Postgres 16 | Postgres 16 (RDS/Self-host) | Postgres 16 + PgBouncer |
|
||
| 存储服务 | MinIO (本地) | Cloudflare R2 | Cloudflare R2 |
|
||
| 任务队列 | Redis | Redis | Redis (Cluster/Sentinel) |
|
||
| 缓存 | Redis | Redis | Redis |
|
||
| 静态资源 | 本地处理 | Cloudflare CDN | Cloudflare CDN |
|
||
| 错误日志 | 控制台 | Sentry | Sentry + Grafana |
|
||
| 服务运行器 | runserver | Gunicorn + Uvicorn | Gunicorn + Uvicorn + Nginx |
|
||
|
||
---
|
||
|
||
## §13 常见故障排查
|
||
|
||
- **schema 切换失败**: 检查 `django-tenants` 中间件是否已启用，且 `ALLOWED_HOSTS` 包含对应的子域名。
|
||
- **R2 401**: 验证 `.env` 中的 AWS 凭证是否正确，桶是否存在。
|
||
- **Celery 任务不执行**: 检查 Redis 是否连通，Worker 是否已启动，且任务是否使用了 `@tenant_task` 装饰器。
|
||
- **HTMX 局刷 404**: 确认视图是否处理了 `HX-Request` 头，且 URL 路由配置正确。
|
||
|
||
---
|
||
|
||
## §14 关联文档索引
|
||
|
||
- [`AGENTS.md`](../AGENTS.md), 技术栈总览与禁止项
|
||
- [`ADR.md`](../ADR.md), 关键技术决策追溯
|
||
- [`TECH_STACK/测试规范.md`](./测试规范.md), 详细测试要求
|
||
- [`DATA_MODEL/DATA_MODEL.md`](../DATA_MODEL/DATA_MODEL.md), 数据架构定义
|
||
|
||
---
|
||
|
||
## §15 待澄清/待补项
|
||
|
||
1. **种子数据脚本**: 尚未实现 `setup_dev_tenant` 命令，目前需手动在 Shell 创建租户。
|
||
2. **MinIO 预设**: 需要一个初始化脚本自动创建所需的 S3 桶（media, releases）。
|
||
3. **Playwright 浏览器环境**: 尚未在 CI 配置中固定特定 Chromium 版本，本地开发建议使用最新版。
|
||
4. **系统配置 DDL**: `AGENTS.md` 提到系统配置 PRD 暂为空，对应的 DDL 迁移可能不完整。
|