ishenwei/nexus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cf4001c4f83bd9e49283b4ace69d5270cdeb9c59
nexus/Project/fonrey/TECH_STACK/TECH_STACK.md
Shen Wei cf4001c4f8 修改文档
2026-04-28 07:38:30 +08:00

13 KiB
Raw Blame History

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 PRD/登录管理/ DATA_MODEL/DATA_MODEL_LOGIN.md tests/integration/account/test_us_account.py v3.1
权限管理 权限管理系统技术方案.md PRD/权限管理/ DATA_MODEL/DATA_MODEL_PERMISSION.md tests/integration/permission/test_us_permission.py v2.1
房源管理 房源管理技术方案.md PRD/房源管理/ DATA_MODEL/DATA_MODEL_PROPERTY.md tests/integration/property/test_us_property.py v1.0
客源管理 客源管理技术方案.md PRD/客源管理/ DATA_MODEL/DATA_MODEL_CLIENT.md tests/integration/client/test_us_client.py v1.0
楼盘管理 楼盘管理技术方案.md PRD/房源管理/（含楼盘） DATA_MODEL/DATA_MODEL_COMPLEX.md tests/integration/complex/test_us_complex.py v1.0
组织人事 组织人事技术方案.md PRD/组织人事管理/ DATA_MODEL/DATA_MODEL_ORG.md tests/integration/org/test_us_org.py v1.0
系统设置 系统设置技术方案.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 全局 API 契约：API_CONTRACT.md MVP 范围与产品总览：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。本节仅列关键结论。

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 中维护
  • 15 章节统一模板发生变更时，须先更新 §9 标准章节骨架，再同步各模块文档
Reference in New Issue View Git Blame Copy Permalink