> **For AI assistants**: Read this entire file before writing any code. All decisions here are final. Do not suggest alternatives unless asked.

## 1. 项目概览 (Project Overview)

**Fonrey (房睿) 房产经纪管理系统** 是一款面向房地产经纪公司的 B2B SaaS 平台 。系统核心目标是解决房源、客源信息散乱、跟进缺失及重复录入等痛点，支持 89,000+ 数据量级下的高效匹配 。
- **核心用途**：房源/客源的全生命周期管理、楼盘基础数据维护及多租户业务规则定制 。
- **目标用户**：一线经纪人（高频使用）、店长/经理、运营/行政人员 。
- **设计哲学**：优先保障数据一致性与极速的录入/筛选体验，UI 简洁高效 。

## 2. 核心技术栈 (Core Stack)
- **Frontend**: HTMX + Alpine.js + Tailwind CSS (无重前端框架，追求极致响应) 。
- **Backend**: Django 4.x (ASGI 模式，支持异步能力) 。
- **Multi-tenant**: `django-tenants` (Postgres Schema 隔离，确保租户数据物理安全) 。
- **Database**: PostgreSQL + PgBouncer (连接池优化) 。
- **Cache**: Redis 。
- **Tasks**: Celery + Celery Beat (用于异步导出、智能配房任务) 。
- **Storage**: Cloudflare R2 (或 AWS S3 compatible) 。
- **CDN**: Cloudflare 。
- **Server**: Gunicorn + Uvicorn workers + Nginx 。
- **Monitoring**: Sentry + Grafana 。
- **Deployment**: Docker Compose。

## 3. 关键约定 (Key Conventions)

- **UI 交互模式**：
    - 采用 **HTMX** 进行局部 DOM 刷新（如分页、筛选、搜索联想）。
    - 采用 **Alpine.js** 处理前端状态（如弹窗开关、复选框多选、字数统计）。
- **多租户隔离**：所有数据库查询必须基于当前租户 Schema，严禁跨租户访问数据。
- **文件命名**：Django App 采用小写下划线 `snake_case`，前端模版组件采用 `kebab-case`。
- **异步处理**：所有耗时任务（如 8.9 万条房源的 Excel 导出、图片转码、复杂的智能配房计算）必须通过 Celery 异步执行 。
- **错误处理**：后端 API 需返回标准 JSON 错误格式；前端 HTMX 请求失败需触发全局 Toast 提示。

## 4. 目录结构 (Directory Structure) **还要修改**
Plaintext
```
/
├── apps/               # Django 应用模块
│   ├── listings/       # 房源管理模块
│   ├── leads/          # 客源管理模块
│   ├── locations/      # 楼盘/区域管理模块
│   └── settings/       # 系统设置模块
├── core/               # 项目核心配置 (settings, asgi, wsgi)
├── static/             # 静态资源 (CSS, Alpine.js logic)
├── templates/          # Django Templates
│   ├── base.html
│   └── partials/       # HTMX 局部刷新组件
├── docker-compose.yml  # 部署配置
└── .env.example        # 环境变量模板
```

## 5. 组件实现标准 (Component Standards)

根据《组件清单.pdf》，以下组件必须按此标准实现：
- **数据表格 (Data Table)**：
    - **排序**：通过 Django 后端排序 + HTMX `hx-get` 刷新表格体 。
    - **自定义列**：使用 Alpine.js `x-show` 控制显示，并可选择性持久化至后端 。
- **模态对话框 (Modal)**：使用 Tailwind 定义样式，Alpine.js 管理 `open` 状态 。
- **分页 (Pagination)**：Django `Paginator` 生成逻辑，HTMX 驱动无刷新翻页 。
- **树形选择 (Tree Select)**：针对“相关员工/组织架构”的高级组件，使用 Alpine.js 递归渲染 。

## 6. Do NOT Use
- **❌ Do NOT** 使用 React/Vue/Angular 等重前端框架。
- **❌ Do NOT** 在 Server Action 中处理耗时超过 500ms 的任务（请用 Celery）。
- **❌ Do NOT** 使用传统的页面全刷方案。
- **❌ Do NOT** 编写复杂的原生 JavaScript，优先使用 HTMX/Alpine 指令。

## 7. 外部服务 (External Services)
- **监控**：Sentry (已配置用于错误追踪) 。
- **对象存储**：Cloudflare R2 (用于房源/客源图片与附件) 。
- **地图服务**：待规划 (本期不涉及底层地图建设) 。