463 lines
23 KiB
Markdown
463 lines
23 KiB
Markdown
# 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.5 ｜ **最后更新**: 2026-04-30
|
||
**定位**: 本文档是 Fonrey 项目技术栈的**总索引**。所有跨模块的技术决策、版本约束、目录规范、禁止项在此定稿；**单一模块的具体技术方案**（数据模型、服务层、HTMX 交互、Celery 任务等）见各自子文档（见 §9 索引）。
|
||
|
||
---
|
||
|
||
## 变更历史
|
||
|
||
| 日期 | 变更人 | 变更内容 |
|
||
|---|---|---|
|
||
| 2026-04-30 | Atlas | 新增 ADR 导航入口与变更治理规则（README 缺失场景下接入 TECH_STACK / DATA_MODEL / AGENTS） |
|
||
| 2026-04-30 | Atlas | 补充“变更历史”章节（文档治理） |
|
||
|
||
## 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
|
||
- ❌ Celery 任务内手写 `connection.set_schema(...)`（必须用 `@tenant_task` 装饰器，见 §12）
|
||
- ❌ 业务视图/服务层直接调用 `<Model>.objects.filter/get/all(...)`（必须用 `Model.scoped(staff)`，见 §14）
|
||
- ❌ R2 对象 key 使用原始文件名或 tenant_id（UUID）前缀（必须按 §13 路径模板）
|
||
|
||
---
|
||
|
||
## 6. 外部服务
|
||
|
||
| 服务 | 用途 | 配置位置 |
|
||
|---|---|---|
|
||
| **Sentry** | 错误追踪 | 已配置 |
|
||
| **Cloudflare R2** | 房源/客源图片、附件、客户端安装包 | bucket: `media`、`releases` |
|
||
| **Cloudflare CDN** | 静态资源 + 客户端更新包加速 | 复用现有账号 |
|
||
| **邮件服务** | 找回密码、通知 | 待选型（详见 登录管理技术方案） |
|
||
| **代码签名** | EV 证书（DigiCert / Sectigo） | CI/CD 阶段使用 |
|
||
| **地图服务** | v2 规划，本期不涉及 | — |
|
||
|
||
---
|
||
|
||
## 7. 客户端发布技术栈（Desktop Client）
|
||
|
||
> **完整方案**见：`TECH_STACK/平台管理后台技术方案.md`（实现口径）与 `PRD/平台管理后台/平台管理后台PRD.md`（需求口径）。本节仅列最终结论。
|
||
|
||
- **框架**：Electron（稳定版） + Chromium 内核（随版本固定，不依赖系统浏览器）
|
||
- **渲染层**：直接加载 Fonrey Web URL，**100% 复用 HTMX + Alpine + Tailwind**，渲染层零新增框架
|
||
- **自动更新**：`electron-updater`；更新包存 R2 / 经 CDN 分发；后端检测端点 `GET /api/release/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` | `tests/integration/account/test_us_account.py` | `v3.1` |
|
||
| 权限管理 | [`权限管理系统技术方案.md`](./权限管理系统技术方案.md) | `PRD/权限管理/` | `DATA_MODEL/DATA_MODEL_PERMISSION.md` | `tests/integration/permission/test_us_permission.py` | `v2.1` |
|
||
| 房源管理 | [`房源管理技术方案.md`](./房源管理技术方案.md) | `PRD/房源管理/` | `DATA_MODEL/DATA_MODEL_PROPERTY.md` | `tests/integration/property/test_us_property.py` | `v1.0` |
|
||
| 客源管理 | [`客源管理技术方案.md`](./客源管理技术方案.md) | `PRD/客源管理/` | `DATA_MODEL/DATA_MODEL_CLIENT.md` | `tests/integration/client/test_us_client.py` | `v1.0` |
|
||
| 楼盘管理 | [`楼盘管理技术方案.md`](./楼盘管理技术方案.md) | `PRD/房源管理/`（含楼盘） | `DATA_MODEL/DATA_MODEL_COMPLEX.md` | `tests/integration/complex/test_us_complex.py` | `v1.0` |
|
||
| 组织人事 | [`组织人事技术方案.md`](./组织人事技术方案.md) | `PRD/组织人事管理/` | `DATA_MODEL/DATA_MODEL_ORG.md` | `tests/integration/org/test_us_org.py` | `v1.0` |
|
||
| 系统设置 | [`系统设置技术方案.md`](./系统设置技术方案.md) | `PRD/系统配置/` | `DATA_MODEL/DATA_MODEL_SETTING.md` | `tests/integration/setting/test_us_setting.py` | `v1.2` |
|
||
| 平台管理后台 | [`平台管理后台技术方案.md`](./平台管理后台技术方案.md) | `PRD/平台管理后台/平台管理后台PRD.md` | `DATA_MODEL/DATA_MODEL_PUBLIC.md`（`tenants` / `platform_admins` / `client_releases` / `client_heartbeats` / `tenant_backups` / `tenant_data_exports` / `audit_logs` / `feature_flags`） | `tests/integration/admin_console/`、`tests/integration/release/test_us_release.py` | `v1.0` |
|
||
|
||
**总览数据模型**：[`DATA_MODEL/DATA_MODEL.md`](../DATA_MODEL/DATA_MODEL.md)
|
||
**全局 API 契约**：[`API_CONTRACT.md`](./API_CONTRACT.md)
|
||
**MVP 范围与产品总览**：[`PRD/PRD_MVP.md`](../PRD/PRD_MVP.md)
|
||
**ADR 动态决策记录**：[`ADR.md`](../ADR.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-30）
|
||
|
||
| 模块 | 技术方案文档 | 15 章节覆盖 | 备注 |
|
||
|---|---|---:|---|
|
||
| 登录认证 | `登录管理技术方案.md` | 15/15 | 完全覆盖 |
|
||
| 权限管理 | `权限管理系统技术方案.md` | 15/15 | 完全覆盖 |
|
||
| 房源管理 | `房源管理技术方案.md` | 15/15 | 完全覆盖 |
|
||
| 客源管理 | `客源管理技术方案.md` | 15/15 | 完全覆盖 |
|
||
| 楼盘管理 | `楼盘管理技术方案.md` | 15/15 | 完全覆盖 |
|
||
| 组织人事 | `组织人事技术方案.md` | 15/15 | 完全覆盖 |
|
||
| 系统设置 | `系统设置技术方案.md` | 15/15 | 完全覆盖 |
|
||
| 客户端发布 | `平台管理后台技术方案.md` | 15/15 | 已合并入「平台管理后台技术方案」（`ADR-20260502-002`），覆盖 Electron/EV/Heartbeat/自动升级/R2/官网下载/便携版 |
|
||
|
||
### 9.3 使用规则（对 AI Agent 生效）
|
||
|
||
- 新增模块技术方案时，必须按上表 15 章节骨架创建，不得自定义主结构。
|
||
- 若模块存在特殊子节，可在对应主章节下扩展 `x.y`，但不得删除主章节。
|
||
- PRD/TASK 范围变化后，先更新模块文档，再回填本矩阵覆盖状态。
|
||
|
||
---
|
||
|
||
## 10. 测试策略
|
||
|
||
> **完整测试规范**见：[`测试规范.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`
|
||
|
||
---
|
||
|
||
## 11. 文档维护原则
|
||
|
||
- 本文档仅记录**跨模块共识**与**模块索引**，不展开模块细节
|
||
- 模块技术方案在子文档中维护，并通过 §8 表格回链
|
||
- API 契约总则在 `API_CONTRACT.md` 维护；模块文档只做模块特化，不得覆盖全局契约
|
||
- 任何技术栈变更（替换组件、升级主版本、新增外部服务）须同步更新本文档 §2、§5、§6
|
||
- 新增模块时，先在 §4 目录结构补位，再在 §8 索引登记子文档
|
||
- 涉及跨模块规则、接口口径、测试治理、范围边界的决策，必须先写入 `ADR.md`（新增 accepted 记录）再改 TECH_STACK/PRD/DATA_MODEL/TEST_CASES
|
||
- 若已有决策被替代，必须在 `ADR.md` 新增 superseded 记录并显式关联新 ADR；禁止静默改文档覆盖历史
|
||
- 提交 PR 时，若变更命中上述决策域，必须在描述中附 ADR ID（如 `ADR-20260430-011`）
|
||
- 测试规范变更须同步更新 §10 关键结论，完整细节在 [`测试规范.md`](./测试规范.md) 中维护
|
||
- 15 章节统一模板发生变更时，须先更新 §9 标准章节骨架，再同步各模块文档
|
||
|
||
---
|
||
|
||
## 12. Celery 多租户规范（M-12）
|
||
|
||
> **For AI assistants**: Every Celery task that touches tenant data MUST use the `@tenant_task` decorator defined here. No exceptions.
|
||
|
||
### 12.1 背景与风险
|
||
|
||
多模块技术方案均声明 Celery 任务签名带 `tenant_schema_name: str`，但 **缺乏统一封装**。
|
||
Celery worker 复用进程池，相邻任务若未正确切换 `search_path`，会产生 **跨租户脏读/脏写**，且不报错。
|
||
|
||
### 12.2 `@tenant_task` 装饰器规范
|
||
|
||
位置：`core/celery_utils.py`（由架构师统一提供，禁止各模块自己实现）
|
||
|
||
```python
|
||
# core/celery_utils.py
|
||
import functools
|
||
import structlog
|
||
from django_tenants.utils import schema_context
|
||
from celery import current_task
|
||
|
||
logger = structlog.get_logger(__name__)
|
||
|
||
def tenant_task(schema_arg: str = "tenant_schema_name"):
|
||
"""
|
||
装饰器：在 Celery 任务执行前自动切换租户 Schema，结束/异常后还原为 public。
|
||
|
||
使用方式：
|
||
@shared_task
|
||
@tenant_task(schema_arg="tenant_schema_name")
|
||
def export_properties(tenant_schema_name: str, ...):
|
||
... # 此处 search_path 已切换到目标 schema
|
||
"""
|
||
def decorator(func):
|
||
@functools.wraps(func)
|
||
def wrapper(*args, **kwargs):
|
||
schema = kwargs.get(schema_arg)
|
||
if not schema:
|
||
# 位置参数兼容：尝试从 args 中读取（按函数签名顺序）
|
||
import inspect
|
||
sig = inspect.signature(func)
|
||
params = list(sig.parameters.keys())
|
||
if schema_arg in params:
|
||
idx = params.index(schema_arg)
|
||
schema = args[idx] if idx < len(args) else None
|
||
if not schema:
|
||
raise ValueError(
|
||
f"[tenant_task] '{schema_arg}' 参数缺失，任务 {func.__name__} 拒绝执行"
|
||
)
|
||
log = logger.bind(task=func.__name__, task_id=current_task.request.id, schema=schema)
|
||
log.info("tenant_task.start")
|
||
try:
|
||
with schema_context(schema):
|
||
result = func(*args, **kwargs)
|
||
log.info("tenant_task.success")
|
||
return result
|
||
except Exception as exc:
|
||
log.error("tenant_task.error", exc=str(exc))
|
||
raise
|
||
return wrapper
|
||
return decorator
|
||
```
|
||
|
||
### 12.3 强制约束
|
||
|
||
| 约束 | 说明 |
|
||
|---|---|
|
||
| **所有业务 Celery 任务** 必须使用 `@tenant_task` | 包括导出、图片处理、智能配房、分区维护任务 |
|
||
| 任务签名 **必须含 `tenant_schema_name: str`** 形参 | 位置或关键字均可，`schema_arg` 参数可自定义名称 |
|
||
| 装饰器顺序：先 `@shared_task`，后 `@tenant_task` | 确保 Celery 正常注册任务名 |
|
||
| **禁止** 在任务内部手写 `connection.set_schema(...)` | 统一走装饰器，禁止散落手写 |
|
||
| 平台级无租户任务（如 `partition_maintenance_task`）| 直接 `with schema_context(target_schema):` 循环，不需要此装饰器 |
|
||
|
||
### 12.4 测试补充规范
|
||
|
||
- Celery 任务测试（`CELERY_TASK_ALWAYS_EAGER = True`）**必须**断言 `schema_context` 被以目标 schema 调用
|
||
- 可用 `unittest.mock.patch("core.celery_utils.schema_context")` 拦截，断言 `call_args`
|
||
- 反例测试：传入空 `tenant_schema_name` 时，任务必须抛出 `ValueError`，不得静默执行
|
||
|
||
---
|
||
|
||
## 13. R2 对象存储路径规范（M-13）
|
||
|
||
> **For AI assistants**: All R2 object keys MUST follow the template table below. Never invent custom prefixes.
|
||
|
||
### 13.1 路径模板表
|
||
|
||
| 资源类型 | Key 模板 | 访问方式 | TTL / 生命周期 |
|
||
|---|---|---|---|
|
||
| **客户端发布包** | `releases/system/{version}/{filename}` | public-read | 永久（不自动删除） |
|
||
| **租户备份** | `backups/{tenant_schema}/{record_id}.tar.gz` | signed URL only | 90 天自动删除 |
|
||
| **租户导出** | `exports/{tenant_schema}/{task_id}.zip` | signed URL 24h | 7 天自动删除 |
|
||
| **房源图片** | `media/{tenant_schema}/property/{property_id}/{photo_id}.{ext}` | signed URL | 永久（随物理删除清理） |
|
||
| **跟进附件** | `media/{tenant_schema}/follow/{log_id}/{idx}.{ext}` | signed URL | 90 天自动删除 |
|
||
| **客源附件** | `media/{tenant_schema}/client/{client_id}/{idx}.{ext}` | signed URL | 永久（随物理删除清理） |
|
||
| **审计归档** | `exports/audit/{task_id}.csv` | signed URL only | 2 年（合规保留） |
|
||
|
||
### 13.2 关键约束
|
||
|
||
- 路径中 **禁止使用 `tenant_id`（UUID）**，统一用 `tenant_schema_name`（字符串），便于跨环境迁移与 bucket policy 配置
|
||
- `{ext}` 统一小写（`jpg` / `png` / `webp`），禁止 `.JPG`
|
||
- 文件名仅用 UUID / 整数索引，**禁止使用原始文件名**（防路径注入）
|
||
- Signed URL 生成统一通过 `core/storage.py` 的 `generate_presigned_url(key, expires_in)` 封装
|
||
|
||
### 13.3 Bucket Policy 摘要
|
||
|
||
| Prefix | Policy | 说明 |
|
||
|---|---|---|
|
||
| `releases/system/` | public-read | 客户端更新包，CDN 加速 |
|
||
| `media/` | 无公开读，仅 signed | 所有租户媒体文件必须签名访问 |
|
||
| `backups/` | 无公开读，仅 signed | 备份包，严禁公开 |
|
||
| `exports/` | 无公开读，仅 signed | 导出包，签名 URL 有效期按上表 |
|
||
|
||
### 13.4 生命周期规则（R2 Object Lifecycle）
|
||
|
||
在 Cloudflare R2 控制台/API 配置以下规则：
|
||
|
||
```
|
||
Rule 1: backups/ prefix → Delete after 90 days
|
||
Rule 2: exports/{tenant}/ → Delete after 7 days
|
||
Rule 3: follow/ in media/ → Delete after 90 days (与 follow_logs 分区归档对齐)
|
||
Rule 4: exports/audit/ → Delete after 730 days (2 年合规保留)
|
||
```
|
||
|
||
---
|
||
|
||
## 14. ORM 数据范围强制规范（M-14）
|
||
|
||
> **For AI assistants**: Never use `Model.objects.filter(...)` directly in views or services. Always go through `scoped(staff)`.
|
||
|
||
### 14.1 背景
|
||
|
||
`DATA_MODEL/DATA_MODEL_PERMISSION.md` 已实现 `ScopeQueryBuilder`，但未强制约束使用入口。
|
||
模块技术方案 view 示例直接使用 `Property.objects.filter(...)`，可绕过权限控制。
|
||
|
||
### 14.2 强制规范
|
||
|
||
**所有业务 Model 必须暴露 `scoped(staff)` 入口，隐藏 `objects` Manager。**
|
||
|
||
```python
|
||
# core/models/scoped.py
|
||
from django.db import models
|
||
|
||
class ScopedManager(models.Manager):
|
||
"""
|
||
业务 Model 统一 Manager。
|
||
直接调用 Model.objects 将报错，强制使用 Model.scoped(staff)。
|
||
"""
|
||
def get_queryset(self):
|
||
raise RuntimeError(
|
||
f"[ScopedManager] 禁止直接调用 {self.model.__name__}.objects。"
|
||
f"请使用 {self.model.__name__}.scoped(staff) 经权限范围过滤。"
|
||
)
|
||
|
||
def scoped(self, staff):
|
||
"""
|
||
返回经 ScopeQueryBuilder 过滤后的 QuerySet。
|
||
staff: 当前登录员工实例（含角色、org_unit、权限范围）
|
||
"""
|
||
from apps.permission.scope import ScopeQueryBuilder
|
||
return ScopeQueryBuilder(staff).apply(super().get_queryset())
|
||
|
||
|
||
class ScopedModel(models.Model):
|
||
"""
|
||
所有业务 Model 继承此基类（而非 models.Model）。
|
||
"""
|
||
objects = ScopedManager()
|
||
|
||
class Meta:
|
||
abstract = True
|
||
```
|
||
|
||
### 14.3 豁免场景
|
||
|
||
| 场景 | 豁免条件 | 写法 |
|
||
|---|---|---|
|
||
| 系统/平台级操作（如分区维护） | 无租户身份，有明确运维场景 | `Model._default_manager.filter(...)` + 代码注释说明 |
|
||
| 迁移脚本 / seed factory | `RunPython` 或测试工厂 | `Model._default_manager.all()` |
|
||
| 测试内部 assert | 纯验证数据存在，非业务查询 | `Model._default_manager.get(pk=...)` |
|
||
|
||
### 14.4 Lint 规则（pre-commit）
|
||
|
||
在 `.pre-commit-config.yaml` 增加以下规则，阻断直接 `objects` 调用：
|
||
|
||
```yaml
|
||
- repo: local
|
||
hooks:
|
||
- id: no-raw-objects
|
||
name: "禁止直接使用 Model.objects（业务代码）"
|
||
language: pygrep
|
||
entry: '(?<!_default_manager)\.\bObjects\b|(?<!\._default_manager)\.objects\.(filter|all|get|exclude|create|update|delete)\b'
|
||
files: ^apps/.*\.py$
|
||
exclude: (tests/|migrations/|factories/)
|
||
types: [python]
|
||
```
|
||
|
||
### 14.5 权限边界测试矩阵
|
||
|
||
每个受权限保护的 Model，集成测试必须覆盖以下 3 case：
|
||
|
||
| Case | 说明 | 预期结果 |
|
||
|---|---|---|
|
||
| own | 员工查自己负责的数据 | 返回数据 ✅ |
|
||
| department | 店长查本部门数据 | 按角色返回 ✅ |
|
||
| cross_department_denied | 普通员工跨部门查询 | 空集或 403 ✅ |
|