文档更新

Project/fonrey/TECH_STACK/TECH_STACK.md

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