> 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 迁移可能不完整。