ishenwei/nexus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Sync: add healthcare compliance notes

Browse Source
This commit is contained in:
weishen
2026-04-25 08:20:22 +08:00
parent 7d0e10b299
commit df840cc5b8
21 changed files with 831 additions and 135 deletions
Download Patch File Download Diff File Expand all files Collapse all files

264
Project/fonrey/TECH_STACK/TECH_STACK.md
View File

@@ -1,155 +1,153 @@
# 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.
## 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 (用于房源/客源图片与附件；同时用于客户端安装包存储与分发) 。
- **地图服务**：待规划 (本期不涉及底层地图建设) 。
**版本**: 2.0 ｜ **最后更新**: 2026-04-25
**定位**: 本文档是 Fonrey 项目技术栈的**总索引**。所有跨模块的技术决策、版本约束、目录规范、禁止项在此定稿；**单一模块的具体技术方案**（数据模型、服务层、HTMX 交互、Celery 任务等）见各自子文档（见 §9 索引）。
---
## 8. 客户端发布技术栈 (Desktop Client Stack)
## 1. 项目概览
> 本节对应 PRD：`Project/fonrey/PRD/发布管理/客户端发布管理模块PRD.md`
> 所有决策均已在 PRD 中完成选型论证，此处为最终结论，直接执行。
**Fonrey（房睿）房产经纪管理系统** —— 面向房地产经纪公司的 B2B SaaS 平台，解决房源/客源信息散乱、跟进缺失、重复录入等痛点，支撑单租户 89,000+ 房源数据量级下的高效匹配。
### 8.1 客户端框架
- **核心模块**：房源管理、客源管理、楼盘管理、组织人事、权限管理、登录管理、系统设置、客户端发布
- **目标用户**：一线经纪人（高频）、店长/经理（每日）、运营/行政（每日）、系统管理员（不定期）
- **形态**：Web 端为主 + Electron 桌面客户端（壳应用）；移动端为 v2 规划
- **设计哲学**：数据一致性 > 录入/筛选速度 > UI 简洁高效。优先保障多租户数据物理隔离与极速响应。
- **框架**：[Electron](https://www.electronjs.org/)（当前稳定版）
- **内核**：Electron 捆绑的 Chromium（版本随 Electron 版本固定，不依赖系统浏览器）
- **主进程语言**：Node.js（JavaScript / TypeScript）
- **渲染层**：直接加载 Fonrey Web 应用 URL，100% 复用现有 HTMX + Alpine.js + Tailwind CSS 技术栈，**渲染层不新增任何框架**
---
### 8.2 自动更新
## 2. 核心技术栈
- **更新库**：`electron-updater`（`electron-builder` 生态，成熟方案）
- **更新包存储**：Cloudflare R2（复用现有存储账号，新增 `releases` bucket）
- **更新包分发**：Cloudflare CDN 加速（复用现有 CDN 配置）
- **更新检测端点**：Django 后端新增 `/api/client/updates/latest/`（GET，公开接口，无需登录）
- **检测时机**：客户端启动时 + 每 4 小时轮询一次
- **更新模式**：后台静默下载，下载完成后提示用户重启；服务端可将版本标记为"强制更新"，客户端不可跳过
| 层级 | 技术选型 | 说明 |
|---|---|---|
| **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 |
### 8.3 安装包构建与签名
---
- **构建工具**：`electron-builder`（输出 NSIS 安装包 `.exe` + 便携版 `.zip`）
- **目标平台**：Windows x64（优先），ARM64 按需支持
- **代码签名**：EV 代码签名证书（DigiCert 或 Sectigo），由 CI/CD 在构建时自动签名，消除 Windows SmartScreen 警告
- **CI/CD**：待确认平台（GitHub Actions / Jenkins），构建流水线负责：编译 → 签名 → 上传 R2 → 调用发布 API
## 3. 关键约定
### 8.4 Django 后端新增模块
- **多租户隔离**：所有数据库查询必须基于当前租户 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` 注入，禁止硬编码。
在现有 `fonrey/apps/` 目录下新增：
---
## 4. 目录结构
```
apps/
└── release/ # 客户端发布管理
├── models.py # ClientRelease（版本号、类型、状态、下载URL、SHA256、更新日志）
├── views.py # 公开更新检测 API + 管理后台 CRUD 视图
├── urls.py
└── admin.py
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 工具
```
**`ClientRelease` 模型关键字段**：
**Django App 内部分层规范**（以 `property` 为典型，其他模块参照执行）：
| 字段 | 类型 | 说明 |
|------|------|------|
| `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 | 发布时间 |
```
apps/property/
├── models/ # 一表一文件，避免单文件膨胀
├── services/ # 业务逻辑（完成度计算、重复检测、搜索等）
├── tasks.py # Celery 异步任务
├── views.py # HTMX/JSON 视图
└── urls.py
```
**`ClientRelease` 属于 `shared_apps`（公共 Schema）**，不属于租户隔离范围，所有租户共享同一套客户端版本。
---
### 8.5 客户端关键约定
## 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` |
| 权限管理 | [`权限管理系统技术方案.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`](../DATA_MODEL/DATA_MODEL.md)
**MVP 范围与产品总览**：[`PRD/PRD_MVP.md`](../PRD/PRD_MVP.md)
---
## 9. 文档维护原则
- 本文档仅记录**跨模块共识**与**模块索引**，不展开模块细节
- 模块技术方案在子文档中维护，并通过 §8 表格回链
- 任何技术栈变更（替换组件、升级主版本、新增外部服务）须同步更新本文档 §2、§5、§6
- 新增模块时，先在 §4 目录结构补位，再在 §8 索引登记子文档
- **❌ Do NOT** 在 Electron 渲染进程中使用 `nodeIntegration: true`，保持 Web 沙箱安全
- **❌ Do NOT** 在客户端内嵌任何业务逻辑或本地数据库，所有业务数据由服务端提供
- **❌ Do NOT** 在客户端内新开多个 `BrowserWindow` 加载内部页面，所有导航在单窗口 SPA 内完成（外部链接除外，需在系统浏览器打开）
- 客户端版本号必须与服务端 `ClientRelease.version` 严格一致，通过 `package.json` 的 `version` 字段统一管理
- 更新包下载完成后，必须校验 SHA256 与服务端返回值一致后才能执行安装，防止下载损坏或中间人攻击