ishenwei/nexus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dfcf7de0034d1b2a2ca83d2a185763e04d1f5063
nexus/Project/fonrey/TECH_STACK/TECH_STACK.md
Shen Wei 712a33fbac docs: 新增系统配置模块PRD及数据模型文档，更新TASK.md 
- 新增 PRD/系统配置/系统配置模块PRD.md（v0.1 Draft）
  - MVP 范围：US-SETTING-001-A（Lookup Items）、B（房源字段必填规则）、C（客源录入规则）
- 新增 PRD/系统配置/系统配置数据模型设计说明_for_Atlas.md
- 新增 PRD/系统配置/系统配置参数数据.md（竞品参数数据）
- 删除旧版 PRD/系统配置/系统配置.md（已被新PRD替代）
- 新增 DATA_MODEL/DATA_MODEL_SETTING.md（系统配置数据模型）
- 新增 DATA_MODEL/ENUMS.md（枚举定义与约定）
- 新增 AGENTS.md（AI Agent 开发规范）
- 更新 PRD/TASK.md：US-SETTING-001 拆分为 A/B/C 三个子任务，修正参考文档路径与验收标准
- 新增 VIBE_CODING_开工前缺失清单.md
- 新增 TECH_STACK/房源管理技术方案.md
- 更新 DATA_MODEL/DATA_MODEL.md、DATA_MODEL_CLIENT.md、DATA_MODEL_LOGIN.md
- 更新 PRD/PRD_MVP.md、PRD/权限管理/权限管理模块PRD.md
- 更新 TECH_STACK/TECH_STACK.md、权限管理系统技术方案.md
- 更新 UI_DESIGN/preview.html、UI_SYSTEM/UI_SYSTEM.md
- 新增 prompt/PRD - 为系统设置生成PRD设计文档.md、更新 prompt 模板
2026-04-27 15:33:12 +08:00

195 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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/
│ ├── 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` |
| 权限管理 | [`权限管理系统技术方案.md`](./权限管理系统技术方案.md) | `PRD/权限管理/` | `DATA_MODEL/DATA_MODEL_PERMISSION.md` |
| 房源管理 | [`房源管理技术方案.md`](./房源管理技术方案.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. 测试策略
> **完整测试规范**见：[`测试规范.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`
---
## 10. 文档维护原则
- 本文档仅记录**跨模块共识**与**模块索引**，不展开模块细节
- 模块技术方案在子文档中维护，并通过 §8 表格回链
- 任何技术栈变更（替换组件、升级主版本、新增外部服务）须同步更新本文档 §2、§5、§6
- 新增模块时，先在 §4 目录结构补位，再在 §8 索引登记子文档
- 测试规范变更须同步更新 §9 关键结论，完整细节在 [`测试规范.md`](./测试规范.md) 中维护
Reference in New Issue View Git Blame Copy Permalink