242 lines
13 KiB
Markdown
242 lines
13 KiB
Markdown
# 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.2 ｜ **最后更新**: 2026-04-27
|
||
**定位**: 本文档是 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/
|
||
│ ├── tenant/ # django-tenants 配置（shared_apps）
|
||
│ ├── account/ # 登录认证（详见 登录管理技术方案.md）
|
||
│ ├── permission/ # 权限管理（详见 权限管理系统技术方案.md）
|
||
│ ├── org/ # 组织人事（org_units, staff）
|
||
│ ├── region/ # 区域管理（districts, business_areas, metro）
|
||
│ ├── complex/ # 楼盘管理（complexes, buildings, schools）
|
||
│ ├── property/ # 房源核心（含 models/services/tasks 三层）
|
||
│ ├── client/ # 客源管理
|
||
│ ├── setting/ # 系统设置（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`](./登录管理技术方案.md) | `PRD/登录管理/` | `DATA_MODEL/DATA_MODEL_LOGIN.md` | `tests/integration/account/test_us_account.py` | `v3.1` |
|
||
| 权限管理 | [`权限管理系统技术方案.md`](./权限管理系统技术方案.md) | `PRD/权限管理/` | `DATA_MODEL/DATA_MODEL_PERMISSION.md` | `tests/integration/permission/test_us_permission.py` | `v2.1` |
|
||
| 房源管理 | [`房源管理技术方案.md`](./房源管理技术方案.md) | `PRD/房源管理/` | `DATA_MODEL/DATA_MODEL_PROPERTY.md` | `tests/integration/property/test_us_property.py` | `v1.0` |
|
||
| 客源管理 | [`客源管理技术方案.md`](./客源管理技术方案.md) | `PRD/客源管理/` | `DATA_MODEL/DATA_MODEL_CLIENT.md` | `tests/integration/client/test_us_client.py` | `v1.0` |
|
||
| 楼盘管理 | [`楼盘管理技术方案.md`](./楼盘管理技术方案.md) | `PRD/房源管理/`（含楼盘） | `DATA_MODEL/DATA_MODEL_COMPLEX.md` | `tests/integration/complex/test_us_complex.py` | `v1.0` |
|
||
| 组织人事 | [`组织人事技术方案.md`](./组织人事技术方案.md) | `PRD/组织人事管理/` | `DATA_MODEL/DATA_MODEL_ORG.md` | `tests/integration/org/test_us_org.py` | `v1.0` |
|
||
| 系统设置 | [`系统设置技术方案.md`](./系统设置技术方案.md) | `PRD/系统配置/`、`PRD/系统管理/` | `DATA_MODEL/DATA_MODEL_SETTING.md` | `tests/integration/setting/test_us_setting.py` | `v1.2` |
|
||
| 客户端发布 | 见本文档 §7 | `PRD/发布管理/客户端发布管理模块PRD.md` | — | — | `§7（本文）` |
|
||
|
||
**总览数据模型**：[`DATA_MODEL/DATA_MODEL.md`](../DATA_MODEL/DATA_MODEL.md)
|
||
**全局 API 契约**：[`API_CONTRACT.md`](./API_CONTRACT.md)
|
||
**MVP 范围与产品总览**：[`PRD/PRD_MVP.md`](../PRD/PRD_MVP.md)
|
||
|
||
---
|
||
|
||
## 9. 模块技术方案一致性矩阵（15 标准章节）
|
||
|
||
> 目的：确保各模块技术方案采用同构模板，便于 AI Agent 与开发同学横向查阅、执行与回归。
|
||
|
||
### 9.1 标准章节骨架（统一实现标准）
|
||
|
||
| 标准章节编号 | 标准章节名 |
|
||
|---|---|
|
||
| 1 | 文档定位与边界 |
|
||
| 2 | 范围定义 |
|
||
| 3 | 模块架构边界 |
|
||
| 4 | API 设计原则 |
|
||
| 5 | 端点清单（核心） |
|
||
| 6 | 关键 API 规范（请求/响应） |
|
||
| 7 | HTMX 交互约定 |
|
||
| 8 | 权限与数据范围 |
|
||
| 9 | 异步任务与缓存策略 |
|
||
| 10 | 性能与可靠性约束 |
|
||
| 11 | 安全与合规 |
|
||
| 12 | 错误码建议 |
|
||
| 13 | 测试映射 |
|
||
| 14 | 落地顺序建议 |
|
||
| 15 | 文档同步规则 |
|
||
|
||
### 9.2 模块覆盖情况（2026-04-27）
|
||
|
||
| 模块 | 技术方案文档 | 15 章节覆盖 | 备注 |
|
||
|---|---|---:|---|
|
||
| 登录认证 | `登录管理技术方案.md` | 15/15 | 完全覆盖 |
|
||
| 权限管理 | `权限管理系统技术方案.md` | 15/15 | 完全覆盖 |
|
||
| 房源管理 | `房源管理技术方案.md` | 15/15 | 完全覆盖 |
|
||
| 客源管理 | `客源管理技术方案.md` | 15/15 | 完全覆盖 |
|
||
| 楼盘管理 | `楼盘管理技术方案.md` | 15/15 | 完全覆盖 |
|
||
| 组织人事 | `组织人事技术方案.md` | 15/15 | 完全覆盖 |
|
||
| 系统设置 | `系统设置技术方案.md` | 15/15 | 完全覆盖 |
|
||
|
||
### 9.3 使用规则（对 AI Agent 生效）
|
||
|
||
- 新增模块技术方案时，必须按上表 15 章节骨架创建，不得自定义主结构。
|
||
- 若模块存在特殊子节，可在对应主章节下扩展 `x.y`，但不得删除主章节。
|
||
- PRD/TASK 范围变化后，先更新模块文档，再回填本矩阵覆盖状态。
|
||
|
||
---
|
||
|
||
## 10. 测试策略
|
||
|
||
> **完整测试规范**见：[`测试规范.md`](./测试规范.md)。本节仅列关键结论。
|
||
|
||
Fonrey 采用 AI vibe coding 模式开发，测试是保证每日迭代质量的唯一安全网。**每个 P0 User Story 完成后，对应测试必须同步产出，不允许欠测试债。**
|
||
|
||
### 测试分层
|
||
|
||
| 层级 | 工具 | 覆盖目标 | 运行频率 |
|
||
|------|------|---------|---------|
|
||
| **单元测试** | `pytest-django` + `factory_boy` | `core/`、`services/`、`tasks.py` | 每次 push |
|
||
| **集成测试** | `pytest-django` TenantClient | 所有 P0 User Story 的 HTTP 接口 | 每次 push |
|
||
| **E2E 测试** | `playwright` (Python) | 5 条核心用户旅程 | 每日定时 |
|
||
|
||
### 关键约定
|
||
|
||
- 所有集成测试必须使用 `django-tenants` 的 `TenantClient`，禁止使用 Django 原生 `Client()`
|
||
- HTMX 局部请求测试须携带 `HTTP_HX_REQUEST: true` header，并验证返回局部 HTML 而非完整页面
|
||
- Celery 任务测试使用 `CELERY_TASK_ALWAYS_EAGER = True` 同步执行
|
||
- 外部服务（R2、Redis、邮件）在测试中全部 Mock，禁止真实调用
|
||
- 每个受权限保护的 View，必须覆盖：有权限（200）、无权限（403）、未登录（302）三个场景
|
||
|
||
### 覆盖率基准
|
||
|
||
| 模块 | 最低目标 |
|
||
|------|---------|
|
||
| `core/` 核心基础模块 | ≥ 90% |
|
||
| `apps/*/services/` 业务逻辑层 | ≥ 80% |
|
||
| `apps/*/views.py` 视图层 | ≥ 70% |
|
||
| E2E 核心用户旅程（5 条） | 100% 通过 |
|
||
|
||
### CI 自动化
|
||
|
||
- 每次 push 到 `main` / `develop` 自动运行单元测试 + 集成测试
|
||
- 每日北京时间凌晨 2 点自动运行全量套件（含 E2E）
|
||
- 配置文件：`.github/workflows/daily-test.yml`
|
||
|
||
---
|
||
|
||
## 11. 文档维护原则
|
||
|
||
- 本文档仅记录**跨模块共识**与**模块索引**，不展开模块细节
|
||
- 模块技术方案在子文档中维护，并通过 §8 表格回链
|
||
- API 契约总则在 `API_CONTRACT.md` 维护；模块文档只做模块特化，不得覆盖全局契约
|
||
- 任何技术栈变更（替换组件、升级主版本、新增外部服务）须同步更新本文档 §2、§5、§6
|
||
- 新增模块时，先在 §4 目录结构补位，再在 §8 索引登记子文档
|
||
- 测试规范变更须同步更新 §10 关键结论，完整细节在 [`测试规范.md`](./测试规范.md) 中维护
|
||
- 15 章节统一模板发生变更时，须先更新 §9 标准章节骨架，再同步各模块文档
|
||
|
||
|