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

data model注释补全

Browse Source
This commit is contained in:
Shen Wei
2026-04-30 06:57:02 +08:00
parent eada3af824
commit 91fc0b06d6
5 changed files with 216 additions and 172 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
Project/fonrey/DATA_MODEL/DATA_MODEL_CLIENT.md
View File

@@ -66,7 +66,7 @@ Staff (员工)
| 字段 | 类型 | 约束 | 业务说明 |
|------|------|------|----------|
| id | UUID | PK | |
| 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' | 见下方枚举 |
@@ -102,11 +102,11 @@ Staff (员工)
| 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 | |
| created_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | 记录创建时间（系统自动） |
| updated_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | 记录最后更新时间（系统自动） |
| deleted_at | TIMESTAMPTZ | | 软删除时间戳；NULL=未删除，非NULL=已软删除 |
| created_by | UUID | FK→staff, SET NULL | 创建人（操作员工） |
| updated_by | UUID | FK→staff, SET NULL | 最后修改人（操作员工） |
| version | INTEGER | NOT NULL DEFAULT 1 | 乐观锁版本号；每次 UPDATE +1；应用层检测 0 行受影响时抛 ConflictError |
**关键索引**：
@@ -127,8 +127,8 @@ CREATE INDEX idx_clients_last_follow ON clients(last_follow_at DESC NULLS LAST)
| 字段 | 类型 | 约束 | 业务说明 |
|------|------|------|----------|
| id | UUID | PK | |
| client_id | UUID | NOT NULL, FK→clients, CASCADE | |
| id | UUID | PK | 主键（系统生成，业务无关） |
| client_id | UUID | NOT NULL, FK→clients, CASCADE | 所属客源（关联 clients 表，联系人随客源级联删除） |
| 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`=女士 |
@@ -137,14 +137,14 @@ CREATE INDEX idx_clients_last_follow ON clients(last_follow_at DESC NULLS LAST)
| 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) | | |
| phone2_hash | VARCHAR(64) | | 备用电话2哈希（SHA-256，用于重复检测） |
| 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 | |
| created_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | 记录创建时间（系统自动） |
| updated_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | 记录最后更新时间（系统自动） |
| deleted_at | TIMESTAMPTZ | | 软删除时间戳；NULL=未删除（不影响客源本身） |
| created_by | UUID | FK→staff, SET NULL | 创建人（操作员工） |
**关键索引**：
```sql
@@ -167,8 +167,8 @@ CREATE INDEX idx_client_contacts_client ON client_contacts(client_id) WHERE dele
| 字段 | 类型 | 约束 | 业务说明 |
|------|------|------|----------|
| id | UUID | PK | |
| client_id | UUID | NOT NULL, FK→clients, CASCADE | |
| id | UUID | PK | 主键（系统生成，业务无关） |
| client_id | UUID | NOT NULL, FK→clients, CASCADE | 所属客源（关联 clients 表，需求随客源级联删除） |
| requirement_type | VARCHAR(20) | NOT NULL | `second_hand`=二手 / `new_house`=新房 / `rental`=租房 |
| is_primary | BOOLEAN | NOT NULL DEFAULT TRUE | 是否为主需求（用于列表展示） |
| budget_min | NUMERIC(12,2) | | 最低预算（万元/元，依据需求类型） |
@@ -188,8 +188,8 @@ CREATE INDEX idx_client_contacts_client ON client_contacts(client_id) WHERE dele
| 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() | |
| created_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | 记录创建时间（系统自动） |
| updated_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | 记录最后更新时间（系统自动） |
**关键索引**：
```sql
@@ -208,8 +208,8 @@ CREATE INDEX idx_client_requirements_area ON client_requirements(area_min, area_
| 字段 | 类型 | 约束 | 业务说明 |
|------|------|------|----------|
| id | UUID | PK | |
| client_id | UUID | NOT NULL, FK→clients, CASCADE | |
| id | UUID | PK | 主键（系统生成，业务无关） |
| client_id | UUID | NOT NULL, FK→clients, CASCADE | 所属客源（关联 clients 表，跟进日志随客源级联删除） |
| log_type | VARCHAR(30) | NOT NULL | 见下方枚举 |
| purpose | VARCHAR(50) | | 跟进目的（lookup_items 维护，23项） |
| content | TEXT | | 跟进内容（最少6字，最多500字） |
@@ -219,8 +219,8 @@ CREATE INDEX idx_client_requirements_area ON client_requirements(area_min, area_
| 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 时可软删 |
| created_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | 记录创建时间（系统自动） |
| deleted_at | TIMESTAMPTZ | | 软删除时间戳；仅 is_deletable=TRUE 时可软删 |
**log_type 枚举**：
```
@@ -246,15 +246,15 @@ CREATE INDEX idx_client_follow_sensitive ON client_follow_logs(client_id, create
| 字段 | 类型 | 约束 | 业务说明 |
|------|------|------|----------|
| id | UUID | PK | |
| follow_log_id | UUID | NOT NULL, FK→client_follow_logs, CASCADE | |
| 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_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() | |
| sort_order | SMALLINT | NOT NULL DEFAULT 0 | 附件排序顺序 |
| created_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | 记录创建时间（系统自动） |
---
@@ -262,9 +262,9 @@ CREATE INDEX idx_client_follow_sensitive ON client_follow_logs(client_id, create
| 字段 | 类型 | 约束 | 业务说明 |
|------|------|------|----------|
| id | UUID | PK | |
| client_id | UUID | NOT NULL, FK→clients, RESTRICT | |
| property_id | UUID | NOT NULL, FK→properties, RESTRICT | |
| 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人） |
@@ -275,9 +275,9 @@ CREATE INDEX idx_client_follow_sensitive ON client_follow_logs(client_id, create
| 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 | |
| created_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | 记录创建时间（系统自动） |
| deleted_at | TIMESTAMPTZ | | 软删除时间戳；带看记录可软删除 |
| created_by | UUID | FK→staff, SET NULL | 创建人（操作员工） |
**关键索引**：
```sql
@@ -292,9 +292,9 @@ CREATE INDEX idx_client_viewings_agent ON client_viewings(agent_id) WHERE delete
| 字段 | 类型 | 约束 | 业务说明 |
|------|------|------|----------|
| id | UUID | PK | |
| client_id | UUID | NOT NULL, FK→clients, CASCADE | |
| property_id | UUID | NOT NULL, FK→properties, CASCADE | |
| 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） |
@@ -303,7 +303,7 @@ CREATE INDEX idx_client_viewings_agent ON client_viewings(agent_id) WHERE delete
| shared_at | TIMESTAMPTZ | | 分享时间 |
| feedback | VARCHAR(50) | | 反馈原因（lookup_items 维护） |
| calculated_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | 配房计算时间 |
| created_by | UUID | FK→staff, SET NULL | |
| created_by | UUID | FK→staff, SET NULL | 触发配房操作的员工（录客配房时记录，系统配房可为NULL） |
**关键索引**：
```sql
@@ -318,14 +318,14 @@ CREATE INDEX idx_client_matches_status ON client_property_matches(client_id, sta
| 字段 | 类型 | 约束 | 业务说明 |
|------|------|------|----------|
| id | UUID | PK | |
| client_id | UUID | NOT NULL, FK→clients, RESTRICT | |
| id | UUID | PK | 主键（系统生成，业务无关） |
| client_id | UUID | NOT NULL, FK→clients, RESTRICT | 所属客源（状态日志永久保留，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() | |
| operator_id | UUID | NOT NULL, FK→staff, RESTRICT | 操作人（必填，状态变更审计用） |
| operated_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | 操作时间（系统自动记录） |
| ⚠️ 无 deleted_at | — | — | 此表记录**不可删除** |
**关键索引**：
@@ -340,13 +340,13 @@ CREATE INDEX idx_client_status_logs_type ON client_status_logs(change_type, oper
| 字段 | 类型 | 约束 | 业务说明 |
|------|------|------|----------|
| id | UUID | PK | |
| 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 | | |
| sort_order | INTEGER | NOT NULL DEFAULT 0 | 收藏夹显示顺序（升序） |
| created_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | 记录创建时间（系统自动） |
| deleted_at | TIMESTAMPTZ | | 软删除时间戳；NULL=未删除 |
```sql
CREATE INDEX idx_favorite_folders_staff ON client_favorite_folders(staff_id) WHERE deleted_at IS NULL;
@@ -360,10 +360,10 @@ CREATE UNIQUE INDEX idx_favorite_folders_default ON client_favorite_folders(staf
| 字段 | 类型 | 约束 | 业务说明 |
| ----------- | ---------------------- | --------------------------------------------- | ---- |
| 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) | | |
| 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);
@@ -377,11 +377,11 @@ CREATE INDEX idx_folder_items_client ON client_folder_items(client_id);
| 字段 | 类型 | 约束 | 业务说明 |
|------|------|------|----------|
| id | UUID | PK | |
| requirement_id | UUID | NOT NULL, FK→client_requirements, CASCADE | |
| 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() | |
| created_at | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | 记录创建时间（系统自动） |
```sql
CREATE INDEX idx_school_prefs_requirement ON client_school_preferences(requirement_id);