70 lines
4.0 KiB
Markdown
70 lines
4.0 KiB
Markdown
> **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 (用于房源/客源图片与附件) 。
|
||
- **地图服务**：待规划 (本期不涉及底层地图建设) 。 |