1357 lines
57 KiB
Markdown
1357 lines
57 KiB
Markdown
# Fonrey 房产经纪管理系统 — DATA MODEL 设计文档
|
||
|
||
> **作者**: Backend Architect
|
||
> **版本**: v1.0
|
||
> **日期**: 2026-04-24
|
||
> **技术栈**: Django 4.x + PostgreSQL + django-tenants + Redis
|
||
> **设计目标**: 支撑 89,000+ 房源、多租户隔离、sub-100ms 查询、合规审计
|
||
|
||
---
|
||
|
||
## 一、架构决策总览 (Architecture Decision Records)
|
||
|
||
### 1.1 多租户策略：Schema-per-Tenant
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ PostgreSQL Instance │
|
||
│ │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ public schema│ │tenant_abc │ │tenant_xyz │ │
|
||
│ │ (shared) │ │ schema │ │ schema │ │
|
||
│ │ │ │ │ │ │ │
|
||
│ │ - tenants │ │ - properties │ │ - properties │ │
|
||
│ │ - domains │ │ - clients │ │ - clients │ │
|
||
│ │ │ │ - complexes │ │ - complexes │ │
|
||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**选型理由**：
|
||
- `django-tenants` 的 Schema 隔离提供最强的数据安全边界
|
||
- 房产经纪公司之间数据绝对不能互通（合规要求）
|
||
- 每个 Schema 独立索引，避免全局锁竞争
|
||
- 支持按租户独立备份/恢复
|
||
|
||
### 1.2 核心领域模型关系图
|
||
|
||
```
|
||
[区域/商圈]──────────────────────────────┐
|
||
│ │
|
||
[学校管理] │
|
||
│ ▼
|
||
[楼盘/小区] ──── [楼栋] ─────────► [房源] ◄──── [挂牌历史]
|
||
│ │
|
||
│ ┌────────┼────────┐
|
||
│ │ │ │
|
||
│ [联系人] [跟进日志] [维护完成度]
|
||
│ │ │
|
||
│ ┌─────┘ ┌────┴──────┐
|
||
│ │ │ │
|
||
│ [电话查看] [钥匙] [委托] [实勘]
|
||
│
|
||
[客源] ──── [配对记录] ──── [带看记录]
|
||
│
|
||
[员工/组织] ──── [权限]
|
||
```
|
||
|
||
### 1.3 关键设计原则
|
||
|
||
| 原则 | 决策 |
|
||
| ----- | -------------------------------------- |
|
||
| 主键类型 | `UUID v4`（跨环境安全，避免枚举攻击） |
|
||
| 软删除 | 所有核心表含 `deleted_at`（历史可追溯） |
|
||
| 时间戳 | 全部使用 `TIMESTAMPTZ`（含时区） |
|
||
| 手机号存储 | AES-256-GCM 加密存储，建立 SHA-256 哈希索引 |
|
||
| 审计字段 | `created_by`, `updated_by` 全表覆盖 |
|
||
| 枚举值 | 业务枚举用 `VARCHAR` + CHECK，系统枚举用 lookup 表 |
|
||
| 大文本 | `TEXT` 类型，不设长度（PG 内部优化） |
|
||
| 金额 | `NUMERIC(12,2)` 万元精度，避免浮点误差 |
|
||
|
||
---
|
||
|
||
## 二、领域概览（Domain Overview）
|
||
|
||
本节用业务语言描述系统的核心领域对象及其关系，作为各子模块数据模型的导读。
|
||
|
||
### 核心领域对象
|
||
|
||
| 领域对象 | 表/子文档 | 业务说明 |
|
||
|----------|-----------|----------|
|
||
| **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) | 行政区划，如「静安区」，是区域体系的顶层节点 |
|
||
| **BusinessArea（商圈）** | `business_areas` → [DATA_MODEL_COMPLEX.md](./DATA_MODEL_COMPLEX.md) | 商圈/板块，从属于城区，一个楼盘可归属多个商圈 |
|
||
| **School（学校）** | `schools` → [DATA_MODEL_COMPLEX.md](./DATA_MODEL_COMPLEX.md) | 对口学校数据库，是买家购房决策的核心参考，与楼盘多对多关联 |
|
||
| **Complex（楼盘/小区）** | `complexes` → [DATA_MODEL_COMPLEX.md](./DATA_MODEL_COMPLEX.md) | 房源录入的基础底座，维护楼盘标准名称/坐标/锁定状态/别名等 |
|
||
| **Building（楼栋/单元）** | `buildings` → [DATA_MODEL_COMPLEX.md](./DATA_MODEL_COMPLEX.md) | 楼盘下的物理楼栋，区分标准结构与非标结构 |
|
||
| **RoomUnit（房号）** | `room_units` → [DATA_MODEL_COMPLEX.md](./DATA_MODEL_COMPLEX.md) | 楼层+房间号，房源定位的最细粒度 |
|
||
| **Property（房源）** | `properties` → §3.3 | 系统核心表，每套二手房源的完整档案，支持出售/出租/出售兼出租三态 |
|
||
| **Client（客源）** | `clients` → [DATA_MODEL_CLIENT.md](./DATA_MODEL_CLIENT.md) | 买家/租客档案，分私客/公客/成交客，含活跃度评分与自动公客转换机制 |
|
||
| **Viewing（带看）** | `client_viewings` → [DATA_MODEL_CLIENT.md](./DATA_MODEL_CLIENT.md) | 经纪人带客户看房的完整记录 |
|
||
| **Match（配对）** | `client_property_matches` → [DATA_MODEL_CLIENT.md](./DATA_MODEL_CLIENT.md) | 系统/人工推荐的客源↔房源配对 |
|
||
|
||
### 领域关系快速导航
|
||
|
||
```
|
||
District (城区)
|
||
└─ BusinessArea (商圈)
|
||
└─ Complex (楼盘) ─── School (对口学校)
|
||
├─ Building (楼栋)
|
||
│ └─ RoomUnit (房号)
|
||
└─ Property (房源)
|
||
├─ PropertyContact (联系人/委托方)
|
||
├─ FollowLog (跟进日志)
|
||
├─ Viewing (带看记录) ──── Client (客源)
|
||
└─ Match (配对记录) ──────┘
|
||
|
||
OrgUnit (组织架构)
|
||
└─ Staff (员工/经纪人) ─── Property / Client / Viewing / Match
|
||
```
|
||
|
||
### 子文档索引
|
||
|
||
| 子文档 | 覆盖模块 | 状态 |
|
||
|--------|----------|------|
|
||
| [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 等） | ✅ 完成 |
|
||
| 本文档 §3.3–§3.16 | 房源核心（properties 及配套 12 张表）、系统设置 | ✅ 完成 |
|
||
|
||
---
|
||
|
||
## 三、公共 Schema（Shared / Public）
|
||
|
||
|
||
```sql
|
||
-- ============================================================
|
||
-- 文件: shared_schema.sql
|
||
-- 用途: django-tenants 公共 Schema，存放租户注册信息
|
||
-- ============================================================
|
||
|
||
-- 租户表（每家房产公司一条记录）
|
||
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 '{}' -- 预留扩展字段
|
||
);
|
||
|
||
-- 域名映射表（支持多域名绑定一个租户）
|
||
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;
|
||
```
|
||
|
||
---
|
||
|
||
## 四、租户 Schema（Tenant Schema）
|
||
|
||
以下所有表均在每个租户的独立 Schema 内创建。
|
||
|
||
---
|
||
|
||
### 3.1 组织人事模块（Organization & HR）
|
||
|
||
> **详细模型** → 见 [`DATA_MODEL_ORG.md`](./DATA_MODEL_ORG.md)
|
||
> 该文件为权威定义，包含完整字段、枚举、查询模式和禁止操作。
|
||
|
||
**核心表概览**（开发时以 DATA_MODEL_ORG.md 为准）：
|
||
|
||
| 表名 | 说明 |
|
||
|------|------|
|
||
| `org_units` | 组织树节点（公司/事业部/大区/区域/片区/门店/店组/职能），物化路径树 |
|
||
| `staff` | 员工主表，含加密手机号、角色、在职状态、Django auth 绑定 |
|
||
| `staff_personal_info` | 员工个人信息扩展（证件、学历、婚育等，1:1） |
|
||
| `staff_transfer_logs` | 人事异动不可变审计日志（入职/调动/离职/复职等） |
|
||
| `staff_reward_punish` | 奖惩记录 |
|
||
| `staff_work_experiences` | 工作经历 |
|
||
| `staff_educations` | 教育经历 |
|
||
| `staff_trainings` | 培训经历 |
|
||
| `staff_family_members` | 家庭成员 |
|
||
| `staff_accounts` | 第三方平台账号绑定（58安居客/中国网络经纪人等） |
|
||
|
||
**关键约束提示**：
|
||
- `staff.phone_enc` AES-256-GCM 加密，`staff.phone_hash` SHA-256 用于唯一索引
|
||
- `staff_transfer_logs` **无 deleted_at**，不可删除
|
||
- `org_units` 路径查询：`WHERE path LIKE '/root/{target_id}/%'`
|
||
- 员工离职：`status = 'resigned'` + `deleted_at` 软删除，记录永久保留
|
||
|
||
---
|
||
|
||
### 3.2 区域与楼盘模块（Region & Complex Management）
|
||
|
||
> **详细模型** → 见 [`DATA_MODEL_COMPLEX.md`](./DATA_MODEL_COMPLEX.md)
|
||
> 本节仅作概览，开发时以 DATA_MODEL_COMPLEX.md 为权威定义。
|
||
|
||
**核心表概览**（开发时以 DATA_MODEL_COMPLEX.md 为准）：
|
||
|
||
| 表名 | 说明 | 关键字段 |
|
||
|------|------|----------|
|
||
| `districts` | 城区/行政区 | `city`, `name`, `short_name`, `sort_order` |
|
||
| `business_areas` | 商圈/板块（从属于城区） | `district_id`, `name`, `latitude`, `longitude` |
|
||
| `metro_lines` | 地铁线路 | `city`, `name`, `color` |
|
||
| `metro_stations` | 地铁站点 | `metro_line_id`, `name`, `latitude`, `longitude` |
|
||
| `schools` | 学校（对口学区） | `district_id`, `name`, `type`, `nature`, `level` |
|
||
| `complexes` | 楼盘/小区（房源底座） | `name`, `district_id`, `address`, `latitude/longitude`, `lock_*`, `search_vector` |
|
||
| `complex_aliases` | 楼盘别名（含系统别名/用户自定义别名） | `complex_id`, `alias`, `is_system` |
|
||
| `complex_business_areas` | 楼盘↔商圈多对多（含主商圈标识） | `complex_id`, `business_area_id`, `is_primary` |
|
||
| `complex_schools` | 楼盘↔学校关联（含学区类型） | `complex_id`, `school_id`, `zone_type` |
|
||
| `complex_metro_stations` | 楼盘↔地铁站关联（含步行距离） | `complex_id`, `station_id`, `distance_meters` |
|
||
| `buildings` | 楼栋/单元 | `complex_id`, `name`, `is_standard`, `total_floors` |
|
||
| `room_units` | 房号/结构单元（楼层+房间号） | `building_id`, `floor`, `room_no`, `is_standard` |
|
||
| `complex_photos` | 楼盘照片（楼盘图/户型图/VR） | `complex_id`, `category`, `file_key`, `is_cover` |
|
||
| `complex_attachments` | 楼盘附件 | `complex_id`, `file_key`, `file_name` |
|
||
| `complex_price_trends` | 楼盘价格走势（月度） | `complex_id`, `record_month`, `avg_unit_price` |
|
||
|
||
---
|
||
|
||
### 3.3 房源核心模块（Property Core）
|
||
|
||
```sql
|
||
-- ============================================================
|
||
-- 房源主表：系统最核心的表，全部筛选/排序/搜索围绕此表展开
|
||
-- 设计重点：89,000+ 数据量，复合索引策略，分区预留
|
||
-- ============================================================
|
||
|
||
CREATE TABLE properties (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
|
||
-- ── 基础分类 ──
|
||
property_type VARCHAR(20) NOT NULL
|
||
CHECK (property_type IN ('residential','villa','commercial_residential',
|
||
'shop','office','other')),
|
||
-- residential=住宅, villa=别墅, commercial_residential=商住,
|
||
-- shop=商铺, office=写字楼, other=其他
|
||
|
||
-- ── 交易状态 ──
|
||
status VARCHAR(20) NOT NULL DEFAULT 'for_sale'
|
||
CHECK (status IN ('for_sale','for_rent','for_sale_rent',
|
||
'suspended','sold_elsewhere','rented_elsewhere',
|
||
'sold','unlisted')),
|
||
-- for_sale=出售, for_rent=出租, for_sale_rent=租售,
|
||
-- suspended=暂缓, sold_elsewhere=他售, rented_elsewhere=他租,
|
||
-- sold=成交, unlisted=未挂牌
|
||
|
||
-- ── 流通属性 ──
|
||
attribute VARCHAR(20) NOT NULL DEFAULT 'public'
|
||
CHECK (attribute IN ('public','private','special','sealed')),
|
||
-- public=公盘, private=私盘, special=特盘, sealed=封盘
|
||
private_reason TEXT, -- 私盘/封盘必填说明
|
||
|
||
-- ── 位置信息 ──
|
||
complex_id UUID NOT NULL REFERENCES complexes(id) ON DELETE RESTRICT,
|
||
building_id UUID REFERENCES buildings(id) ON DELETE SET NULL,
|
||
block_no VARCHAR(30), -- 栋/幢/弄号
|
||
unit_no VARCHAR(30), -- 单元号
|
||
room_no VARCHAR(30), -- 房号/门牌号
|
||
floor SMALLINT NOT NULL, -- 所在楼层
|
||
total_floors SMALLINT NOT NULL, -- 总楼层
|
||
CONSTRAINT chk_floor CHECK (floor > 0 AND floor <= total_floors),
|
||
|
||
-- ── 户型 ──
|
||
bedroom_count SMALLINT NOT NULL DEFAULT 0, -- 室
|
||
living_room_count SMALLINT NOT NULL DEFAULT 0, -- 厅
|
||
bathroom_count SMALLINT NOT NULL DEFAULT 0, -- 卫
|
||
kitchen_count SMALLINT NOT NULL DEFAULT 0, -- 厨
|
||
balcony_count SMALLINT NOT NULL DEFAULT 0, -- 阳台数
|
||
|
||
-- ── 面积 ──
|
||
area NUMERIC(8,2) NOT NULL, -- 建筑面积 m²
|
||
inner_area NUMERIC(8,2), -- 套内面积 m²（编辑时填写）
|
||
|
||
-- ── 价格 ──
|
||
sale_price NUMERIC(12,2), -- 挂牌售价（万元）
|
||
sale_bottom_price NUMERIC(12,2), -- 售底价（万元，内部可见）
|
||
sale_record_price NUMERIC(12,2), -- 备案/核验价（万元）
|
||
rent_price NUMERIC(10,2), -- 挂牌租价（元/月）
|
||
|
||
-- ── 基础物理属性 ──
|
||
orientation VARCHAR(10)
|
||
CHECK (orientation IN ('east','south','west','north',
|
||
'southeast','northeast','east_west',
|
||
'south_north','northwest','southwest')),
|
||
decoration VARCHAR(10)
|
||
CHECK (decoration IN ('rough','plain','simple','medium',
|
||
'fine','luxury')),
|
||
-- rough=毛坯, plain=清水, simple=简装, medium=中装, fine=精装, luxury=豪装
|
||
|
||
has_elevator BOOLEAN,
|
||
built_year SMALLINT,
|
||
|
||
-- ── 用途 ──
|
||
usage_type VARCHAR(30), -- 住宅/商住/商业/普通住宅/花园洋房 等
|
||
usage_subtype VARCHAR(30), -- 细分用途
|
||
|
||
-- ── 商铺专属 ──
|
||
shop_frontage NUMERIC(6,2), -- 开间（米）
|
||
shop_depth NUMERIC(6,2), -- 进深（米）
|
||
shop_height NUMERIC(6,2), -- 层高（米）
|
||
shop_location VARCHAR(20)
|
||
CHECK (shop_location IS NULL OR
|
||
shop_location IN ('street','mall','residential',
|
||
'ground_floor','complex')),
|
||
|
||
-- ── 房屋状态 ──
|
||
house_status VARCHAR(20)
|
||
CHECK (house_status IN ('owner_occupied','vacant',
|
||
'tenant_occupied','unknown')),
|
||
viewing_time VARCHAR(20)
|
||
CHECK (viewing_time IN ('anytime','by_appointment','inconvenient')),
|
||
|
||
-- ── 等级与标签 ──
|
||
grade VARCHAR(5)
|
||
CHECK (grade IN ('A_urgent','A','B','C','D')),
|
||
-- A_urgent=A(急迫), A=A, B=B(较强), C=C(一般), D=D
|
||
|
||
-- ── 交易属性 ──
|
||
ownership_years VARCHAR(30), -- 房本年限：不满2年/满2年/满5年 等
|
||
ownership_years_detail VARCHAR(20), -- 满五/不满五
|
||
ownership_nature VARCHAR(20)
|
||
CHECK (ownership_nature IS NULL OR
|
||
ownership_nature IN ('commercial','reform_housing',
|
||
'collective','economic')),
|
||
-- commercial=商品房, reform_housing=房改房, collective=集资房, economic=经济适用房
|
||
is_only_house BOOLEAN, -- 唯一住房
|
||
payment_method VARCHAR(30)
|
||
CHECK (payment_method IS NULL OR
|
||
payment_method IN ('full','mortgage','installment','advance')),
|
||
tax_included VARCHAR(10)
|
||
CHECK (tax_included IS NULL OR
|
||
tax_included IN ('each_party','net','inclusive')),
|
||
has_mortgage BOOLEAN,
|
||
has_loan BOOLEAN,
|
||
has_seal BOOLEAN,
|
||
has_restriction BOOLEAN,
|
||
original_price NUMERIC(12,2), -- 原购价（万元）
|
||
sale_reason TEXT, -- 售房原因（最多200字）
|
||
|
||
-- ── 营销备注 ──
|
||
remarks TEXT, -- 房源备注（最多500字）
|
||
|
||
-- ── 相关方（冗余存储 UUID，完整信息查 staff 表）──
|
||
first_recorder_id UUID REFERENCES staff(id) ON DELETE SET NULL, -- 首录方
|
||
number_holder_id UUID REFERENCES staff(id) ON DELETE SET NULL, -- 号码方
|
||
seller_agent_id UUID REFERENCES staff(id) ON DELETE SET NULL, -- 出售方
|
||
buyer_agent_id UUID REFERENCES staff(id) ON DELETE SET NULL, -- 实买方
|
||
|
||
-- ── 来源 ──
|
||
source VARCHAR(50), -- 房源来源渠道（由运营维护枚举）
|
||
|
||
-- ── 维护完成度（冗余缓存，定期重算）──
|
||
completeness_score SMALLINT NOT NULL DEFAULT 0, -- 0-100 分
|
||
|
||
-- ── 时间轨迹 ──
|
||
listed_at TIMESTAMPTZ, -- 最近一次挂牌时间
|
||
last_followed_at TIMESTAMPTZ, -- 最后跟进时间（冗余，加速排序）
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
deleted_at TIMESTAMPTZ,
|
||
created_by UUID REFERENCES staff(id) ON DELETE SET NULL,
|
||
updated_by UUID REFERENCES staff(id) ON DELETE SET NULL,
|
||
|
||
-- ── 全文检索向量 ──
|
||
search_vector TSVECTOR
|
||
);
|
||
|
||
-- ── 索引策略（针对高频查询路径设计）──
|
||
|
||
-- 1. 最核心的列表页：按状态 + 属性 + 类型过滤
|
||
CREATE INDEX idx_properties_status_attr ON properties(status, attribute, property_type)
|
||
WHERE deleted_at IS NULL;
|
||
|
||
-- 2. 区域筛选（通过 complex 表 JOIN 优化）
|
||
CREATE INDEX idx_properties_complex ON properties(complex_id)
|
||
WHERE deleted_at IS NULL;
|
||
|
||
-- 3. 价格排序（出售最常用）
|
||
CREATE INDEX idx_properties_sale_price ON properties(sale_price DESC NULLS LAST)
|
||
WHERE deleted_at IS NULL AND status IN ('for_sale','for_sale_rent');
|
||
|
||
-- 4. 面积区间筛选
|
||
CREATE INDEX idx_properties_area ON properties(area)
|
||
WHERE deleted_at IS NULL;
|
||
|
||
-- 5. 挂牌日期倒序（最新挂牌）
|
||
CREATE INDEX idx_properties_listed_at ON properties(listed_at DESC NULLS LAST)
|
||
WHERE deleted_at IS NULL;
|
||
|
||
-- 6. 最后跟进日期（超时未跟进功能）
|
||
CREATE INDEX idx_properties_last_followed ON properties(last_followed_at DESC NULLS LAST)
|
||
WHERE deleted_at IS NULL;
|
||
|
||
-- 7. 户型筛选
|
||
CREATE INDEX idx_properties_bedroom ON properties(bedroom_count)
|
||
WHERE deleted_at IS NULL;
|
||
|
||
-- 8. 等级筛选
|
||
CREATE INDEX idx_properties_grade ON properties(grade)
|
||
WHERE deleted_at IS NULL;
|
||
|
||
-- 9. 完成度排序（引导补全信息）
|
||
CREATE INDEX idx_properties_completeness ON properties(completeness_score)
|
||
WHERE deleted_at IS NULL;
|
||
|
||
-- 10. 全文搜索
|
||
CREATE INDEX idx_properties_search ON properties USING gin(search_vector);
|
||
|
||
-- 11. 与我相关（相关方快速定位）
|
||
CREATE INDEX idx_properties_seller_agent ON properties(seller_agent_id)
|
||
WHERE deleted_at IS NULL;
|
||
CREATE INDEX idx_properties_number_holder ON properties(number_holder_id)
|
||
WHERE deleted_at IS NULL;
|
||
|
||
-- 12. 复合索引：列表默认排序（状态 + 挂牌时间）
|
||
CREATE INDEX idx_properties_list_default ON properties(status, listed_at DESC NULLS LAST)
|
||
WHERE deleted_at IS NULL;
|
||
```
|
||
|
||
---
|
||
|
||
### 3.4 房源联系人（Property Contacts）
|
||
|
||
```sql
|
||
-- ============================================================
|
||
-- 业主/联系人：手机号加密存储，哈希值支持重复检测
|
||
-- 安全要点：任何查看明文号码的行为均触发审计日志
|
||
-- ============================================================
|
||
|
||
CREATE TABLE property_contacts (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE,
|
||
|
||
name VARCHAR(50) NOT NULL,
|
||
gender VARCHAR(10) NOT NULL DEFAULT 'male'
|
||
CHECK (gender IN ('male','female')),
|
||
identity VARCHAR(20) NOT NULL DEFAULT 'contact'
|
||
CHECK (identity IN ('owner','contact','subletter',
|
||
'tenant','agent','corporate')),
|
||
-- owner=业主, contact=联系人, subletter=二房东, tenant=租客,
|
||
-- agent=代理人, corporate=企业法人
|
||
|
||
-- 手机号：加密存储 + 哈希索引（重复检测用）
|
||
phone_enc BYTEA NOT NULL, -- AES-256-GCM 加密
|
||
phone_hash VARCHAR(64) NOT NULL, -- SHA-256(phone) 用于去重查询
|
||
phone2_enc BYTEA,
|
||
phone2_hash VARCHAR(64),
|
||
|
||
wechat VARCHAR(100), -- 微信号（相对不敏感，可明文）
|
||
qq VARCHAR(20),
|
||
remarks TEXT,
|
||
|
||
-- 是否为号码方（关联审批流）
|
||
is_number_holder BOOLEAN NOT NULL DEFAULT FALSE,
|
||
number_holder_approved_at TIMESTAMPTZ, -- 审批通过时间
|
||
|
||
sort_order INTEGER NOT NULL DEFAULT 0,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
deleted_at TIMESTAMPTZ,
|
||
created_by UUID REFERENCES staff(id) ON DELETE SET NULL,
|
||
updated_by UUID REFERENCES staff(id) ON DELETE SET NULL
|
||
);
|
||
|
||
CREATE INDEX idx_contacts_property ON property_contacts(property_id)
|
||
WHERE deleted_at IS NULL;
|
||
|
||
-- 关键：手机号哈希全局索引（用于重复房源检测）
|
||
CREATE INDEX idx_contacts_phone_hash ON property_contacts(phone_hash)
|
||
WHERE deleted_at IS NULL;
|
||
CREATE INDEX idx_contacts_phone2_hash ON property_contacts(phone2_hash)
|
||
WHERE phone2_hash IS NOT NULL AND deleted_at IS NULL;
|
||
```
|
||
|
||
---
|
||
|
||
### 3.5 挂牌历史（Listing History）
|
||
|
||
```sql
|
||
-- ============================================================
|
||
-- 挂牌历史：记录房源每次上架的完整快照
|
||
-- 设计重点：不可删除（合规），仅追加
|
||
-- ============================================================
|
||
|
||
CREATE TABLE listing_histories (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE RESTRICT,
|
||
|
||
listing_type VARCHAR(20) NOT NULL
|
||
CHECK (listing_type IN ('for_sale','for_rent')),
|
||
status VARCHAR(20) NOT NULL DEFAULT 'active'
|
||
CHECK (status IN ('active','ended')),
|
||
|
||
-- 价格快照
|
||
sale_price NUMERIC(12,2),
|
||
rent_price NUMERIC(10,2),
|
||
sale_unit_price NUMERIC(10,2), -- 元/m²，计算字段
|
||
|
||
-- 交易信息快照
|
||
ownership_years VARCHAR(30),
|
||
is_only_house BOOLEAN,
|
||
tax_included VARCHAR(10),
|
||
sale_reason TEXT,
|
||
|
||
-- 经纪人快照
|
||
seller_agent_id UUID REFERENCES staff(id) ON DELETE SET NULL,
|
||
seller_agent_snapshot JSONB, -- 存储经纪人姓名+门店（防止变更后丢失）
|
||
|
||
started_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
ended_at TIMESTAMPTZ,
|
||
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
-- 注：无 deleted_at，此表记录不可删除
|
||
);
|
||
|
||
CREATE INDEX idx_listing_histories_property ON listing_histories(property_id);
|
||
CREATE INDEX idx_listing_histories_active ON listing_histories(property_id)
|
||
WHERE status = 'active';
|
||
```
|
||
|
||
---
|
||
|
||
### 3.6 调价记录（Price Change Log）
|
||
|
||
```sql
|
||
-- ============================================================
|
||
-- 调价记录：支持折线图展示，不可删除
|
||
-- ============================================================
|
||
|
||
CREATE TABLE price_changes (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE RESTRICT,
|
||
|
||
old_sale_price NUMERIC(12,2),
|
||
new_sale_price NUMERIC(12,2),
|
||
old_bottom_price NUMERIC(12,2),
|
||
new_bottom_price NUMERIC(12,2),
|
||
old_record_price NUMERIC(12,2),
|
||
new_record_price NUMERIC(12,2),
|
||
old_rent_price NUMERIC(10,2),
|
||
new_rent_price NUMERIC(10,2),
|
||
|
||
change_reason TEXT NOT NULL, -- 最多200字
|
||
changed_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
changed_by UUID NOT NULL REFERENCES staff(id) ON DELETE RESTRICT
|
||
);
|
||
|
||
CREATE INDEX idx_price_changes_property ON price_changes(property_id);
|
||
CREATE INDEX idx_price_changes_time ON price_changes(property_id, changed_at DESC);
|
||
```
|
||
|
||
---
|
||
|
||
### 3.7 跟进日志（Follow-up Logs）
|
||
|
||
```sql
|
||
-- ============================================================
|
||
-- 跟进日志：系统最高写入频率的表，按 property_id 分区预留
|
||
-- 6 种类型：写入跟进/修改跟进/敏感信息跟进/敏感信息查看/其他跟进/系统日志
|
||
-- ============================================================
|
||
|
||
CREATE TABLE follow_logs (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE,
|
||
|
||
log_type VARCHAR(30) NOT NULL
|
||
CHECK (log_type IN ('written','modified','sensitive_op',
|
||
'sensitive_view','other','system')),
|
||
-- written=写入跟进（经纪人主动写）
|
||
-- modified=修改跟进（字段变更自动生成）
|
||
-- sensitive_op=敏感信息跟进（相关方保护变更）
|
||
-- sensitive_view=敏感信息查看（查看号码等）
|
||
-- other=其他跟进（钥匙/新增联系人等）
|
||
-- system=系统日志
|
||
|
||
-- 写入跟进专用字段
|
||
purpose VARCHAR(50), -- 跟进目的（由运营维护枚举值）
|
||
content TEXT, -- 跟进内容，最少6字最多500字
|
||
ai_tag VARCHAR(20)
|
||
CHECK (ai_tag IS NULL OR ai_tag IN ('ai_for_sale','ai_not_for_sale')),
|
||
|
||
-- 修改跟进专用字段
|
||
change_detail JSONB,
|
||
-- 格式：{"field": "sale_price", "old": 850, "new": 800, "label": "售价"}
|
||
-- 支持多字段同时变更
|
||
|
||
-- 系统标签（显示在日志时间线上的 tag）
|
||
log_tag VARCHAR(50),
|
||
-- 如：查看号码/图片下载/改状态/改价格/改等级/修改相关方 等
|
||
|
||
-- 可见性控制
|
||
is_public BOOLEAN NOT NULL DEFAULT TRUE,
|
||
-- FALSE = 仅本人及上级可见
|
||
|
||
-- 操作人
|
||
operator_id UUID REFERENCES staff(id) ON DELETE SET NULL,
|
||
operator_snapshot JSONB, -- {name, role, org_unit_name, store_group}
|
||
|
||
-- 是否可删除（敏感信息查看类型 = FALSE）
|
||
is_deletable BOOLEAN NOT NULL DEFAULT TRUE,
|
||
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
deleted_at TIMESTAMPTZ -- 仅 is_deletable=TRUE 时才能软删
|
||
);
|
||
|
||
-- 核心索引：时间线展示
|
||
CREATE INDEX idx_follow_logs_property_time ON follow_logs(property_id, created_at DESC)
|
||
WHERE deleted_at IS NULL;
|
||
|
||
-- 按类型过滤（6个 Tab 查询）
|
||
CREATE INDEX idx_follow_logs_type ON follow_logs(property_id, log_type, created_at DESC)
|
||
WHERE deleted_at IS NULL;
|
||
|
||
-- 操作员过滤（跟进日志搜索功能）
|
||
CREATE INDEX idx_follow_logs_operator ON follow_logs(operator_id, created_at DESC)
|
||
WHERE deleted_at IS NULL;
|
||
|
||
-- 不可删除类型专用索引（合规审计）
|
||
CREATE INDEX idx_follow_logs_sensitive ON follow_logs(property_id, created_at DESC)
|
||
WHERE log_type IN ('sensitive_view','sensitive_op');
|
||
|
||
-- 跟进日志附件（一条跟进可附多张图）
|
||
CREATE TABLE follow_log_attachments (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
follow_log_id UUID NOT NULL REFERENCES follow_logs(id) ON DELETE CASCADE,
|
||
file_key TEXT NOT NULL, -- R2/S3 存储路径
|
||
file_name VARCHAR(255) NOT NULL,
|
||
file_size INTEGER NOT NULL, -- bytes
|
||
file_type VARCHAR(10)
|
||
CHECK (file_type IN ('bmp','jpg','png','svg','gif')),
|
||
sort_order SMALLINT NOT NULL DEFAULT 0,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
|
||
CREATE INDEX idx_follow_attachments_log ON follow_log_attachments(follow_log_id);
|
||
|
||
-- 跟进录音（独立存储，支持音频文件）
|
||
CREATE TABLE follow_log_recordings (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
follow_log_id UUID NOT NULL REFERENCES follow_logs(id) ON DELETE CASCADE,
|
||
file_key TEXT NOT NULL,
|
||
duration_seconds INTEGER,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
### 3.8 钥匙管理（Key Management）
|
||
|
||
```sql
|
||
CREATE TABLE property_keys (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE,
|
||
|
||
key_type VARCHAR(20) NOT NULL
|
||
CHECK (key_type IN ('mechanical','password')),
|
||
|
||
-- 钥匙持有方
|
||
holder_id UUID REFERENCES staff(id) ON DELETE SET NULL,
|
||
holder_snapshot JSONB, -- {name, store_group}（防人员变动丢失）
|
||
storage_unit_id UUID REFERENCES org_units(id) ON DELETE SET NULL, -- 保管部门
|
||
|
||
-- 他司钥匙标记
|
||
is_other_agency BOOLEAN NOT NULL DEFAULT FALSE,
|
||
other_agency_info VARCHAR(30), -- 他司信息，最多30字
|
||
|
||
remarks TEXT, -- 备注，最多200字
|
||
|
||
is_active BOOLEAN NOT NULL DEFAULT TRUE, -- FALSE = 钥匙已归还/失效
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
created_by UUID REFERENCES staff(id) ON DELETE SET NULL
|
||
);
|
||
|
||
CREATE INDEX idx_property_keys_property ON property_keys(property_id)
|
||
WHERE is_active = TRUE;
|
||
|
||
-- 钥匙附件
|
||
CREATE TABLE key_attachments (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
key_id UUID NOT NULL REFERENCES property_keys(id) ON DELETE CASCADE,
|
||
file_key TEXT NOT NULL,
|
||
file_name VARCHAR(255) NOT NULL,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
### 3.9 委托管理（Commission Management）
|
||
|
||
```sql
|
||
CREATE TABLE commissions (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE,
|
||
|
||
commission_type VARCHAR(50) NOT NULL, -- 独家委托/非独家委托（运营维护枚举）
|
||
period_start DATE NOT NULL,
|
||
period_end DATE,
|
||
is_open_ended BOOLEAN NOT NULL DEFAULT FALSE, -- 无固定结束日期
|
||
|
||
-- 委托方（负责经纪人）
|
||
agent_id UUID REFERENCES staff(id) ON DELETE SET NULL,
|
||
agent_snapshot JSONB,
|
||
|
||
-- 签约方式（选择后动态展示委托书模板）
|
||
signing_method VARCHAR(50),
|
||
|
||
-- 委托人（产权人）信息
|
||
owner_type VARCHAR(20) NOT NULL DEFAULT 'owner'
|
||
CHECK (owner_type IN ('owner','authorized_third')),
|
||
-- 从 property_contacts 中选择
|
||
property_owner_contact_id UUID REFERENCES property_contacts(id) ON DELETE SET NULL,
|
||
owner_name VARCHAR(50), -- 产权人姓名
|
||
owner_id_type VARCHAR(20), -- 证件类型：身份证/护照 等
|
||
owner_id_number VARCHAR(50), -- 证件号码（加密存储）
|
||
owner_id_number_enc BYTEA,
|
||
|
||
remarks TEXT, -- 备注，最多200字
|
||
|
||
-- 状态
|
||
status VARCHAR(20) NOT NULL DEFAULT 'active'
|
||
CHECK (status IN ('active','expired','cancelled')),
|
||
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
created_by UUID REFERENCES staff(id) ON DELETE SET NULL
|
||
);
|
||
|
||
CREATE INDEX idx_commissions_property ON commissions(property_id);
|
||
CREATE INDEX idx_commissions_active ON commissions(property_id)
|
||
WHERE status = 'active';
|
||
|
||
-- 委托附件（身份证/房产证/委托书 等）
|
||
CREATE TABLE commission_attachments (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
commission_id UUID NOT NULL REFERENCES commissions(id) ON DELETE CASCADE,
|
||
category VARCHAR(20) NOT NULL
|
||
CHECK (category IN ('id_card','property_cert',
|
||
'commission_letter','other')),
|
||
file_key TEXT NOT NULL,
|
||
file_name VARCHAR(255) NOT NULL,
|
||
file_size INTEGER,
|
||
sort_order SMALLINT NOT NULL DEFAULT 0,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
|
||
CREATE INDEX idx_commission_attachments_commission ON commission_attachments(commission_id);
|
||
```
|
||
|
||
---
|
||
|
||
### 3.10 实勘管理（Field Survey）
|
||
|
||
```sql
|
||
CREATE TABLE field_surveys (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE,
|
||
|
||
status VARCHAR(10) NOT NULL DEFAULT 'draft'
|
||
CHECK (status IN ('draft','submitted')),
|
||
|
||
-- GPS 定位
|
||
gps_latitude NUMERIC(10,7),
|
||
gps_longitude NUMERIC(10,7),
|
||
gps_accuracy NUMERIC(6,2), -- 精度（米）
|
||
|
||
description TEXT, -- 实勘说明，最多200字
|
||
|
||
submitted_at TIMESTAMPTZ,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
created_by UUID NOT NULL REFERENCES staff(id) ON DELETE RESTRICT
|
||
);
|
||
|
||
CREATE INDEX idx_field_surveys_property ON field_surveys(property_id);
|
||
CREATE INDEX idx_field_surveys_submitted ON field_surveys(property_id)
|
||
WHERE status = 'submitted';
|
||
|
||
-- 实勘照片（按空间分类）
|
||
CREATE TABLE survey_photos (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
survey_id UUID NOT NULL REFERENCES field_surveys(id) ON DELETE CASCADE,
|
||
category VARCHAR(20) NOT NULL
|
||
CHECK (category IN ('layout','living_room','dining_room',
|
||
'bedroom','bathroom','kitchen',
|
||
'entrance','balcony','study',
|
||
'indoor_other','outdoor')),
|
||
file_key TEXT NOT NULL, -- R2/S3 路径
|
||
thumbnail_key TEXT, -- 缩略图路径
|
||
file_size INTEGER,
|
||
width INTEGER,
|
||
height INTEGER,
|
||
sort_order SMALLINT NOT NULL DEFAULT 0,
|
||
is_vr_screenshot BOOLEAN NOT NULL DEFAULT FALSE,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
|
||
CREATE INDEX idx_survey_photos_survey ON survey_photos(survey_id);
|
||
CREATE INDEX idx_survey_photos_category ON survey_photos(survey_id, category);
|
||
```
|
||
|
||
---
|
||
|
||
### 3.11 房源图片管理（Property Photos）
|
||
|
||
```sql
|
||
-- ============================================================
|
||
-- 房源图片：与实勘照片分离存储，经纪人自主上传和管理
|
||
-- 封面限1张，全景类型单独处理
|
||
-- ============================================================
|
||
|
||
CREATE TABLE property_photos (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE,
|
||
|
||
category VARCHAR(20) NOT NULL
|
||
CHECK (category IN ('cover','entrance','living_room',
|
||
'dining_room','bedroom','bathroom',
|
||
'kitchen','balcony','study',
|
||
'indoor_other','outdoor','panorama')),
|
||
|
||
file_key TEXT NOT NULL, -- R2/S3 原图路径
|
||
thumbnail_key TEXT, -- 缩略图路径（Cloudflare Images 生成）
|
||
file_name VARCHAR(255),
|
||
file_size INTEGER,
|
||
width INTEGER,
|
||
height INTEGER,
|
||
|
||
is_cover BOOLEAN NOT NULL DEFAULT FALSE,
|
||
sort_order SMALLINT NOT NULL DEFAULT 0,
|
||
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
created_by UUID REFERENCES staff(id) ON DELETE SET NULL
|
||
);
|
||
|
||
CREATE INDEX idx_property_photos_property ON property_photos(property_id);
|
||
CREATE INDEX idx_property_photos_cover ON property_photos(property_id)
|
||
WHERE is_cover = TRUE;
|
||
CREATE INDEX idx_property_photos_category ON property_photos(property_id, category);
|
||
|
||
-- 唯一约束：每个房源只能有一张封面
|
||
CREATE UNIQUE INDEX idx_property_photos_unique_cover
|
||
ON property_photos(property_id)
|
||
WHERE is_cover = TRUE;
|
||
```
|
||
|
||
---
|
||
|
||
### 3.12 房源附件（Property Attachments）
|
||
|
||
```sql
|
||
CREATE TABLE property_attachments (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE,
|
||
|
||
category VARCHAR(20) NOT NULL DEFAULT 'other'
|
||
CHECK (category IN ('id_card','property_cert',
|
||
'commission_letter','other')),
|
||
|
||
file_key TEXT NOT NULL,
|
||
file_name VARCHAR(255) NOT NULL,
|
||
file_size INTEGER NOT NULL,
|
||
file_type VARCHAR(50), -- MIME type
|
||
|
||
sort_order SMALLINT NOT NULL DEFAULT 0,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
created_by UUID REFERENCES staff(id) ON DELETE SET NULL
|
||
);
|
||
|
||
CREATE INDEX idx_property_attachments_property ON property_attachments(property_id);
|
||
CREATE INDEX idx_property_attachments_category ON property_attachments(property_id, category);
|
||
```
|
||
|
||
---
|
||
|
||
### 3.13 房源营销信息（Property Marketing）
|
||
|
||
```sql
|
||
CREATE TABLE property_marketing (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
property_id UUID NOT NULL UNIQUE REFERENCES properties(id) ON DELETE CASCADE,
|
||
|
||
marketing_title VARCHAR(30), -- 营销标题 0-30字
|
||
core_selling_points TEXT, -- 核心卖点，最多200字
|
||
owner_attitude TEXT, -- 业主心态，最多200字
|
||
layout_description TEXT, -- 户型介绍，最多200字
|
||
complex_description TEXT, -- 小区介绍，最多200字
|
||
|
||
-- AI 生成标记
|
||
ai_generated_points BOOLEAN NOT NULL DEFAULT FALSE,
|
||
ai_generated_attitude BOOLEAN NOT NULL DEFAULT FALSE,
|
||
|
||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
updated_by UUID REFERENCES staff(id) ON DELETE SET NULL
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
### 3.14 产证信息（Property Certificate）
|
||
|
||
```sql
|
||
CREATE TABLE property_certificates (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
property_id UUID NOT NULL UNIQUE REFERENCES properties(id) ON DELETE CASCADE,
|
||
|
||
owner_name VARCHAR(100),
|
||
owner_id_number VARCHAR(50), -- 身份证号/统一社会信用代码
|
||
owner_cert_type VARCHAR(20), -- 身份证/护照/营业执照
|
||
property_location VARCHAR(500), -- 房屋坐落（产权证书上的地址），最多50字
|
||
|
||
-- 产证状态
|
||
cert_status VARCHAR(30),
|
||
cert_no VARCHAR(100), -- 产证号
|
||
first_registered_at DATE, -- 首次登记时间
|
||
ownership_nature VARCHAR(30),
|
||
land_nature VARCHAR(30), -- 土地性质
|
||
|
||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
updated_by UUID REFERENCES staff(id) ON DELETE SET NULL
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
### 3.15 楼盘基本信息扩展（Complex Property Info）
|
||
|
||
```sql
|
||
-- 补充：楼盘与房源通过 complex_id 关联，楼盘信息首次填写后修改需走楼盘管理系统
|
||
-- 楼盘价格走势（用于楼盘详情页展示）
|
||
CREATE TABLE complex_price_trends (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
complex_id UUID NOT NULL REFERENCES complexes(id) ON DELETE CASCADE,
|
||
record_month DATE NOT NULL, -- 月份（取该月1日存储）
|
||
avg_sale_price NUMERIC(10,2), -- 月均售价（万元/套）
|
||
avg_unit_price NUMERIC(10,2), -- 月均单价（元/m²）
|
||
transaction_count INTEGER, -- 成交套数
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
|
||
CREATE UNIQUE INDEX idx_complex_price_trend_month
|
||
ON complex_price_trends(complex_id, record_month);
|
||
```
|
||
|
||
---
|
||
|
||
### 3.16 维护完成度评分（Completeness Scoring）
|
||
|
||
```sql
|
||
-- ============================================================
|
||
-- 维护完成度：不直接存完整计算明细（减少宽表），
|
||
-- 以触发器/Celery 任务异步更新 properties.completeness_score
|
||
-- 此表存储各维度的得分快照，供详情页展示
|
||
-- ============================================================
|
||
|
||
CREATE TABLE property_completeness (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
property_id UUID NOT NULL UNIQUE REFERENCES properties(id) ON DELETE CASCADE,
|
||
|
||
-- 各维度得分（满分见 PRD 8.2）
|
||
score_core_info SMALLINT NOT NULL DEFAULT 0, -- 重点信息 满分8
|
||
score_attachment SMALLINT NOT NULL DEFAULT 0, -- 附件 满分8
|
||
score_survey SMALLINT NOT NULL DEFAULT 0, -- 实勘 满分16
|
||
score_vr SMALLINT NOT NULL DEFAULT 0, -- VR 满分8
|
||
score_key SMALLINT NOT NULL DEFAULT 0, -- 钥匙 满分10
|
||
score_commission SMALLINT NOT NULL DEFAULT 0, -- 委托 满分10
|
||
score_verification SMALLINT NOT NULL DEFAULT 0, -- 验证 满分7
|
||
score_follow_up SMALLINT NOT NULL DEFAULT 0, -- 跟进 满分8
|
||
score_viewing SMALLINT NOT NULL DEFAULT 0, -- 带看 满分8
|
||
score_other SMALLINT NOT NULL DEFAULT 0, -- 其他 满分7
|
||
total_score SMALLINT NOT NULL DEFAULT 0, -- 总分 0-100
|
||
|
||
calculated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
### 3.17 客源管理（Client Management）
|
||
|
||
> **详细模型** → 见 [`DATA_MODEL_CLIENT.md`](./DATA_MODEL_CLIENT.md)
|
||
> 该文件为权威定义，包含完整字段、枚举、状态机、查询模式和禁止操作。
|
||
|
||
**核心表概览**（开发时以 DATA_MODEL_CLIENT.md 为准）：
|
||
|
||
| 表名 | 说明 |
|
||
|------|------|
|
||
| `clients` | 客源主表（私客/公客/成交客），含加密手机号哈希、活跃度、归属人 |
|
||
| `client_contacts` | 联系人（1:N），手机号加密+哈希，支持多联系人 |
|
||
| `client_requirements` | 需求信息（可多类型：二手/新房/租房），含预算/面积/商圈/朝向等偏好 |
|
||
| `client_follow_logs` | 跟进日志（高写入频率，5种类型，敏感查看类型不可删） |
|
||
| `client_follow_log_attachments` | 跟进附件（图片/录音，最大20MB） |
|
||
| `client_viewings` | 带看/预约记录（1:N，含陪看人/合作带看人） |
|
||
| `client_property_matches` | 智能配房结果（录客配房/系统配房，匹配度评分） |
|
||
| `client_status_logs` | 状态变更不可变审计日志（改状态/改等级/转公/转成交/转无效等） |
|
||
| `client_favorite_folders` | 私客收藏夹（经纪人自定义分组） |
|
||
| `client_folder_items` | 收藏夹与客源的多对多关联 |
|
||
| `client_school_preferences` | 意向学校（拆表，支持精确查询） |
|
||
|
||
**关键约束提示**：
|
||
- `client_contacts.phone_hash` 是重复客源检测的唯一依据，录入前必须查重
|
||
- `client_status_logs` **无 deleted_at**，不可删除
|
||
- 私客超时（配置天数内无跟进）→ Celery 自动转公（`transfer_to_public_type = 'auto'`）
|
||
- 活跃度 `activity_level` 由 Celery 每日凌晨批量计算，不实时更新
|
||
|
||
---
|
||
|
||
### 3.18 系统设置（System Settings）
|
||
|
||
```sql
|
||
-- ============================================================
|
||
-- 枚举/选项管理：跟进目的、标签、来源渠道 等运营维护的枚举值
|
||
-- ============================================================
|
||
|
||
CREATE TABLE lookup_categories (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
code VARCHAR(50) UNIQUE NOT NULL, -- 如：follow_purpose, property_source
|
||
name VARCHAR(100) NOT NULL,
|
||
module VARCHAR(30) NOT NULL -- property/client/system
|
||
);
|
||
|
||
CREATE TABLE lookup_items (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
category_id UUID NOT NULL REFERENCES lookup_categories(id) ON DELETE CASCADE,
|
||
value VARCHAR(100) NOT NULL,
|
||
label VARCHAR(100) NOT NULL, -- 显示文本
|
||
sort_order INTEGER NOT NULL DEFAULT 0,
|
||
is_active BOOLEAN NOT NULL DEFAULT TRUE,
|
||
metadata JSONB NOT NULL DEFAULT '{}', -- 扩展属性
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
|
||
CREATE INDEX idx_lookup_items_category ON lookup_items(category_id)
|
||
WHERE is_active = TRUE;
|
||
CREATE UNIQUE INDEX idx_lookup_items_value ON lookup_items(category_id, value);
|
||
|
||
-- 自定义标签（速销/独家/唯一 等）
|
||
CREATE TABLE property_tags (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
name VARCHAR(50) NOT NULL,
|
||
color VARCHAR(7), -- HEX 颜色
|
||
is_system BOOLEAN NOT NULL DEFAULT FALSE, -- 系统预置标签不可删除
|
||
sort_order INTEGER NOT NULL DEFAULT 0,
|
||
is_active BOOLEAN NOT NULL DEFAULT TRUE
|
||
);
|
||
|
||
-- 房源 ↔ 标签 多对多
|
||
CREATE TABLE property_tag_relations (
|
||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE,
|
||
tag_id UUID NOT NULL REFERENCES property_tags(id) ON DELETE CASCADE,
|
||
PRIMARY KEY (property_id, tag_id)
|
||
);
|
||
|
||
CREATE INDEX idx_property_tags_property ON property_tag_relations(property_id);
|
||
CREATE INDEX idx_property_tags_tag ON property_tag_relations(tag_id);
|
||
|
||
-- 收藏（经纪人收藏房源）
|
||
CREATE TABLE property_favorites (
|
||
staff_id UUID NOT NULL REFERENCES staff(id) ON DELETE CASCADE,
|
||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
PRIMARY KEY (staff_id, property_id)
|
||
);
|
||
|
||
CREATE INDEX idx_property_favorites_staff ON property_favorites(staff_id);
|
||
|
||
-- 保护房设置
|
||
CREATE TABLE property_protections (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
property_id UUID NOT NULL UNIQUE REFERENCES properties(id) ON DELETE CASCADE,
|
||
is_protected BOOLEAN NOT NULL DEFAULT FALSE,
|
||
reason TEXT,
|
||
start_at TIMESTAMPTZ,
|
||
end_at TIMESTAMPTZ,
|
||
set_by UUID REFERENCES staff(id) ON DELETE SET NULL,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
|
||
-- 筛选方案（保存的搜索条件）
|
||
CREATE TABLE saved_filters (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
staff_id UUID NOT NULL REFERENCES staff(id) ON DELETE CASCADE,
|
||
name VARCHAR(100) NOT NULL,
|
||
module VARCHAR(20) NOT NULL DEFAULT 'property',
|
||
filter_params JSONB NOT NULL, -- 完整筛选参数 JSON
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
|
||
CREATE INDEX idx_saved_filters_staff ON saved_filters(staff_id, module);
|
||
|
||
-- 号码方修改审批
|
||
CREATE TABLE number_holder_approvals (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE,
|
||
contact_id UUID NOT NULL REFERENCES property_contacts(id) ON DELETE CASCADE,
|
||
applicant_id UUID NOT NULL REFERENCES staff(id) ON DELETE RESTRICT,
|
||
approver_id UUID REFERENCES staff(id) ON DELETE SET NULL,
|
||
status VARCHAR(20) NOT NULL DEFAULT 'pending'
|
||
CHECK (status IN ('pending','approved','rejected')),
|
||
remarks TEXT,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
decided_at TIMESTAMPTZ
|
||
);
|
||
|
||
CREATE INDEX idx_number_holder_approvals_status ON number_holder_approvals(status)
|
||
WHERE status = 'pending';
|
||
```
|
||
|
||
---
|
||
|
||
## 五、关键索引汇总与查询优化策略
|
||
|
||
### 4.1 房源列表页核心查询分析
|
||
|
||
```sql
|
||
-- 典型查询：出售状态 + 公盘 + 特定区域 + 价格区间 + 户型筛选 + 按挂牌日期排序
|
||
-- 优化方案：复合索引覆盖最高频维度组合
|
||
|
||
-- 高频组合索引（status + attribute，覆盖 90% 的列表查询）
|
||
CREATE INDEX idx_properties_list_composite ON properties
|
||
(status, attribute, complex_id, sale_price DESC NULLS LAST)
|
||
WHERE deleted_at IS NULL;
|
||
|
||
-- 与我相关查询（经纪人个人仪表板）
|
||
CREATE INDEX idx_properties_my_properties ON properties
|
||
(seller_agent_id, status, listed_at DESC NULLS LAST)
|
||
WHERE deleted_at IS NULL;
|
||
```
|
||
|
||
### 4.2 全文搜索触发器（自动维护 search_vector）
|
||
|
||
```sql
|
||
-- 房源全文检索向量更新触发器
|
||
CREATE OR REPLACE FUNCTION update_property_search_vector()
|
||
RETURNS TRIGGER AS $$
|
||
BEGIN
|
||
NEW.search_vector :=
|
||
setweight(to_tsvector('simple', COALESCE(NEW.block_no, '') ||
|
||
' ' || COALESCE(NEW.unit_no, '') ||
|
||
' ' || COALESCE(NEW.room_no, '')), 'A') ||
|
||
setweight(to_tsvector('simple', COALESCE(NEW.remarks, '')), 'C');
|
||
RETURN NEW;
|
||
END;
|
||
$$ LANGUAGE plpgsql;
|
||
|
||
CREATE TRIGGER trg_property_search_vector
|
||
BEFORE INSERT OR UPDATE OF block_no, unit_no, room_no, remarks
|
||
ON properties
|
||
FOR EACH ROW EXECUTE FUNCTION update_property_search_vector();
|
||
|
||
-- 楼盘全文检索向量（含别名，提升模糊搜索精度）
|
||
CREATE OR REPLACE FUNCTION update_complex_search_vector()
|
||
RETURNS TRIGGER AS $$
|
||
BEGIN
|
||
NEW.search_vector :=
|
||
setweight(to_tsvector('simple', COALESCE(NEW.name, '')), 'A') ||
|
||
setweight(to_tsvector('simple', COALESCE(NEW.alias, '')), 'B') ||
|
||
setweight(to_tsvector('simple', COALESCE(NEW.address, '')), 'C');
|
||
RETURN NEW;
|
||
END;
|
||
$$ LANGUAGE plpgsql;
|
||
|
||
CREATE TRIGGER trg_complex_search_vector
|
||
BEFORE INSERT OR UPDATE OF name, alias, address
|
||
ON complexes
|
||
FOR EACH ROW EXECUTE FUNCTION update_complex_search_vector();
|
||
```
|
||
|
||
### 4.3 last_followed_at 自动维护触发器
|
||
|
||
```sql
|
||
-- 每次写入跟进日志时，自动更新 properties.last_followed_at
|
||
CREATE OR REPLACE FUNCTION update_property_last_followed()
|
||
RETURNS TRIGGER AS $$
|
||
BEGIN
|
||
IF NEW.log_type = 'written' THEN
|
||
UPDATE properties
|
||
SET last_followed_at = NEW.created_at,
|
||
updated_at = NOW()
|
||
WHERE id = NEW.property_id;
|
||
END IF;
|
||
RETURN NEW;
|
||
END;
|
||
$$ LANGUAGE plpgsql;
|
||
|
||
CREATE TRIGGER trg_update_last_followed
|
||
AFTER INSERT ON follow_logs
|
||
FOR EACH ROW EXECUTE FUNCTION update_property_last_followed();
|
||
```
|
||
|
||
---
|
||
|
||
## 六、Redis 缓存策略
|
||
|
||
### 5.1 缓存 Key 规范
|
||
|
||
```
|
||
# 格式：{tenant_schema}:{module}:{entity}:{id}:{field}
|
||
# TTL 单位：秒
|
||
|
||
# 房源详情（高频读取）
|
||
{schema}:prop:detail:{property_id} TTL: 300 (5分钟)
|
||
|
||
# 房源联系人（含解密号码，敏感，TTL 短）
|
||
{schema}:prop:contacts:{property_id} TTL: 60 (1分钟)
|
||
|
||
# 楼盘基础信息（低变更频率）
|
||
{schema}:complex:base:{complex_id} TTL: 3600 (1小时)
|
||
|
||
# 楼盘名称自动补全候选列表（联想搜索）
|
||
{schema}:complex:autocomplete:{prefix} TTL: 600 (10分钟)
|
||
|
||
# 员工信息（用于日志快照）
|
||
{schema}:staff:base:{staff_id} TTL: 1800 (30分钟)
|
||
|
||
# 枚举值/lookup（几乎不变）
|
||
{schema}:lookup:{category_code} TTL: 86400 (24小时)
|
||
|
||
# 标签列表
|
||
{schema}:tags:property TTL: 3600
|
||
|
||
# 维护完成度（Celery 计算后写入，详情页直接读 Redis）
|
||
{schema}:prop:completeness:{property_id} TTL: 600
|
||
|
||
# 房源列表计数（筛选后总条数，避免 COUNT(*) 全扫）
|
||
{schema}:prop:count:{filter_hash} TTL: 30 (短TTL，保证准确性)
|
||
```
|
||
|
||
### 5.2 缓存失效策略
|
||
|
||
```python
|
||
# Django Signal 驱动的缓存失效（在 models.py 中注册）
|
||
|
||
# 房源更新 → 失效详情缓存 + 完成度缓存
|
||
# 跟进日志新增 → 失效 last_followed_at 缓存
|
||
# 联系人更新 → 失效联系人缓存（立即）
|
||
# 楼盘更新 → 失效楼盘缓存 + 相关房源缓存（批量）
|
||
# 枚举更新 → 失效对应 lookup 缓存
|
||
```
|
||
|
||
---
|
||
|
||
## 七、Django Model 层设计要点
|
||
|
||
### 6.1 抽象基类
|
||
|
||
```python
|
||
# models/base.py
|
||
|
||
import uuid
|
||
from django.db import models
|
||
|
||
class UUIDPrimaryKeyModel(models.Model):
|
||
id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
|
||
class Meta:
|
||
abstract = True
|
||
|
||
class TimeStampedModel(UUIDPrimaryKeyModel):
|
||
created_at = models.DateTimeField(auto_now_add=True, db_index=False)
|
||
updated_at = models.DateTimeField(auto_now=True)
|
||
class Meta:
|
||
abstract = True
|
||
|
||
class SoftDeleteModel(TimeStampedModel):
|
||
deleted_at = models.DateTimeField(null=True, blank=True, db_index=False)
|
||
|
||
class Meta:
|
||
abstract = True
|
||
|
||
def soft_delete(self, deleted_by=None):
|
||
from django.utils import timezone
|
||
self.deleted_at = timezone.now()
|
||
self.save(update_fields=['deleted_at', 'updated_at'])
|
||
|
||
class AuditedModel(SoftDeleteModel):
|
||
created_by = models.ForeignKey(
|
||
'staff.Staff', null=True, on_delete=models.SET_NULL,
|
||
related_name='+', db_column='created_by'
|
||
)
|
||
updated_by = models.ForeignKey(
|
||
'staff.Staff', null=True, on_delete=models.SET_NULL,
|
||
related_name='+', db_column='updated_by'
|
||
)
|
||
class Meta:
|
||
abstract = True
|
||
```
|
||
|
||
### 6.2 加密字段 Mixin
|
||
|
||
```python
|
||
# utils/encryption.py
|
||
# 手机号加密：AES-256-GCM + SHA-256 哈希索引
|
||
|
||
class EncryptedPhoneField:
|
||
"""
|
||
存储时：phone → AES加密 → phone_enc (BYTEA)
|
||
phone → SHA256 → phone_hash (VARCHAR 64)
|
||
查询时：phone_hash 走索引，phone_enc 解密展示
|
||
打码展示：前3位明文 + ******* + 后3位
|
||
"""
|
||
pass
|
||
```
|
||
|
||
### 6.3 Manager 过滤软删除
|
||
|
||
```python
|
||
class ActiveManager(models.Manager):
|
||
def get_queryset(self):
|
||
return super().get_queryset().filter(deleted_at__isnull=True)
|
||
|
||
class PropertyManager(ActiveManager):
|
||
def public(self):
|
||
return self.get_queryset().filter(attribute='public')
|
||
|
||
def mine(self, staff_id):
|
||
return self.get_queryset().filter(seller_agent_id=staff_id)
|
||
```
|
||
|
||
---
|
||
|
||
## 八、数据量与性能预测
|
||
|
||
| 表名 | 预估行数 | 增长速度 | 分区策略 |
|
||
|------|---------|---------|---------|
|
||
| `properties` | 89,000+ | 中速 | 暂不分区，建议 500k 后按 `created_at` RANGE 分区 |
|
||
| `follow_logs` | 200万+ | 高速（最高频写入） | 按 `created_at` 月度 RANGE 分区 |
|
||
| `property_photos` | 500万+ | 高速 | 按 `property_id` HASH 分区（16分区） |
|
||
| `price_changes` | 50万 | 中速 | 无需分区 |
|
||
| `listing_histories` | 20万 | 低速 | 无需分区 |
|
||
| `clients` | 10万+ | 中速 | 暂不分区 |
|
||
| `viewings` | 100万 | 中速 | 无需分区 |
|
||
|
||
---
|
||
|
||
## 九、必须在开发启动前明确的数据架构决策
|
||
|
||
| 决策项 | 推荐方案 | 风险 |
|
||
|-------|---------|------|
|
||
| 小区数据来源 | 预导入基础数据（安居客/链家 API）+ 支持手动新增兜底 | 高：影响录入体验 |
|
||
| 私盘可见范围 | 录入人所在门店可见（综合业务需求） | 需与权限模块约定 |
|
||
| 号码查看权限 | 角色级控制：经纪人限查自己相关房源，店长无限制 | 需合规确认 |
|
||
| 重复房源主键 | 主键：手机号 hash；辅助：（小区+楼栋+单元+房号）组合 | 需双重校验 |
|
||
| 跟进目的枚举 | 存 lookup_items 表，运营可维护 | 初始化数据需提前收集 |
|
||
| 手机号加密算法 | AES-256-GCM，密钥存 Django settings（生产用 Vault） | 密钥管理需单独规划 |
|
||
|
||
---
|
||
|
||
*本文档为 Fonrey 系统 DATA MODEL v1.0，随 PRD 迭代同步更新。*
|
||
*下一步建议：API 接口规范（URL 设计 + Request/Response Schema）*
|