575 lines
27 KiB
Markdown
575 lines
27 KiB
Markdown
# Fonrey — 客源管理数据模型（DATA_MODEL_CLIENT）
|
||
|
||
> **所属系统**: Fonrey 房产经纪管理系统
|
||
> **版本**: v1.0
|
||
> **日期**: 2026-04-24
|
||
> **关联模块**: `apps/client/` — 私客、公客、成交客、跟进记录、带看、智能配房
|
||
|
||
---
|
||
|
||
## 一、领域概览（Domain Overview）
|
||
|
||
### 核心概念
|
||
|
||
- **Client（客源）**：有购房/租房意向或历史成交记录的客户。核心实体，与房源（Property）是系统业务闭环的两端。
|
||
- **客源类型**：
|
||
- **私客（private）**：经纪人独占跟进的意向客户，是本期核心。
|
||
- **公客（public）**：私客超时未跟进或手动转公后，进入全公司共享客源池。
|
||
- **成交客（transacted）**：已完成购房/租房成交的客户，用于复购/转介绍跟进。
|
||
- **ClientContact（联系人）**：一个客源可有多个联系人，每个联系人有独立手机号。手机号加密存储，用于重复检测（「私客与成交客重复」）。
|
||
- **ClientRequirement（需求信息）**：购房/租房的详细偏好。一个客源可同时有「二手」「新房」「租房」三种需求类型（分别对应独立的需求记录）。
|
||
- **ClientFollowLog（跟进日志）**：经纪人与客户每次沟通的书面记录，是客源活跃度计算的数据来源。
|
||
- **Viewing（带看记录）**：与 Property 模块共享此表，记录经纪人带客户看房的过程。见主 DATA_MODEL.md 3.17 节。
|
||
- **ClientPropertyMatch（智能配房）**：系统按需求自动匹配的房源列表，分「录客配房」和「系统配房」两种来源。
|
||
- **ClientFavoriteFolder（收藏夹）**：经纪人自定义的客源分组收藏夹。
|
||
|
||
### 关键业务规则
|
||
|
||
1. **私客手机号唯一性**：录入联系人手机号时，系统通过 `phone_hash` 检测是否与现有私客/成交客/公客重复，并在列表顶部提示重复数量。
|
||
2. **活跃度计算**：系统根据「最后跟进日期」自动计算客源活跃度，分为：新配偶（新建）/ 7日活跃 / 30日活跃 / 90日活跃 / 即将过期 / 无效。具体阈值由运营配置。
|
||
3. **私客自动转公规则**：超过配置天数（如 30 天）无跟进记录，系统自动将私客标记为公客（`transfer_to_public_type = 'auto'`）。
|
||
4. **状态机**：客源状态有严格流转规则（见第四章），不可跳过转台。
|
||
5. **跟进目的枚举**：由 `lookup_items` 表维护，运营可配置，当前已知 23 项（见 Story 8）。
|
||
6. **号码查看审计**：查看联系人明文号码需记录 `client_follow_logs`（`log_type = 'sensitive_view'`），不可删除。
|
||
7. **需求类型独立存储**：同一客源可同时有「二手购房」「租房」两类需求，分别存储在独立需求记录中，由 `client_requirements.requirement_type` 区分。
|
||
|
||
---
|
||
|
||
## 二、实体关系
|
||
|
||
```
|
||
Client (客源主表)
|
||
│
|
||
├── 1:N ── ClientContact (联系人，多个号码)
|
||
├── 1:N ── ClientRequirement (需求信息，可多类型)
|
||
├── 1:N ── ClientFollowLog (跟进日志，高写入频率)
|
||
├── 1:N ── ClientViewing (带看预约)
|
||
├── 1:N ── ClientPropertyMatch (智能配房结果)
|
||
├── 1:1 ── ClientActivityCache (活跃度缓存，异步计算)
|
||
├── N:M ── ClientFavoriteFolder (通过 client_folder_items 关联)
|
||
└── 1:N ── ClientStatusLog (状态变更日志，不可删)
|
||
|
||
ClientFavoriteFolder
|
||
└── 1:N ── ClientFolderItem (收藏夹中的客源)
|
||
|
||
Staff (员工)
|
||
├── first_recorder_id → Client (首录人)
|
||
└── owner_id → Client (归属人)
|
||
```
|
||
|
||
---
|
||
|
||
## 三、Schema 定义
|
||
|
||
### 3.1 clients — 客源主表
|
||
|
||
| 字段 | 类型 | 约束 | 业务说明 |
|
||
|------|------|------|----------|
|
||
| id | UUID | PK | |
|
||
| client_no | VARCHAR(30) | UNIQUE, NOT NULL | 系统生成的客源编号，格式由运营配置（如 KY20260424001） |
|
||
| client_type | VARCHAR(20) | NOT NULL DEFAULT 'private' | `private`=私客 / `public`=公客 / `transacted`=成交客 |
|
||
| status | VARCHAR(20) | NOT NULL DEFAULT 'buying' | 见下方枚举 |
|
||
| grade | VARCHAR(5) | NOT NULL DEFAULT 'C' | `A_urgent`=A急迫 / `A` / `B`=较强 / `C`=一般 / `D`=较弱 / `E`=暂不关注 |
|
||
| property_usage | VARCHAR(30) | NOT NULL DEFAULT 'residential' | `residential`=住宅 / `villa`=别墅 / `commercial_residential`=商住 / `shop`=商铺 / `office`=写字楼 / `other`=其他 |
|
||
| buying_purpose | VARCHAR(20)[] | | 购房目的多选：`rigid`=刚需 / `investment`=投资 / `school_district`=学区 / `upgrade`=改善 / `commercial`=商用 / `other`=其他 |
|
||
| payment_method | VARCHAR(30) | | `full`=全额 / `mortgage`=商业贷款 / `mortgage_fund`=商贷+公积金 / `fund`=公积金 |
|
||
| properties_owned | VARCHAR(20) | | `none`=无 / `local_none`=本地无外地有 / `local_has`=本地有 |
|
||
| has_loan_record | BOOLEAN | | 有无贷款记录 |
|
||
| id_type | VARCHAR(20) | | 证件类型：`id_card` / `passport` / `hk_macao` / `other` |
|
||
| id_number_enc | BYTEA | | 证件号码（AES 加密） |
|
||
| source | VARCHAR(50) | | 客户来源（lookup_items 维护） |
|
||
| remarks | TEXT | | 备注，最多200字 |
|
||
| is_starred | BOOLEAN | NOT NULL DEFAULT FALSE | 是否收藏（快速标记，详细收藏夹用 client_folder_items） |
|
||
| is_pinned | BOOLEAN | NOT NULL DEFAULT FALSE | 是否置顶（列表顶部置顶） |
|
||
| is_big_value | BOOLEAN | NOT NULL DEFAULT FALSE | 是否大价值客户（影响筛选展示） |
|
||
| is_protected | BOOLEAN | NOT NULL DEFAULT FALSE | 是否保护客（影响转公逻辑） |
|
||
| prefers_new_house | BOOLEAN | | 偏好新房（用于筛选） |
|
||
| transfer_to_public_type | VARCHAR(20) | | 转公客方式：`manual`=手动转公 / `auto`=自动转公（超时） / `marketing_jump`=营销客跳公 / `resource_public`=资料客素公 |
|
||
| transferred_public_at | TIMESTAMPTZ | | 进入公客池时间 |
|
||
| invalid_reason | VARCHAR(30) | | 无效原因：`invalid_phone`=号码无效 / `peer_agent`=同行 / `ad`=广告推销 / `no_intent`=无意向 / `other` |
|
||
| invalidated_at | TIMESTAMPTZ | | 标记无效时间 |
|
||
| transacted_at | DATE | | 成交日期 |
|
||
| transacted_property_id | UUID | FK→properties, SET NULL | 成交关联的房源 |
|
||
| transacted_price | NUMERIC(12,2) | | 成交价格（万元） |
|
||
| transacted_type | VARCHAR(20) | | 成交类型：`bought`=我购 / `rented`=我租 |
|
||
| transacted_property_type | VARCHAR(20) | | 成交房源类型：`second_hand`=二手 / `new_house`=新房 |
|
||
| first_recorder_id | UUID | FK→staff, SET NULL | 首录人 |
|
||
| owner_id | UUID | FK→staff, SET NULL | 归属人（私客独占跟进人） |
|
||
| org_unit_id | UUID | FK→org_units, SET NULL | 归属部门（冗余，加速筛选） |
|
||
| activity_level | VARCHAR(20) | | `new_matched`=新配偶 / `active_7d` / `active_30d` / `active_90d` / `expiring` / `frozen` / `invalid`（异步计算）|
|
||
| last_active_at | TIMESTAMPTZ | | 最后有效跟进时间（触发器维护） |
|
||
| last_follow_at | TIMESTAMPTZ | | 最后跟进时间（冗余，列表排序用） |
|
||
| commission_date | DATE | | 委托日期 |
|
||
| entrust_count | SMALLINT | NOT NULL DEFAULT 1 | 委托次数（成交后再委托则累加） |
|
||
| created_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |
|
||
| updated_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |
|
||
| deleted_at | TIMESTAMPTZ | | 软删除 |
|
||
| created_by | UUID | FK→staff, SET NULL | |
|
||
| updated_by | UUID | FK→staff, SET NULL | |
|
||
|
||
**关键索引**：
|
||
```sql
|
||
CREATE UNIQUE INDEX idx_clients_client_no ON clients(client_no) WHERE deleted_at IS NULL;
|
||
CREATE INDEX idx_clients_type_status ON clients(client_type, status) WHERE deleted_at IS NULL;
|
||
CREATE INDEX idx_clients_owner ON clients(owner_id) WHERE deleted_at IS NULL;
|
||
CREATE INDEX idx_clients_org_unit ON clients(org_unit_id) WHERE deleted_at IS NULL;
|
||
CREATE INDEX idx_clients_activity ON clients(activity_level, last_active_at DESC) WHERE deleted_at IS NULL;
|
||
CREATE INDEX idx_clients_grade ON clients(grade) WHERE deleted_at IS NULL;
|
||
CREATE INDEX idx_clients_transferred_at ON clients(transferred_public_at DESC) WHERE client_type = 'public';
|
||
CREATE INDEX idx_clients_last_follow ON clients(last_follow_at DESC NULLS LAST) WHERE deleted_at IS NULL;
|
||
```
|
||
|
||
---
|
||
|
||
### 3.2 client_contacts — 联系人表
|
||
|
||
| 字段 | 类型 | 约束 | 业务说明 |
|
||
|------|------|------|----------|
|
||
| id | UUID | PK | |
|
||
| client_id | UUID | NOT NULL, FK→clients, CASCADE | |
|
||
| sort_order | SMALLINT | NOT NULL DEFAULT 0 | 联系人1为主联系人（sort_order=0） |
|
||
| name | VARCHAR(50) | NOT NULL | 联系人姓名 |
|
||
| gender | VARCHAR(10) | NOT NULL DEFAULT 'male' | `male`=先生 / `female`=女士 |
|
||
| phone_enc | BYTEA | NOT NULL | AES-256-GCM 加密手机号（电话1） |
|
||
| phone_hash | VARCHAR(64) | NOT NULL | SHA-256 哈希（重复检测） |
|
||
| phone_country_code | VARCHAR(10) | NOT NULL DEFAULT '+86' | 国际区号 |
|
||
| phone_is_invalid | BOOLEAN | NOT NULL DEFAULT FALSE | 是否被标记为无效号码 |
|
||
| phone2_enc | BYTEA | | 备用电话2 |
|
||
| phone2_hash | VARCHAR(64) | | |
|
||
| wechat | VARCHAR(100) | | 微信号 |
|
||
| qq | VARCHAR(20) | | QQ号 |
|
||
| remarks | VARCHAR(200) | | 联系人备注，最多200字 |
|
||
| created_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |
|
||
| updated_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |
|
||
| deleted_at | TIMESTAMPTZ | | 软删除（不影响客源本身） |
|
||
| created_by | UUID | FK→staff, SET NULL | |
|
||
|
||
**关键索引**：
|
||
```sql
|
||
-- 关键：手机号哈希全局唯一索引（用于重复客源检测）
|
||
CREATE INDEX idx_client_contacts_phone_hash ON client_contacts(phone_hash) WHERE deleted_at IS NULL;
|
||
CREATE INDEX idx_client_contacts_phone2_hash ON client_contacts(phone2_hash) WHERE phone2_hash IS NOT NULL AND deleted_at IS NULL;
|
||
CREATE INDEX idx_client_contacts_client ON client_contacts(client_id) WHERE deleted_at IS NULL;
|
||
```
|
||
|
||
**业务注意**：
|
||
- `sort_order = 0` 的联系人为主联系人，姓名用于客源姓名显示
|
||
- 手机号标记无效（`phone_is_invalid = TRUE`）时，不影响记录存在，但该号码不再参与重复检测
|
||
- 联系人软删除后客源仍保留，但若所有联系人均被删则客源实际上无有效号码
|
||
|
||
---
|
||
|
||
### 3.3 client_requirements — 需求信息表
|
||
|
||
一个客源可同时有多类需求（二手购房、新房、租房），每类需求独立一条记录。
|
||
|
||
| 字段 | 类型 | 约束 | 业务说明 |
|
||
|------|------|------|----------|
|
||
| id | UUID | PK | |
|
||
| client_id | UUID | NOT NULL, FK→clients, CASCADE | |
|
||
| requirement_type | VARCHAR(20) | NOT NULL | `second_hand`=二手 / `new_house`=新房 / `rental`=租房 |
|
||
| is_primary | BOOLEAN | NOT NULL DEFAULT TRUE | 是否为主需求（用于列表展示） |
|
||
| budget_min | NUMERIC(12,2) | | 最低预算（万元/元，依据需求类型） |
|
||
| budget_max | NUMERIC(12,2) | | 最高预算 |
|
||
| area_min | NUMERIC(8,2) | | 最小面积（㎡） |
|
||
| area_max | NUMERIC(8,2) | | 最大面积 |
|
||
| bedroom_counts | SMALLINT[] | | 可接受卧室数：如 [2,3]（多选） |
|
||
| floor_preferences | VARCHAR(20)[] | | 楼层偏好多选：`no_first`=不要一层 / `low`=低楼层 / `mid`=中楼层 / `high`=高楼层 / `no_top`=不要顶层 |
|
||
| orientations | VARCHAR(10)[] | | 朝向多选：`east`/`south`/`west`/`north` |
|
||
| decorations | VARCHAR(10)[] | | 装修偏好多选（枚举同 properties.decoration） |
|
||
| building_age_ranges | VARCHAR(20)[] | | 楼龄多选：`within_5y`/`5_10y`/`10_15y`/`15_20y`/`over_20y` |
|
||
| intent_district_ids | UUID[] | | 意向行政区 ID 数组 |
|
||
| intent_business_area_ids | UUID[] | | 意向商圈 ID 数组 |
|
||
| intent_complex_names | TEXT | | 意向小区（文本，逗号分隔，最多500字） |
|
||
| transportation | VARCHAR(50) | | 交通要求（最多50字） |
|
||
| intent_school_names | TEXT | | 意向学校（文本，逗号分隔） |
|
||
| school_enrollment_date | DATE | | 入学时间（月份精度，取该月1日存储） |
|
||
| traffic_preference | TEXT | | 交通备注 |
|
||
| requirement_notes | VARCHAR(200) | | 需求备注（最多200字） |
|
||
| created_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |
|
||
| updated_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |
|
||
|
||
**关键索引**：
|
||
```sql
|
||
CREATE INDEX idx_client_requirements_client ON client_requirements(client_id);
|
||
CREATE INDEX idx_client_requirements_type ON client_requirements(requirement_type, client_id);
|
||
-- 智能配房时按预算/面积范围查询
|
||
CREATE INDEX idx_client_requirements_budget ON client_requirements(budget_min, budget_max);
|
||
CREATE INDEX idx_client_requirements_area ON client_requirements(area_min, area_max);
|
||
```
|
||
|
||
---
|
||
|
||
### 3.4 client_follow_logs — 客源跟进日志
|
||
|
||
> 与 `follow_logs`（房源跟进）结构类似，独立存储以避免跨模块混淆。
|
||
|
||
| 字段 | 类型 | 约束 | 业务说明 |
|
||
|------|------|------|----------|
|
||
| id | UUID | PK | |
|
||
| client_id | UUID | NOT NULL, FK→clients, CASCADE | |
|
||
| log_type | VARCHAR(30) | NOT NULL | 见下方枚举 |
|
||
| purpose | VARCHAR(50) | | 跟进目的（lookup_items 维护，23项） |
|
||
| content | TEXT | | 跟进内容（最少6字，最多500字） |
|
||
| log_tag | VARCHAR(50) | | 跟进标签：`has_recording`=有录音 / `has_photo`=有图片 / `not_satisfied`=对房源不满意 / `still_considering`=还在考虑 / `ready_to_deposit`=可交定金 |
|
||
| change_detail | JSONB | | 修改跟进专用，格式：`{"field": "grade", "old": "C", "new": "B", "label": "等级"}` |
|
||
| is_public | BOOLEAN | NOT NULL DEFAULT TRUE | FALSE=仅本人及上级可见 |
|
||
| is_deletable | BOOLEAN | NOT NULL DEFAULT TRUE | 敏感信息查看类型为 FALSE，不可删除 |
|
||
| operator_id | UUID | FK→staff, SET NULL | 操作人 |
|
||
| operator_snapshot | JSONB | | `{name, store_group, role}`（防止人员调动后显示异常） |
|
||
| created_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |
|
||
| deleted_at | TIMESTAMPTZ | | 仅 is_deletable=TRUE 时可软删 |
|
||
|
||
**log_type 枚举**：
|
||
```
|
||
written = 写入跟进（经纪人主动写）
|
||
modified = 修改跟进（字段变更自动生成）
|
||
sensitive_view= 敏感信息查看（查看号码等，不可删）
|
||
other = 其他跟进（系统自动：新增私客/状态变更等）
|
||
system = 系统日志
|
||
```
|
||
|
||
**关键索引**：
|
||
```sql
|
||
CREATE INDEX idx_client_follow_logs_client_time ON client_follow_logs(client_id, created_at DESC) WHERE deleted_at IS NULL;
|
||
CREATE INDEX idx_client_follow_logs_type ON client_follow_logs(client_id, log_type, created_at DESC) WHERE deleted_at IS NULL;
|
||
CREATE INDEX idx_client_follow_logs_operator ON client_follow_logs(operator_id, created_at DESC) WHERE deleted_at IS NULL;
|
||
-- 不可删记录（合规审计）
|
||
CREATE INDEX idx_client_follow_sensitive ON client_follow_logs(client_id, created_at DESC) WHERE log_type = 'sensitive_view';
|
||
```
|
||
|
||
---
|
||
|
||
### 3.5 client_follow_log_attachments — 跟进附件
|
||
|
||
| 字段 | 类型 | 约束 | 业务说明 |
|
||
|------|------|------|----------|
|
||
| id | UUID | PK | |
|
||
| follow_log_id | UUID | NOT NULL, FK→client_follow_logs, CASCADE | |
|
||
| file_key | TEXT | NOT NULL | R2/S3 存储路径 |
|
||
| file_name | VARCHAR(255) | NOT NULL | |
|
||
| file_size | INTEGER | NOT NULL | bytes，最大 20MB |
|
||
| file_type | VARCHAR(10) | CHECK | `bmp`/`jpg`/`png`/`gif` |
|
||
| has_location | BOOLEAN | NOT NULL DEFAULT FALSE | 是否含 GPS 位置信息 |
|
||
| sort_order | SMALLINT | NOT NULL DEFAULT 0 | |
|
||
| created_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |
|
||
|
||
---
|
||
|
||
### 3.6 client_viewings — 带看记录（客源侧视图）
|
||
|
||
| 字段 | 类型 | 约束 | 业务说明 |
|
||
|------|------|------|----------|
|
||
| id | UUID | PK | |
|
||
| client_id | UUID | NOT NULL, FK→clients, RESTRICT | |
|
||
| property_id | UUID | NOT NULL, FK→properties, RESTRICT | |
|
||
| viewing_type | VARCHAR(20) | NOT NULL DEFAULT 'viewing' | `appointment`=预约 / `viewing`=带看 / `revisit`=复看 / `empty`=空看 |
|
||
| agent_id | UUID | FK→staff, SET NULL | 主带看经纪人 |
|
||
| companion_ids | UUID[] | | 陪看人员 ID 数组（最多5人） |
|
||
| cooperator_ids | UUID[] | | 合作带看人 ID 数组（最多5人） |
|
||
| scheduled_at | TIMESTAMPTZ | | 预约时间 |
|
||
| viewing_start_at | TIMESTAMPTZ | | 实际带看开始时间 |
|
||
| viewing_end_at | TIMESTAMPTZ | | 结束时间 |
|
||
| situation | TEXT | | 带看情况（必填，≥6字） |
|
||
| client_intent | VARCHAR(20) | | 客户意向：`interested`=感兴趣 / `not_interested`=不感兴趣 / `negotiating`=谈判中 / `cancelled`=取消 |
|
||
| viewing_progress | SMALLINT | | 带看进度（1=一看，2=二看...，冗余字段，触发器维护） |
|
||
| created_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |
|
||
| deleted_at | TIMESTAMPTZ | | |
|
||
| created_by | UUID | FK→staff, SET NULL | |
|
||
|
||
**关键索引**：
|
||
```sql
|
||
CREATE INDEX idx_client_viewings_client ON client_viewings(client_id, viewing_start_at DESC) WHERE deleted_at IS NULL;
|
||
CREATE INDEX idx_client_viewings_property ON client_viewings(property_id) WHERE deleted_at IS NULL;
|
||
CREATE INDEX idx_client_viewings_agent ON client_viewings(agent_id) WHERE deleted_at IS NULL;
|
||
```
|
||
|
||
---
|
||
|
||
### 3.7 client_property_matches — 智能配房
|
||
|
||
| 字段 | 类型 | 约束 | 业务说明 |
|
||
|------|------|------|----------|
|
||
| id | UUID | PK | |
|
||
| client_id | UUID | NOT NULL, FK→clients, CASCADE | |
|
||
| property_id | UUID | NOT NULL, FK→properties, CASCADE | |
|
||
| match_source | VARCHAR(20) | NOT NULL DEFAULT 'recorded' | `recorded`=录客配房（基于录入需求） / `system`=系统配房（算法推荐） |
|
||
| match_group | VARCHAR(30) | | 分组：`quality_layout`=优质户型 / `price_reduced`=降价 / `hot`=热门 / `newly_listed`=新上 |
|
||
| match_score | NUMERIC(5,2) | | 匹配度评分（0-100） |
|
||
| match_reasons | JSONB | | 匹配原因详情，格式：`[{"key": "budget", "match": true}, ...]` |
|
||
| status | VARCHAR(20) | NOT NULL DEFAULT 'suggested' | `suggested`=待推送 / `shared`=已分享 / `rejected`=已反馈不合适 / `viewed`=客户已查看 |
|
||
| shared_at | TIMESTAMPTZ | | 分享时间 |
|
||
| feedback | VARCHAR(50) | | 反馈原因（lookup_items 维护） |
|
||
| calculated_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | 配房计算时间 |
|
||
| created_by | UUID | FK→staff, SET NULL | |
|
||
|
||
**关键索引**：
|
||
```sql
|
||
CREATE UNIQUE INDEX idx_client_matches_pair ON client_property_matches(client_id, property_id);
|
||
CREATE INDEX idx_client_matches_client ON client_property_matches(client_id, match_source, match_group);
|
||
CREATE INDEX idx_client_matches_status ON client_property_matches(client_id, status) WHERE status != 'rejected';
|
||
```
|
||
|
||
---
|
||
|
||
### 3.8 client_status_logs — 状态变更日志（不可删）
|
||
|
||
| 字段 | 类型 | 约束 | 业务说明 |
|
||
|------|------|------|----------|
|
||
| id | UUID | PK | |
|
||
| client_id | UUID | NOT NULL, FK→clients, RESTRICT | |
|
||
| change_type | VARCHAR(30) | NOT NULL | `status_change`=改状态 / `grade_change`=改等级 / `to_public`=转公客 / `to_transacted`=转成交 / `to_invalid`=转无效 / `owner_change`=改归属人 / `source_change`=改来源 |
|
||
| old_value | JSONB | | 变更前快照，格式：`{"status": "buying", "label": "求购"}` |
|
||
| new_value | JSONB | | 变更后快照 |
|
||
| reason | TEXT | | 变更理由（改状态必填，最多200字） |
|
||
| operator_id | UUID | NOT NULL, FK→staff, RESTRICT | |
|
||
| operated_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |
|
||
| ⚠️ 无 deleted_at | — | — | 此表记录**不可删除** |
|
||
|
||
**关键索引**：
|
||
```sql
|
||
CREATE INDEX idx_client_status_logs_client ON client_status_logs(client_id, operated_at DESC);
|
||
CREATE INDEX idx_client_status_logs_type ON client_status_logs(change_type, operated_at DESC);
|
||
```
|
||
|
||
---
|
||
|
||
### 3.9 client_favorite_folders — 私客收藏夹
|
||
|
||
| 字段 | 类型 | 约束 | 业务说明 |
|
||
|------|------|------|----------|
|
||
| id | UUID | PK | |
|
||
| staff_id | UUID | NOT NULL, FK→staff, CASCADE | 收藏夹所属经纪人 |
|
||
| name | VARCHAR(10) | NOT NULL | 收藏夹名称，最多10字 |
|
||
| is_default | BOOLEAN | NOT NULL DEFAULT FALSE | 系统默认收藏夹 |
|
||
| sort_order | INTEGER | NOT NULL DEFAULT 0 | |
|
||
| created_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |
|
||
| deleted_at | TIMESTAMPTZ | | |
|
||
|
||
```sql
|
||
CREATE INDEX idx_favorite_folders_staff ON client_favorite_folders(staff_id) WHERE deleted_at IS NULL;
|
||
-- 每个经纪人只能有一个默认收藏夹
|
||
CREATE UNIQUE INDEX idx_favorite_folders_default ON client_favorite_folders(staff_id) WHERE is_default = TRUE AND deleted_at IS NULL;
|
||
```
|
||
|
||
---
|
||
|
||
### 3.10 client_folder_items — 收藏夹中的客源
|
||
|
||
| 字段 | 类型 | 约束 | 业务说明 |
|
||
|------|------|------|----------|
|
||
| folder_id | UUID | NOT NULL, FK→client_favorite_folders, CASCADE | |
|
||
| client_id | UUID | NOT NULL, FK→clients, CASCADE | |
|
||
| added_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |
|
||
| PRIMARY KEY | (folder_id, client_id) | | |
|
||
|
||
```sql
|
||
CREATE INDEX idx_folder_items_client ON client_folder_items(client_id);
|
||
```
|
||
|
||
---
|
||
|
||
### 3.11 client_school_preferences — 意向学校（多对多）
|
||
|
||
> 单独拆表便于学校搜索，避免文本字段模糊查询。
|
||
|
||
| 字段 | 类型 | 约束 | 业务说明 |
|
||
|------|------|------|----------|
|
||
| id | UUID | PK | |
|
||
| requirement_id | UUID | NOT NULL, FK→client_requirements, CASCADE | |
|
||
| school_id | UUID | FK→schools, SET NULL | 从学校表选择，允许为 NULL（自由输入） |
|
||
| school_name | VARCHAR(100) | NOT NULL | 学校名称（当 school_id 为 NULL 时为手动输入） |
|
||
| created_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |
|
||
|
||
```sql
|
||
CREATE INDEX idx_school_prefs_requirement ON client_school_preferences(requirement_id);
|
||
```
|
||
|
||
---
|
||
|
||
## 四、枚举常量
|
||
|
||
### clients.status（客源状态）
|
||
|
||
```
|
||
buying = 求购（私客活跃态）
|
||
renting = 求租（私客活跃态）
|
||
buy_or_rent = 租购（私客活跃态）
|
||
suspended = 暂缓（暂时无需求，不计入活跃统计）
|
||
bought = 已购（成交客：我购）
|
||
rented_done = 已租（成交客：我租）
|
||
public = 公客（已转入公客池）
|
||
invalid = 无效（号码无效/无意向等）
|
||
```
|
||
|
||
**状态流转规则**：
|
||
```
|
||
buying/renting/buy_or_rent
|
||
→ suspended （改状态操作，可逆）
|
||
→ public （手动转公 or 超时自动转公，不可逆）
|
||
→ bought/rented_done （转成交，不可逆）
|
||
→ invalid （转无效，需经理审批后可恢复）
|
||
```
|
||
|
||
### clients.grade（等级）
|
||
|
||
```
|
||
A_urgent = A(急迫)
|
||
A = A
|
||
B = B(较强)
|
||
C = C(一般，默认值)
|
||
D = D(较弱)
|
||
E = E(暂不关注)
|
||
```
|
||
|
||
### client_status_logs.change_type（变更类型）
|
||
|
||
```
|
||
status_change = 改状态（含改等级时同时改状态的情况）
|
||
grade_change = 改等级
|
||
to_public = 转公客（manual=手动 or auto=自动）
|
||
to_transacted = 转成交（记录成交信息）
|
||
to_invalid = 转无效（含无效原因）
|
||
owner_change = 改归属人
|
||
source_change = 改来源
|
||
merge = 合并客源（被合并的记录保留日志）
|
||
```
|
||
|
||
### clients.activity_level（活跃度分层，系统计算）
|
||
|
||
| 值 | 含义 | 触发条件（示例，以运营配置为准） |
|
||
|----|------|------|
|
||
| `new_matched` | 新配偶 | 录入后 3 天内 |
|
||
| `active_7d` | 7日活跃 | 最后跟进在 7 天内 |
|
||
| `active_30d` | 30日活跃 | 最后跟进在 30 天内 |
|
||
| `active_90d` | 90日活跃 | 最后跟进在 90 天内 |
|
||
| `expiring` | 即将过期 | 距自动转公还有 N 天 |
|
||
| `frozen` | 冻结（暂缓） | status = suspended |
|
||
| `invalid` | 无效 | status = invalid |
|
||
|
||
---
|
||
|
||
## 五、查询模式
|
||
|
||
### 5.1 私客列表页（求购 Tab）核心查询
|
||
|
||
```sql
|
||
-- 典型：当前经纪人名下 + 求购状态 + 等级筛选 + 按最后跟进排序
|
||
SELECT c.id, c.status, c.grade, c.activity_level,
|
||
c.last_follow_at, c.commission_date, c.buying_purpose,
|
||
cc.name AS contact_name, -- JOIN 主联系人
|
||
s.name AS owner_name, ou.name AS org_unit_name,
|
||
COUNT(cpm.id) AS match_count -- 智能配房数量
|
||
FROM clients c
|
||
JOIN client_contacts cc ON cc.client_id = c.id AND cc.sort_order = 0 AND cc.deleted_at IS NULL
|
||
JOIN staff s ON s.id = c.owner_id
|
||
JOIN org_units ou ON ou.id = c.org_unit_id
|
||
LEFT JOIN client_property_matches cpm ON cpm.client_id = c.id AND cpm.status != 'rejected'
|
||
WHERE c.client_type = 'private'
|
||
AND c.owner_id = :current_staff_id -- 与我相关
|
||
AND c.status IN ('buying', 'buy_or_rent')
|
||
AND c.deleted_at IS NULL
|
||
GROUP BY c.id, cc.name, s.name, ou.name
|
||
ORDER BY c.last_follow_at DESC NULLS LAST
|
||
LIMIT 20 OFFSET :offset;
|
||
```
|
||
|
||
### 5.2 重复客源检测（录入/编辑时触发）
|
||
|
||
```sql
|
||
-- 手机号哈希碰撞检测（私客、成交客、公客三池同时检查）
|
||
SELECT c.id, c.client_type, c.status, c.client_no,
|
||
cc.name AS contact_name
|
||
FROM client_contacts cc
|
||
JOIN clients c ON cc.client_id = c.id
|
||
WHERE cc.phone_hash = :new_phone_hash
|
||
AND cc.deleted_at IS NULL
|
||
AND c.deleted_at IS NULL
|
||
AND c.status != 'invalid';
|
||
```
|
||
|
||
### 5.3 活跃度批量更新（Celery 定时任务，每日凌晨执行）
|
||
|
||
```sql
|
||
-- 更新活跃度（以7日活跃为例）
|
||
UPDATE clients
|
||
SET activity_level = 'active_7d',
|
||
updated_at = NOW()
|
||
WHERE client_type = 'private'
|
||
AND status NOT IN ('invalid', 'public', 'bought', 'rented_done')
|
||
AND last_follow_at >= NOW() - INTERVAL '7 days'
|
||
AND deleted_at IS NULL;
|
||
```
|
||
|
||
### 5.4 私客自动转公（超时无跟进，Celery 定时任务）
|
||
|
||
```sql
|
||
-- 查询应自动转公的私客（阈值由运营配置，假设30天）
|
||
SELECT id FROM clients
|
||
WHERE client_type = 'private'
|
||
AND status IN ('buying', 'renting', 'buy_or_rent')
|
||
AND last_follow_at < NOW() - INTERVAL '30 days'
|
||
AND is_protected = FALSE
|
||
AND deleted_at IS NULL;
|
||
-- 后续在 Application 层批量更新 client_type='public', transfer_to_public_type='auto'
|
||
```
|
||
|
||
---
|
||
|
||
## 六、触发器
|
||
|
||
### 6.1 last_follow_at 自动维护
|
||
|
||
```sql
|
||
-- 每次写入跟进日志时，自动更新 clients.last_follow_at
|
||
CREATE OR REPLACE FUNCTION update_client_last_follow()
|
||
RETURNS TRIGGER AS $$
|
||
BEGIN
|
||
IF NEW.log_type = 'written' THEN
|
||
UPDATE clients
|
||
SET last_follow_at = NEW.created_at,
|
||
last_active_at = NEW.created_at,
|
||
updated_at = NOW()
|
||
WHERE id = NEW.client_id;
|
||
END IF;
|
||
RETURN NEW;
|
||
END;
|
||
$$ LANGUAGE plpgsql;
|
||
|
||
CREATE TRIGGER trg_client_last_follow
|
||
AFTER INSERT ON client_follow_logs
|
||
FOR EACH ROW EXECUTE FUNCTION update_client_last_follow();
|
||
```
|
||
|
||
### 6.2 viewing_progress 自动维护
|
||
|
||
```sql
|
||
-- 每次新增带看记录时，自动更新 clients 的带看进度冗余字段
|
||
CREATE OR REPLACE FUNCTION update_client_viewing_progress()
|
||
RETURNS TRIGGER AS $$
|
||
BEGIN
|
||
UPDATE clients
|
||
SET updated_at = NOW()
|
||
WHERE id = NEW.client_id;
|
||
-- Application 层根据 COUNT(viewings) 计算具体进度
|
||
RETURN NEW;
|
||
END;
|
||
$$ LANGUAGE plpgsql;
|
||
|
||
CREATE TRIGGER trg_client_viewing_progress
|
||
AFTER INSERT ON client_viewings
|
||
FOR EACH ROW EXECUTE FUNCTION update_client_viewing_progress();
|
||
```
|
||
|
||
---
|
||
|
||
## 七、禁止操作
|
||
|
||
- ❌ **严禁硬删除 clients 记录**：无效/转公客/成交客均通过 status 和 soft delete 处理，历史跟进/带看依赖外键
|
||
- ❌ **严禁删除 client_status_logs**：状态变更为不可变审计日志
|
||
- ❌ **严禁删除 log_type='sensitive_view' 的跟进记录**：必须通过 `is_deletable=FALSE` 约束在应用层拦截
|
||
- ❌ **严禁明文存储联系人手机号**：必须走 `EncryptedPhoneField`，`phone_hash` 用于索引和重复检测
|
||
- ❌ **严禁跳过状态机流转**：如私客不可直接跳过「求购」变为「无效」而不生成 status log
|
||
- ❌ **严禁在没有 `client_type` 过滤的情况下查询客源列表**：私客/公客/成交客数据量均较大，必须按类型隔离查询
|
||
- ❌ **严禁查询 clients 时不带 `deleted_at IS NULL`**：软删除过滤必须存在
|