ishenwei/nexus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
91fc0b06d60ac2a6bd0d8dc4161d604875f08978
nexus/Project/fonrey/AGENTS.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

318 lines
15 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.
> **For AI assistants**: Read this entire file before writing any code. All decisions here are final. Do not suggest alternatives unless asked. Every new feature or User Story implementation must be accompanied by corresponding tests as defined in this document.
# Fonrey（房睿）— AGENTS.md
**适用对象**：所有 AI Coding Agent（vibe coding 模式）
**文档定位**：开发启动前的强制阅读清单，定义架构约定、禁止项和文档导航
**最后更新**：2026-04-27
---
## 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 技术栈 |
---
## 3. 目录结构
代码库标准目录结构如下，**严格遵循**，不得自行创建新的顶层目录：
```
fonrey/
├── apps/
│ ├── tenant/ # django-tenants 配置（shared_apps）
│ ├── account/ # 登录认证
│ ├── permission/ # 权限管理
│ ├── org/ # 组织人事（org_units, staff）
│ ├── region/ # 区域管理（districts, business_areas）
│ ├── complex/ # 楼盘管理（complexes, buildings, schools）
│ ├── property/ # 房源核心（含 models/services/tasks 三层）
│ ├── client/ # 客源管理
│ ├── setting/ # 系统设置（lookup, tags）
│ └── release/ # 客户端发布管理（shared_apps）
├── shared/ # 公共 Schema App（public schema 模型）
└── core/
├── models/base.py # 抽象基类（所有业务表继承）
├── encryption.py # PII 加密（AES-256-GCM）
└── cache.py # Redis 工具（含 tenant 前缀）
```
**Django App 内部分层规范**（以 `property` 为典型，所有 App 参照执行）：
```
apps/property/
├── models/ # 一表一文件，禁止全部堆在 models.py
├── services/ # 业务逻辑（完成度计算、重复检测、匹配等）
├── tasks.py # Celery 异步任务
├── views.py # HTMX/JSON 视图（薄视图，调 services）
└── urls.py
```
---
## 4. 关键开发约定
### 4.1 多租户隔离（最高优先级）
- 所有数据库查询**必须**基于当前租户 Schema；`django-tenants` 中间件已自动切换，不得绕过
- **严禁**跨租户 SQL 查询（包括 raw SQL 和 ORM 的 `using()` 指定 public schema）
- `shared_apps` 仅放平台基础数据：`Tenant`、`ClientRelease`、`PermissionDef`、`PlatformAdmin` 等
- Celery 任务必须在任务参数中传入 `tenant_schema_name`，任务开头调用 `connection.set_schema(schema_name)` 切换到正确 Schema，**不得依赖外部上下文传递**
### 4.2 前端交互约定
- **HTMX** 处理局部 DOM 刷新：分页、筛选、联想搜索、表单提交
- **Alpine.js** 处理前端状态：弹窗开关、多选状态、字数统计、条件显示
- **禁止**编写复杂原生 JavaScript；逻辑无法用 HTMX/Alpine 覆盖时，优先提出问题而不是自行引入 JS 库
- HTMX 请求失败（4xx/5xx）必须触发全局 Toast 提示（通过 `HX-Trigger` 响应头）
- 所有 HTMX 局部请求后端视图必须校验 `HX-Request` header，防止直接访问返回残缺 HTML
### 4.3 异步任务约定
- 所有耗时 **> 500ms** 的操作**必须**经 Celery 异步执行：Excel 导出、图片处理、智能配房、邮件发送、完成度重算
- Celery Beat 定时任务：私客自动转公客（每小时）、重复客源检测（每日）
- 任务状态存 Redis，前端通过轮询 HTMX 端点展示进度
### 4.4 数据模型约定
| 约定 | 规则 |
|------|------|
| 主键类型 | `UUID v4`（`gen_random_uuid()`），禁止自增整数 |
| 软删除 | 所有核心表含 `deleted_at TIMESTAMPTZ`，查询默认加 `WHERE deleted_at IS NULL` |
| 时间戳 | 全部使用 `TIMESTAMPTZ`（含时区），禁止 naive datetime |
| 手机号存储 | AES-256-GCM 加密，建立 SHA-256 哈希索引，通过 `core/encryption.py` 操作 |
| 审计字段 | `created_by UUID`、`updated_by UUID` 全表覆盖 |
| 枚举值 | 业务枚举用 `VARCHAR + CHECK CONSTRAINT`；不得在代码中硬编码中文枚举值 |
| 金额 | `NUMERIC(12,2)` 万元精度，禁止 FLOAT |
| 大文本 | `TEXT` 类型，不设长度限制 |
| 不可删除记录 | `listing_histories`、`price_changes` 无 `deleted_at`，append-only，禁止物理删除 |
### 4.5 查询性能约定
- 列表查询目标：89,000 条房源 / 200 万条跟进日志下，p95 响应 **< 2 秒**
- **所有列表查询必须使用 Keyset 分页**（`WHERE id > :last_id ORDER BY id`），禁止 OFFSET 分页用于大数据量场景
- 新增表必须在 migration 中同步创建必要索引，不得事后补建
- 高写入表（`follow_logs`、`property_photos`、`permission_change_logs`、`login_attempts`）必须按月分区（`PARTITION BY RANGE`）
### 4.6 安全约定
- 手机号等 PII 数据统一通过 `core/encryption.py` 加密存储，**禁止明文入库**
- 所有配置（密钥、Bucket 名、外部服务 URL）通过 `.env` 注入，**禁止硬编码**
- 每个受权限保护的 View 必须覆盖三个测试场景：有权限（200）、无权限（403）、未登录（302）
- Redis Key 必须携带租户 Schema 前缀，格式：`{tenant_schema}:{module}:{key}`
### 4.7 错误处理约定
- 后端 API 返回标准 JSON 错误格式：`{"error": "...", "code": "SNAKE_CASE_CODE"}`
- View 层禁止直接抛出异常，必须捕获并返回对应 HTTP 状态码
- Celery 任务失败必须记录到 Sentry，并更新任务状态表
### 4.8 文件命名约定
- Django App：`snake_case`（如 `property`、`follow_log`）
- 前端模板组件：`kebab-case`（如 `property-card.html`、`client-form.html`）
- Migration 文件：不得手动重命名，保留 Django 自动生成的序号
---
## 5. 禁止项（Do NOT — 违反视为 Bug）
- ❌ **React / Vue / Angular** 等重前端框架
- ❌ 在请求线程中处理耗时 **> 500ms** 的任务（必须用 Celery）
- ❌ 传统页面全刷方案（除初始页面加载外）
- ❌ 复杂原生 JavaScript（优先 HTMX/Alpine 指令）
- ❌ Electron 渲染进程开启 `nodeIntegration: true`
- ❌ 客户端内嵌业务逻辑或本地数据库（壳应用原则，渲染层只加载 Web URL）
- ❌ 跨租户 SQL 查询（必须经 `django-tenants` 中间件切换 Schema）
- ❌ 代码中硬编码密钥、Tenant ID、URL、枚举中文字符串
- ❌ 使用 OFFSET 分页处理 1000 条以上数据集
- ❌ 手机号/身份证号明文存储
- ❌ 使用 Django 原生 `Client()` 做集成测试（必须用 `TenantClient`）
- ❌ 在 MVP 阶段实现 `PRD_MVP.md §3` 中标注的 Out-of-Scope 功能（移动端、合同、财务、新房、三网发布等）
---
## 6. 测试要求
**核心原则**：每个 P0 User Story 完成后，对应测试必须同步产出，**不允许欠测试债**。
### 测试分层
| 层级 | 工具 | 覆盖目标 | 运行频率 |
|------|------|---------|---------|
| **单元测试** | `pytest-django` + `factory_boy` | `core/`、`services/`、`tasks.py` | 每次 push |
| **集成测试** | `pytest-django` + `TenantClient` | 所有 P0 User Story 的 HTTP 接口 | 每次 push |
| **E2E 测试** | `playwright` (Python) | 5 条核心用户旅程 | 每日定时 |
### 测试关键约定
- 集成测试**必须**使用 `TenantClient`，禁止使用 Django 原生 `Client()`
- HTMX 局部请求测试须携带 `HTTP_HX_REQUEST: true` header，验证返回局部 HTML 而非完整页面
- Celery 任务测试使用 `CELERY_TASK_ALWAYS_EAGER = True` 同步执行
- 外部服务（R2、Redis、邮件）在测试中全部 Mock，禁止真实调用
- 权限测试必须覆盖：有权限（200）、无权限（403）、未登录（302）三场景
### 覆盖率基准
| 模块 | 最低目标 |
|------|---------|
| `core/` 核心基础模块 | ≥ 90% |
| `apps/*/services/` 业务逻辑层 | ≥ 80% |
| `apps/*/views.py` 视图层 | ≥ 70% |
| E2E 核心用户旅程（5 条） | 100% 通过 |
---
## 7. MVP 范围（Phase 1）
**当前阶段**：MVP Phase 1（P0 功能）
实现任何功能前，先对照 `PRD/PRD_MVP.md` 确认是否在 P0 范围。**P0 范围以外的功能在 MVP 阶段禁止实现**，包括但不限于：
- 移动端适配（v2 规划）
- 新房模块、合同、财务、三网发布
- 公客管理（P2）
- 门店分布地图（P2）
**当前 Phase 1 P0 Task 列表**：见 `PRD/TASK.md §Phase 1`（US-ACCOUNT-001~003、US-COMPLEX-001~003、US-PROPERTY-001~008、US-CLIENT-001~017、US-ORG-001~003、US-PERMISSION-001~005、US-SETTING-001）
---
## 8. 数据模型参考（实现前必读）
所有数据模型的**权威来源**如下，开发前必须阅读对应文档，不得凭印象实现：
| 模块 | 数据模型权威文档 |
|------|---------------|
| 总览 & 架构决策 | `DATA_MODEL/DATA_MODEL.md` |
| 房源管理 | `DATA_MODEL/DATA_MODEL_PROPERTY.md` |
| 客源管理 | `DATA_MODEL/DATA_MODEL_CLIENT.md` |
| 楼盘/小区/区域 | `DATA_MODEL/DATA_MODEL_COMPLEX.md` |
| 组织人事 | `DATA_MODEL/DATA_MODEL_ORG.md` |
| 权限管理 | `DATA_MODEL/DATA_MODEL_PERMISSION.md` |
| 登录认证 | `DATA_MODEL/DATA_MODEL_LOGIN.md` |
| Public Schema（平台运营层） | `DATA_MODEL/DATA_MODEL_PUBLIC.md` |
| 系统配置（lookup/setting） | `DATA_MODEL/DATA_MODEL_SETTING.md` |
### 核心领域关系速览
```
[区域/商圈] ──────────────────────────────┐
│ │
[学校管理] │
│ ▼
[楼盘/小区] ── [楼栋] ──────────► [房源] ◄──── [挂牌历史]
│ │
│ ┌────────┼────────┐
│ │ │ │
│ [联系人] [跟进日志] [维护完成度]
│
[客源] ──── [配对记录] ──── [带看记录]
│
[员工/组织] ──── [权限]
```
---
## 9. 技术方案文档导航
| 模块 | 技术方案文档 | PRD |
|------|------------|-----|
| 总纲 & 禁止项 | `TECH_STACK/TECH_STACK.md` | `PRD/PRD_MVP.md` |
| 登录认证 | `TECH_STACK/登录管理技术方案.md` | `PRD/登录管理/` |
| 权限管理 | `TECH_STACK/权限管理系统技术方案.md` | `PRD/权限管理/` |
| 测试规范 | `TECH_STACK/测试规范.md` | — |
| 房源管理 | _待补充_ | `PRD/房源管理/` |
| 客源管理 | _待补充_ | `PRD/客源管理/` |
| 楼盘管理 | _待补充_ | `PRD/房源管理/（含楼盘）` |
| 组织人事 | _待补充_ | `PRD/组织人事管理/` |
| 系统设置 | _待补充_ | `PRD/系统配置/`、`PRD/系统管理/` |
| 客户端发布 | `TECH_STACK/TECH_STACK.md §7` | `PRD/发布管理/客户端发布管理模块PRD.md` |
**设计 Review 记录**（了解当前已知技术债与阻塞项）：
- `REVIEW/REVIEW_全局_2026-04-26.md`（最新）
- `REVIEW/REVIEW_全局_2026-04-25.md`
---
## 10. 已知待解决问题（编码前必须确认）
以下问题在开始编码前需先确认当前状态，若未解决应在实现对应模块前暂停并上报：
| 编号 | 级别 | 问题描述 | 影响模块 |
|------|------|---------|---------|
| **B-01** | 🔴 Blocker | 系统配置 PRD（`PRD/系统配置/系统配置.md`）为空骨架，US-SETTING-001 无法启动 | 系统配置 |
| **B-02** | 🔴 Blocker | 核心枚举三方不一致（PRD ↔ DDL ↔ TASK AC）：客源 status/grade、房源 status 互相矛盾，需先冻结 `DATA_MODEL/ENUMS.md` | 房源、客源 |
| **B-03** | 🔴 Blocker | 权限数据范围档位冲突：§3 非目标"三档" vs §5.6"五档"，DataScope 实现方式未统一 | 权限管理 |
| **B-04** | 🔴 Blocker | Keyset 分页规范完全缺位，89k 房源列表设计错误 | 房源、客源 |
| **M-02** | 🟠 Major | 主表 `properties`/`clients` 缺乏乐观锁字段 `version` | 房源、客源 |
| **M-03** | 🟠 Major | 高写入表分区 DDL 未落地（`follow_logs` 等） | 跟进日志 |
| **M-04** | 🟠 Major | Celery 多租户 schema 切换规范、R2 文件路径前缀规范、查询索引矩阵未补充 | 全局 |
> 详细内容见 `REVIEW/REVIEW_全局_2026-04-26.md`
---
## 11. 文档根目录
所有项目文档位于：`/mnt/d/Workspace/nexus/Project/fonrey/`
```
fonrey/
├── AGENTS.md # 本文件（AI Agent 开发指南）
├── PRD/
│ ├── PRD_MVP.md # MVP 范围书（必读）
│ ├── TASK.md # 全量 Task Board（US 编号）
│ ├── 房源管理/
│ ├── 客源管理/
│ ├── 楼盘管理/
│ ├── 组织人事管理/
│ ├── 权限管理/
│ ├── 登录管理/
│ ├── 系统配置/
│ ├── 系统管理/
│ └── 发布管理/
├── DATA_MODEL/
│ ├── DATA_MODEL.md # 数据模型总览（必读）
│ ├── DATA_MODEL_PROPERTY.md
│ ├── DATA_MODEL_CLIENT.md
│ ├── DATA_MODEL_COMPLEX.md
│ ├── DATA_MODEL_ORG.md
│ ├── DATA_MODEL_PERMISSION.md
│ ├── DATA_MODEL_LOGIN.md
│ └── DATA_MODEL_PUBLIC.md
├── TECH_STACK/
│ ├── TECH_STACK.md # 技术栈总纲（必读）
│ ├── 登录管理技术方案.md
│ ├── 权限管理系统技术方案.md
│ └── 测试规范.md
└── REVIEW/
├── REVIEW_全局_2026-04-26.md # 最新 Review（含阻塞问题）
└── REVIEW_全局_2026-04-25.md
```
Reference in New Issue View Git Blame Copy Permalink