86 lines
5.7 KiB
Markdown
86 lines
5.7 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+ 数据量级下的高效匹配 。
|
||
- **房源管理**：支持住宅/别墅/商铺/商住/写字楼/其他 6 种房源类型（P0 住宅，P1 别墅，商业类低优先级）；核心功能含录入、跟进、图片管理、价格解读、市场报盘、附件、业主联系人；目标 89,000+ 条数据量级
|
||
- **客源管理**：管理购房/租房意向客户（私客为核心，公客/成交客后续版本）；功能含录入私客、智能配房、跟进记录、活跃度分层、转公客/转成交/转无效、联系人管理、操作日志
|
||
- **楼盘管理**：楼盘为房源基础数据底座；功能含楼盘列表、楼盘详情（楼盘信息/楼栋管理/结构管理/照片/价格走势/周边配套）、区域管理（城区/商圈/关联关系）、学校管理；聚焦二手房
|
||
- **系统设置**：平台"控制中心"；本期聚焦首页设置与房源设置（字段标签、必填规则、自定义字段、标签管理）；其余设置（客源/交易/财务/人事OA/合同/通用/移动端/安装登录）在各自模块 PRD 中说明
|
||
- 所有模块均为 Web 端，移动端适配为 v2 规划
|
||
- **目标用户**：一线经纪人（高频）、店长/经理（每日）、运营/行政人员（每日）、系统管理员（不定期）
|
||
- **核心用途**：房源/客源的全生命周期管理、楼盘基础数据维护及多租户业务规则定制 。 。
|
||
- **设计哲学**：优先保障数据一致性与极速的录入/筛选体验，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. 目录结构 (Django App Structure)
|
||
Plaintext
|
||
```
|
||
fonrey/
|
||
├── apps/
|
||
│ ├── tenants/ # django-tenants 配置
|
||
│ ├── org/ # 组织人事（org_units, staff）
|
||
│ ├── region/ # 区域管理（districts, business_areas, metro）
|
||
│ ├── complex/ # 楼盘管理（complexes, buildings, schools）
|
||
│ ├── property/ # 房源核心（properties + 所有子表）
|
||
│ │ ├── models/
|
||
│ │ │ ├── property.py # Property 主表
|
||
│ │ │ ├── contact.py # PropertyContact
|
||
│ │ │ ├── follow_log.py # FollowLog
|
||
│ │ │ ├── key.py # PropertyKey
|
||
│ │ │ ├── commission.py # Commission
|
||
│ │ │ ├── survey.py # FieldSurvey
|
||
│ │ │ ├── photo.py # PropertyPhoto
|
||
│ │ │ ├── attachment.py # PropertyAttachment
|
||
│ │ │ ├── marketing.py # PropertyMarketing
|
||
│ │ │ └── completeness.py # PropertyCompleteness
|
||
│ │ ├── services/
|
||
│ │ │ ├── completeness.py # 完成度计算服务
|
||
│ │ │ ├── duplicate.py # 重复房源检测
|
||
│ │ │ └── search.py # 搜索/筛选服务
|
||
│ │ └── tasks.py # Celery 异步任务
|
||
│ ├── client/ # 客源管理
|
||
│ ├── settings/ # 系统设置（lookup, tags）
|
||
│ └── permissions/ # 权限管理
|
||
├── shared/ # 公共 Schema App（django-tenants shared_apps）
|
||
└── core/
|
||
├── models/base.py # 抽象基类
|
||
├── encryption.py # 手机号加密
|
||
└── cache.py # Redis 缓存工具
|
||
```
|
||
|
||
## 5. 组件实现标准 (Component Standards)
|
||
|
||
根据[[组件清单]]
|
||
## 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 (用于房源/客源图片与附件) 。
|
||
- **地图服务**：待规划 (本期不涉及底层地图建设) 。 |