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

Sync: add infrastructure as code notes

Browse Source
This commit is contained in:
weishen
2026-04-24 19:58:02 +08:00
parent cc23df1883
commit e4f6f463cb
29 changed files with 2344 additions and 155 deletions
Download Patch File Download Diff File Expand all files Collapse all files

119
Project/fonrey/DATA_MODEL/DATA_MODEL.md
View File

@@ -1,8 +1,8 @@
# Fonrey 房产经纪管理系统 — DATA MODEL 设计文档
> **作者**: Backend Architect
> **版本**: v1.0
> **日期**: 2026-04-24
> **版本**: v1.3
> **日期**: 2026-04-24（v1.1 修复 S1/S2/S4；v1.2 扩展 public schema；v1.3 §三 DDL 迁至 DATA_MODEL_PUBLIC.md，本文改为索引）
> **技术栈**: Django 4.x + PostgreSQL + django-tenants + Redis
> **设计目标**: 支撑 89,000+ 房源、多租户隔离、sub-100ms 查询、合规审计
@@ -13,18 +13,28 @@
### 1.1 多租户策略：Schema-per-Tenant
```
┌─────────────────────────────────────────────────────────────┐
│ PostgreSQL Instance │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ public schema│ │tenant_abc │ │tenant_xyz │ │
│ │ (shared) │ │ schema │ │ schema │ │
│ │ │ │ │ │ │ │
│ │ - tenants │ │ - properties │ │ - properties │ │
│ │ - domains │ │ - clients │ │ - clients │ │
│ │ │ │ - complexes │ │ - complexes │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────────┐
│ PostgreSQL Instance │
│ │
│ ┌─────────────────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ public schema │ │ tenant_abc │ │ tenant_xyz │ │
│ │ (平台运营层) │ │ schema │ │ schema │ │
│ │ │ │ │ │ │ │
│ │ - tenants │ │ - properties │ │ - properties │ │
│ │ - domains │ │ - clients │ │ - clients │ │
│ │ - tenant_status_logs │ │ - complexes │ │ - complexes │ │
│ │ - platform_admins │ │ - staff │ │ - staff │ │
│ │ - admin_mfa_devices │ │ - org_units │ │ - org_units │ │
│ │ - admin_sessions │ │ - ... │ │ - ... │ │
│ │ - ip_whitelist │ └──────────────┘ └──────────────┘ │
│ │ - platform_audit_logs │ │
│ │ - backup_schedules │ │
│ │ - backup_records │ │
│ │ - export_tasks │ │
│ │ - system_versions │ │
│ │ - upgrade_events │ │
│ └─────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────┘
```
**选型理由**：
@@ -76,9 +86,28 @@
### 核心领域对象
#### Public Schema（平台运营层）
| 领域对象 | 表 | 业务说明 |
|----------|-----|----------|
| **Tenant（租户）** | `public.tenants` | 每家房产经纪公司一条记录，含状态机（creating/active/suspended/pending_delete/deleted）、套餐、联系人 |
| **Domain（域名）** | `public.domains` | 子域名↔租户映射，支持多域名绑定，子域名创建后不可修改 |
| **TenantStatusLog** | `public.tenant_status_logs` | 租户状态变更不可变审计（append-only） |
| **PlatformAdmin** | `public.platform_admins` | 平台管理员账号，3 种角色：超级管理员/运营人员/只读审计员 |
| **AdminMfaDevice** | `public.admin_mfa_devices` | 管理员 TOTP 设备（强制启用） |
| **AdminSession** | `public.admin_sessions` | 登录会话（30 分钟超时，支持强制登出） |
| **IpWhitelist** | `public.ip_whitelist` | 管理控制台 CIDR 白名单 |
| **PlatformAuditLog** | `public.platform_audit_logs` | 所有写操作+高危操作审计（append-only，建议月度分区） |
| **BackupSchedule** | `public.backup_schedules` | 全局/租户级定时备份计划（频率/保留数/存储目标） |
| **BackupRecord** | `public.backup_records` | 备份任务执行记录（自动/手动/升级前/恢复前） |
| **ExportTask** | `public.export_tasks` | 数据导出异步任务（CSV/JSON/SQL Dump，24h 下载链接） |
| **SystemVersion** | `public.system_versions` | 平台版本历史，唯一 current 版本约束 |
| **UpgradeEvent** | `public.upgrade_events` | 升级/回滚事件，含灰度租户维度进度快照 |
#### Tenant Schema（租户业务层）
| 领域对象 | 表/子文档 | 业务说明 |
|----------|-----------|----------|
| **Tenant（租户）** | `public.tenants` | 每家房产经纪公司对应一个租户，数据完全隔离（Schema-per-Tenant） |
| **OrgUnit（组织架构）** | `org_units` → [DATA_MODEL_ORG.md](./DATA_MODEL_ORG.md) | 树形组织架构（总部/区域/城市/大区/分公司/门店/团队/虚拟团队），物化路径存储，支持权限继承 |
| **Staff（员工）** | `staff` → [DATA_MODEL_ORG.md](./DATA_MODEL_ORG.md) | 经纪人/店长/经理，绑定组织节点，手机号加密存储，与账号（登录）分离 |
| **District（城区）** | `districts` → [DATA_MODEL_COMPLEX.md](./DATA_MODEL_COMPLEX.md) | 行政区划，如「静安区」，是区域体系的顶层节点 |
@@ -114,6 +143,7 @@ OrgUnit (组织架构)
| 子文档 | 覆盖模块 | 状态 |
|--------|----------|------|
| [DATA_MODEL_PUBLIC.md](./DATA_MODEL_PUBLIC.md) | Public schema 平台运营层（tenants, domains, platform_admins, admin_sessions, audit_logs, backup, export, upgrade 共 13 张表） | ✅ 完成 |
| [DATA_MODEL_ORG.md](./DATA_MODEL_ORG.md) | 组织人事（org_units, staff, 异动/奖惩/教育/家庭等） | ✅ 完成 |
| [DATA_MODEL_COMPLEX.md](./DATA_MODEL_COMPLEX.md) | 楼盘/区域（districts, business_areas, complexes, buildings, room_units, schools 等） | ✅ 完成 |
| [DATA_MODEL_CLIENT.md](./DATA_MODEL_CLIENT.md) | 客源管理（clients, requirements, follow_logs, viewings, matches 等） | ✅ 完成 |
@@ -123,42 +153,41 @@ OrgUnit (组织架构)
## 三、公共 Schema（Shared / Public）
> **权威源**：完整 DDL 已迁至 [`DATA_MODEL_PUBLIC.md`](./DATA_MODEL_PUBLIC.md)，本节仅保留摘要索引。
> **覆盖范围**：`public` schema 存储平台运营层数据——租户注册、管理员账号、审计日志、备份/导出任务、版本升级记录（共 13 张表）。
> **设计依据**：系统管理模块 PRD（`PRD/系统管理/系统管理模块PRD.md`）。
```sql
-- ============================================================
-- 文件: shared_schema.sql
-- 用途: django-tenants 公共 Schema，存放租户注册信息
-- ============================================================
### 表清单（开发以 DATA_MODEL_PUBLIC.md 为准）
-- 租户表（每家房产公司一条记录）
CREATE TABLE public.tenants (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
schema_name VARCHAR(63) UNIQUE NOT NULL, -- PG schema 名，最长 63 字符
name VARCHAR(255) NOT NULL, -- 公司名称
short_name VARCHAR(100), -- 简称/品牌名
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
is_active BOOLEAN NOT NULL DEFAULT TRUE,
paid_until DATE, -- 订阅到期日
on_trial BOOLEAN NOT NULL DEFAULT TRUE,
extra JSONB NOT NULL DEFAULT '{}' -- 预留扩展字段
);
| 表名 | 说明 | 节 |
|------|------|----|
| `public.tenants` | 租户主表（django-tenants 核心，状态机 6 态） | §2.1 |
| `public.domains` | 域名↔租户映射（支持多域名，子域名不可修改） | §2.1 |
| `public.tenant_status_logs` | 租户状态变更不可变审计日志（append-only） | §2.1 |
| `public.platform_admins` | 平台管理员账号（super_admin/ops_operator/read_only_auditor） | §2.2 |
| `public.admin_mfa_devices` | 管理员 TOTP MFA 设备（强制启用） | §2.2 |
| `public.admin_sessions` | 管理员登录会话（30 min 滚动超时，支持强制登出） | §2.2 |
| `public.ip_whitelist` | 管理控制台 CIDR 白名单 | §2.2 |
| `public.platform_audit_logs` | 所有写操作+高危操作审计（append-only，建议月度分区） | §2.3 |
| `public.backup_schedules` | 全局/租户级定时备份计划（NULL tenant_id = 全局默认） | §2.4 |
| `public.backup_records` | 备份任务执行记录（auto/manual/pre_upgrade/pre_restore） | §2.4 |
| `public.export_tasks` | 数据导出异步任务（CSV/JSON/SQL Dump，24h 下载链接） | §2.4 |
| `public.system_versions` | 平台版本历史，部分唯一索引保证唯一 current | §2.5 |
| `public.upgrade_events` | 升级/回滚事件，`tenant_progress` JSONB 快照各租户状态 | §2.5 |
-- 域名映射表（支持多域名绑定一个租户）
CREATE TABLE public.domains (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
domain VARCHAR(253) UNIQUE NOT NULL, -- 含子域名的完整域名
tenant_id UUID NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
is_primary BOOLEAN NOT NULL DEFAULT FALSE,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_domains_tenant ON public.domains(tenant_id);
CREATE INDEX idx_domains_primary ON public.domains(tenant_id) WHERE is_primary = TRUE;
```
**关键约束提示**：
- `tenant_status_logs` / `platform_audit_logs` **无 deleted_at**，禁止 UPDATE/DELETE，append-only
- `public.tenants.schema_name` 创建后**不可修改**
- `public.tenants` 不再使用 `is_active` boolean，改用 6 态 `status` 枚举
- `platform_admins` 与租户 `staff` **完全独立**，不共享 auth 系统
- `system_versions` 通过部分唯一索引确保全局只有一个 `status='current'`
---
<!-- §三 DDL 已迁至 DATA_MODEL_PUBLIC.md v1.0（2026-04-24） -->
## 四、租户 Schema（Tenant Schema）
以下所有表均在每个租户的独立 Schema 内创建。