Fonrey 技术栈总纲（TECH_STACK）

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

版本: 2.0 ｜ 最后更新: 2026-04-25 定位: 本文档是 Fonrey 项目技术栈的总索引。所有跨模块的技术决策、版本约束、目录规范、禁止项在此定稿；单一模块的具体技术方案（数据模型、服务层、HTMX 交互、Celery 任务等）见各自子文档（见 §9 索引）。

1. 项目概览

Fonrey（房睿）房产经纪管理系统 —— 面向房地产经纪公司的 B2B SaaS 平台，解决房源/客源信息散乱、跟进缺失、重复录入等痛点，支撑单租户 89,000+ 房源数据量级下的高效匹配。

核心模块：房源管理、客源管理、楼盘管理、组织人事、权限管理、登录管理、系统设置、客户端发布
目标用户：一线经纪人（高频）、店长/经理（每日）、运营/行政（每日）、系统管理员（不定期）
形态：Web 端为主 + Electron 桌面客户端（壳应用）；移动端为 v2 规划
设计哲学：数据一致性 > 录入/筛选速度 > UI 简洁高效。优先保障多租户数据物理隔离与极速响应。

2. 核心技术栈

层级	技术选型	说明
Frontend	HTMX + Alpine.js + Tailwind CSS	无重前端框架；HTMX 局刷、Alpine 管状态、Tailwind 样式
Backend	Django 4.x（ASGI 模式）	支持异步能力
Multi-tenant	`django-tenants`	PostgreSQL Schema 隔离，租户数据物理安全
Database	PostgreSQL 16 + PgBouncer	连接池优化，支撑高并发
Cache	Redis	缓存、限流、Token、权限快照
Tasks	Celery + Celery Beat	异步导出、智能配房、邮件、图片转码
Storage	Cloudflare R2（S3 兼容）	房源图片、附件、客户端安装包
CDN	Cloudflare	静态资源 + 客户端更新包加速
Server	Gunicorn + Uvicorn workers + Nginx	ASGI 服务部署
Monitoring	Sentry + Grafana	错误追踪 + 指标监控
Deployment	Docker Compose	容器化部署
Desktop Client	Electron + electron-updater	壳应用，渲染层复用 Web 技术栈，详见 §7

3. 关键约定

多租户隔离：所有数据库查询必须基于当前租户 Schema；严禁跨租户访问。shared_apps 仅放平台基础数据（Tenant、ClientRelease、PermissionDef 等）。
UI 交互：HTMX 处理局部 DOM 刷新（分页、筛选、联想）；Alpine.js 处理前端状态（弹窗、多选、字数统计）；禁止编写复杂原生 JS。
异步处理：所有耗时 > 500ms 的任务必须经 Celery 异步执行（Excel 导出、图片处理、智能配房、邮件发送）。
错误处理：后端 API 返回标准 JSON 错误格式；HTMX 请求失败触发全局 Toast 提示。
文件命名：Django App 用 snake_case；前端模板组件用 kebab-case。
敏感数据：手机号等 PII 通过 core/encryption.py 加密存储。
配置：环境变量统一通过 .env 注入，禁止硬编码。

4. 目录结构

fonrey/
├── apps/
│   ├── tenants/          # django-tenants 配置（shared_apps）
│   ├── accounts/         # 登录认证（详见 登录管理技术方案.md）
│   ├── permissions/      # 权限管理（详见 权限管理系统技术方案.md）
│   ├── org/              # 组织人事（org_units, staff）
│   ├── region/           # 区域管理（districts, business_areas, metro）
│   ├── complex/          # 楼盘管理（complexes, buildings, schools）
│   ├── property/         # 房源核心（含 models/services/tasks 三层）
│   ├── client/           # 客源管理
│   ├── settings/         # 系统设置（lookup, tags）
│   └── release/          # 客户端发布管理（shared_apps）
├── shared/               # 公共 Schema App
└── core/
    ├── models/base.py    # 抽象基类
    ├── encryption.py     # PII 加密
    └── cache.py          # Redis 工具

Django App 内部分层规范（以 property 为典型，其他模块参照执行）：

apps/property/
├── models/         # 一表一文件，避免单文件膨胀
├── services/       # 业务逻辑（完成度计算、重复检测、搜索等）
├── tasks.py        # Celery 异步任务
├── views.py        # HTMX/JSON 视图
└── urls.py

5. 禁止项（Do NOT）

❌ React / Vue / Angular 等重前端框架
❌ 在请求线程中处理耗时 > 500ms 的任务（必须用 Celery）
❌ 传统页面全刷方案
❌ 复杂原生 JavaScript（优先 HTMX/Alpine 指令）
❌ Electron 渲染进程开启 nodeIntegration: true
❌ 客户端内嵌业务逻辑或本地数据库（壳应用原则）
❌ 跨租户 SQL 查询（必须经 django-tenants 中间件切换 Schema）
❌ 在代码中硬编码密钥、Tenant ID、URL

6. 外部服务

服务	用途	配置位置
Sentry	错误追踪	已配置
Cloudflare R2	房源/客源图片、附件、客户端安装包	bucket: `media`、`releases`
Cloudflare CDN	静态资源 + 客户端更新包加速	复用现有账号
邮件服务	找回密码、通知	待选型（详见登录管理技术方案）
代码签名	EV 证书（DigiCert / Sectigo）	CI/CD 阶段使用
地图服务	v2 规划，本期不涉及	—

7. 客户端发布技术栈（Desktop Client）

完整方案见 PRD：PRD/发布管理/客户端发布管理模块PRD.md。本节仅列最终结论。

框架：Electron（稳定版） + Chromium 内核（随版本固定，不依赖系统浏览器）
渲染层：直接加载 Fonrey Web URL，100% 复用 HTMX + Alpine + Tailwind，渲染层零新增框架
自动更新：electron-updater；更新包存 R2 / 经 CDN 分发；后端检测端点 GET /api/client/updates/latest/（公开）；启动时 + 每 4h 轮询；后台静默下载，下载完成提示重启；服务端可标记强制更新
构建：electron-builder 输出 NSIS .exe + 便携版 .zip；目标 Windows x64（优先），ARM64 按需
代码签名：EV 证书，CI/CD 自动签名，消除 SmartScreen 警告
完整性校验：下载后必须校验 SHA256 与服务端返回一致才能安装
后端模型：apps/release/ClientRelease（shared_apps，所有租户共享版本表）

8. 模块技术方案索引

每个模块的具体技术决策（模型字段、服务层、缓存策略、HTMX/Celery 集成等）见对应子文档：

模块	技术方案文档	PRD	数据模型
登录认证	`登录管理技术方案.md`	`PRD/登录管理/`	`DATA_MODEL/DATA_MODEL_LOGIN.md`
权限管理	`权限管理系统技术方案.md`	`PRD/权限管理/`	`DATA_MODEL/DATA_MODEL_PERMISSION.md`
房源管理	待补充	`PRD/房源管理/`	`DATA_MODEL/DATA_MODEL_PROPERTY.md`
客源管理	待补充	`PRD/客源管理/`	`DATA_MODEL/DATA_MODEL_CLIENT.md`
楼盘管理	待补充	`PRD/房源管理/`（含楼盘）	`DATA_MODEL/DATA_MODEL_COMPLEX.md`
组织人事	待补充	`PRD/组织人事管理/`	`DATA_MODEL/DATA_MODEL_ORG.md`
系统设置	待补充	`PRD/系统配置/`、`PRD/系统管理/`	`DATA_MODEL/DATA_MODEL_PUBLIC.md`
客户端发布	见本文档 §7	`PRD/发布管理/客户端发布管理模块PRD.md`	—

总览数据模型：DATA_MODEL/DATA_MODEL.md MVP 范围与产品总览：PRD/PRD_MVP.md

9. 文档维护原则

本文档仅记录跨模块共识与模块索引，不展开模块细节
模块技术方案在子文档中维护，并通过 §8 表格回链
任何技术栈变更（替换组件、升级主版本、新增外部服务）须同步更新本文档 §2、§5、§6
新增模块时，先在 §4 目录结构补位，再在 §8 索引登记子文档

8.3 KiB Raw Blame History Unescape Escape