nexus/Project/fonrey/TECH_STACK/TECH_STACK.md at 84d27f4210c9f5c19497ebfdca82bc98e16e1367

Files

weishen 7903d703b9 Sync: add ses and networking notes

2026-04-24 20:38:20 +08:00

9.4 KiB

Raw Blame History

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 (用于房源/客源图片与附件；同时用于客户端安装包存储与分发) 。
地图服务：待规划 (本期不涉及底层地图建设) 。

8. 客户端发布技术栈 (Desktop Client Stack)

本节对应 PRD：Project/fonrey/PRD/发布管理/客户端发布管理模块PRD.md 所有决策均已在 PRD 中完成选型论证，此处为最终结论，直接执行。

8.1 客户端框架

框架：Electron（当前稳定版）
内核：Electron 捆绑的 Chromium（版本随 Electron 版本固定，不依赖系统浏览器）
主进程语言：Node.js（JavaScript / TypeScript）
渲染层：直接加载 Fonrey Web 应用 URL，100% 复用现有 HTMX + Alpine.js + Tailwind CSS 技术栈，渲染层不新增任何框架

8.2 自动更新

更新库：electron-updater（electron-builder 生态，成熟方案）
更新包存储：Cloudflare R2（复用现有存储账号，新增 releases bucket）
更新包分发：Cloudflare CDN 加速（复用现有 CDN 配置）
更新检测端点：Django 后端新增 /api/client/updates/latest/（GET，公开接口，无需登录）
检测时机：客户端启动时 + 每 4 小时轮询一次
更新模式：后台静默下载，下载完成后提示用户重启；服务端可将版本标记为"强制更新"，客户端不可跳过

8.3 安装包构建与签名

构建工具：electron-builder（输出 NSIS 安装包 .exe + 便携版 .zip）
目标平台：Windows x64（优先），ARM64 按需支持
代码签名：EV 代码签名证书（DigiCert 或 Sectigo），由 CI/CD 在构建时自动签名，消除 Windows SmartScreen 警告
CI/CD：待确认平台（GitHub Actions / Jenkins），构建流水线负责：编译 → 签名 → 上传 R2 → 调用发布 API

8.4 Django 后端新增模块

在现有 fonrey/apps/ 目录下新增：

apps/
└── release/              # 客户端发布管理
    ├── models.py         # ClientRelease（版本号、类型、状态、下载URL、SHA256、更新日志）
    ├── views.py          # 公开更新检测 API + 管理后台 CRUD 视图
    ├── urls.py
    └── admin.py

ClientRelease 模型关键字段：

字段	类型	说明
`version`	CharField	SemVer 格式，如 `1.2.3`，唯一索引
`platform`	CharField	平台标识，如 `win32`
`arch`	CharField	CPU 架构，如 `x64`
`release_type`	CharField	`normal` / `force`（强制更新）
`status`	CharField	`draft` / `published` / `archived`
`download_url`	URLField	EXE 安装包 Cloudflare R2 URL
`portable_url`	URLField	ZIP 便携版 URL（可选）
`checksum_sha256`	CharField	安装包 SHA256 校验值
`min_required_version`	CharField	低于此版本的客户端强制升级（可选）
`release_notes`	TextField	Markdown 格式更新日志
`published_at`	DateTimeField	发布时间

ClientRelease 属于 shared_apps（公共 Schema），不属于租户隔离范围，所有租户共享同一套客户端版本。

8.5 客户端关键约定

❌ Do NOT 在 Electron 渲染进程中使用 nodeIntegration: true，保持 Web 沙箱安全
❌ Do NOT 在客户端内嵌任何业务逻辑或本地数据库，所有业务数据由服务端提供
❌ Do NOT 在客户端内新开多个 BrowserWindow 加载内部页面，所有导航在单窗口 SPA 内完成（外部链接除外，需在系统浏览器打开）
客户端版本号必须与服务端 ClientRelease.version 严格一致，通过 package.json 的 version 字段统一管理
更新包下载完成后，必须校验 SHA256 与服务端返回值一致后才能执行安装，防止下载损坏或中间人攻击

9.4 KiB Raw Blame History Unescape Escape