文档更新

Project/fonrey/TECH_STACK/本地开发手册.md

@@ -0,0 +1,260 @@
+> 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 迁移可能不完整。