# DATA_MODEL 注释补全规范 v1.0

> **作者**: Backend Engineer
> **日期**: 2026-04-29
> **目标读者**: 产品经理 / 数据模型维护者
> **目的**: 统一 `/DATA_MODEL/*.md` 中所有字段的中文注释格式与覆盖度，使其能机械化同步到 Django 模型代码与 OpenAPI 文档

---

## 一、背景

当前 Django 项目骨架已搭建完成（74 个模型 / 781 个字段），但模型代码中**几乎没有任何中文字段说明**：

| 维度 | 现状 |
|---|---|
| `verbose_name="中文名"`（字段中文名） | 0 / 781 |
| `help_text="..."`（字段详细说明） | 14 / 781 |
| `Meta.verbose_name`（模型中文名） | 0 / 74 |
| 模型类中文 docstring | 0 / 74 |

代码侧无法凭空生成业务语义，必须**以 DATA_MODEL 为唯一权威源**，由产品经理补全后，由开发同步到代码。

DATA_MODEL 现有的业务字段注释覆盖率约 **70%**——大量业务字段已有清晰的中文说明（这是本规范的范本），缺口集中在**技术元数据字段**和少数边角字段。本规范定义补全标准。

---

## 二、规范总览

### 2.1 必须补全的字段范围

每个表的 **每一个字段** 都必须有中文注释，包括：

- ✅ 业务字段（property.name / client.phone 等）— 大多已有
- ✅ 状态枚举字段（status / type / level 等）— 大多已有
- ✅ 外键字段（complex_id / staff_id 等）— 部分缺失
- ⚠️ **技术元数据字段（重点缺口）**：
  - `id` / `uuid` — 主键
  - `created_at` / `updated_at` / `deleted_at` — 时间戳
  - `created_by` / `updated_by` — 操作人
  - `version` — 乐观锁版本号
  - `search_vector` — 全文检索向量
  - `*_hash` — 加密字段配套哈希
  - `*_enc` — 加密字段密文
  - `sort_order` — 排序权重

### 2.2 表级别也需补全

每张表必须有：

- **表名中文标题**（已有，无需改）
- **业务摘要**（1-2 句话说明该表的业务作用，已有大部分）
- **关键业务规则**（如"不可删除"、"按月分区"等，已有大部分）

---

## 三、字段注释格式（统一模板）

### 3.1 标准 Markdown 表格格式

DATA_MODEL 现有格式已经很好，**继续沿用**：

```markdown
| 字段 | 类型 | 约束 | 默认 | 业务说明 |
|------|------|------|------|----------|
| id | UUID | PK | gen_random_uuid() | 主键（系统生成，业务无关） |
| name | varchar(100) | NOT NULL | - | 房源名称（如"翠湖天地 3 号楼 1502 室"，展示给客户） |
| status | varchar(20) | NOT NULL | 'for_sale' | 房源状态：for_sale=在售 / sold=已成交 / off_market=下架（详见 ENUMS.md） |
```

**关键要求**：

1. **每行的"业务说明"列必须填写**，不允许留空或只写 "-"
2. **业务说明要包含三类信息**（按重要性）：
   - **是什么**（必填）：如"房源名称"、"主键"
   - **示例值**（推荐）：如"如'翠湖天地 3 号楼 1502 室'"
   - **业务规则**（按需）：如"展示给客户"、"系统生成"、"不可修改"

### 3.2 SQL DDL 内联注释（DDL 块也要写）

DATA_MODEL 中的 SQL DDL 块也必须有中文 `-- 注释`：

```sql
CREATE TABLE properties (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),  -- 主键（系统生成）
    name            VARCHAR(100) NOT NULL,                       -- 房源名称
    status          VARCHAR(20) NOT NULL DEFAULT 'for_sale',     -- 房源状态（详见 ENUMS）
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),          -- 记录创建时间（系统自动）
    updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),          -- 记录最后更新时间（系统自动）
    deleted_at      TIMESTAMPTZ,                                 -- 软删除时间戳；NULL=未删除
    created_by      UUID REFERENCES staff(id),                   -- 创建人（FK 到员工表）
    updated_by      UUID REFERENCES staff(id),                   -- 最后修改人
    version         INTEGER NOT NULL DEFAULT 1                   -- 乐观锁版本号（每次更新 +1）
);
```

---

## 四、技术元数据字段标准注释库

**这是本规范的核心交付物**——所有表的元数据字段使用统一中文注释，PM 不必逐个想，开发也能机械化套用。

### 4.1 通用元数据字段（每张表都要）

| 字段名 | 类型 | 标准中文注释 |
|---|---|---|
| `id` | UUID / BIGINT | 主键（系统生成，业务无关） |
| `created_at` | TIMESTAMPTZ | 记录创建时间（系统自动） |
| `updated_at` | TIMESTAMPTZ | 记录最后更新时间（系统自动） |
| `deleted_at` | TIMESTAMPTZ NULL | 软删除时间戳；NULL=未删除，非 NULL=已软删除 |
| `created_by` | FK → staff/account | 创建人（操作员工） |
| `updated_by` | FK → staff/account | 最后修改人（操作员工） |
| `version` | INTEGER | 乐观锁版本号（每次更新 +1，用于并发冲突检测） |

### 4.2 加密字段配套（涉及手机号/身份证等敏感数据）

| 字段名 | 类型 | 标准中文注释 |
|---|---|---|
| `phone_enc` | BYTEA | 手机号密文（AES-256-GCM 加密，不可直接查询） |
| `phone_hash` | CHAR(64) | 手机号哈希（SHA-256，用于唯一性约束和精确查询） |
| `id_card_enc` | BYTEA | 身份证号密文（AES-256-GCM 加密） |
| `id_card_hash` | CHAR(64) | 身份证号哈希（SHA-256） |

### 4.3 全文检索字段

| 字段名 | 类型 | 标准中文注释 |
|---|---|---|
| `search_vector` | TSVECTOR | 全文检索向量（由触发器或 Celery 自动维护） |

### 4.4 排序与状态字段

| 字段名 | 类型 | 标准中文注释 |
|---|---|---|
| `sort_order` | INTEGER | 排序权重（数值越小越靠前） |
| `is_active` | BOOLEAN | 是否启用（true=启用，false=禁用） |
| `is_deleted` | BOOLEAN | 是否已删除（与 deleted_at 二选一，按表设计） |

### 4.5 计分/统计字段（多见于楼盘、房源完成度）

| 字段名 | 类型 | 标准中文注释 |
|---|---|---|
| `total_score` | SMALLINT | 总分（0-100；其他 score_* 字段加权汇总） |
| `calculated_at` | TIMESTAMPTZ | 上次计算时间（由 Celery 异步任务更新，非实时） |

---

## 五、业务字段注释三段式（用于补全缺失项）

对于业务字段，使用**三段式**结构（用 / 或 ； 分隔）：

```
[字段中文名]：[示例值或取值范围]；[业务规则或备注]
```

**示例**：

| 原始（缺失） | 补全后 |
|---|---|
| `floor` | `所在楼层：1=底层；总楼层不超过 total_floors（CheckConstraint 校验）` |
| `built_year` | `建成年份：如 2018；可空（老房源无记录）` |
| `is_only_house` | `是否唯一住房：true=唯一/false=非唯一/NULL=未确认；影响交易税费计算` |
| `completeness_score` | `房源完整度评分：0-100；由 Celery 异步计算，非实时；前端列表页展示徽章` |
| `commission_rate` | `佣金费率：百分比，如 2.5 表示 2.5%；范围 0-10` |
| `protection_end_at` | `保护期结束时间：null=永久保护；保护期内禁止其他经纪人接单` |

---

## 六、状态/枚举字段注释规范

枚举字段必须**列出所有可能值的中英对照**：

```markdown
| status | varchar(20) | NOT NULL | 'for_sale' | 房源状态：for_sale=在售 / sold=已成交 / rented=已出租 / off_market=下架 / pending=审核中（详见 ENUMS.md §房源状态） |
```

**规则**：
1. 使用 `英文值=中文名` 的对照
2. 多个值用 ` / ` 分隔
3. 末尾加 `（详见 ENUMS.md §章节名）` 引用枚举权威源
4. 默认值如有业务含义需说明（如"新建房源默认 for_sale"）

---

## 七、外键字段注释规范

```markdown
| complex_id | UUID | FK → complexes.id | NOT NULL | 所属楼盘（关联 complexes 表；房源必须挂在楼盘下） |
| seller_agent_id | UUID | FK → staff.id NULL | NULL | 出售经纪人（接单后填写；ON DELETE SET NULL） |
| created_by | UUID | FK → staff.id NULL | NULL | 创建人（系统自动从登录会话填写） |
```

**规则**：
1. 必须说明**关联表**（"关联 X 表"）
2. 必须说明**业务含义**（"所属楼盘"、"出售经纪人"，而非只写"complex_id"）
3. 可空字段说明**何时为空**（"接单后填写"、"老数据无此字段"）

---

## 八、表级别补全要求

每张表在 DATA_MODEL 中必须有：

```markdown
### 3.X `table_name` — 中文表名

**业务作用**：[一句话说明这张表存什么、为什么需要]

**关键业务规则**：
- 规则 1（如：手机号必须加密存储）
- 规则 2（如：跟进日志不可删除）
- 规则 3（如：每月自动分区）

**字段表**：
[标准字段表格]

**索引说明**：
- idx_xxx：[为什么建这个索引，支撑什么查询]
```

---

## 九、补全工作清单（PM 待办）

### 9.1 待补全文件清单

| DATA_MODEL 文件 | 当前覆盖率（业务字段） | 主要缺口 | 优先级 |
|---|---|---|---|
| DATA_MODEL_PROPERTY.md | ~75% | 技术元数据字段；部分 shop_* 字段说明；保护期字段 | P0 |
| DATA_MODEL_CLIENT.md | ~70% | 跟进日志字段；匹配字段；技术元数据 | P0 |
| DATA_MODEL_COMPLEX.md | ~80% | 楼栋/单元字段；技术元数据 | P1 |
| DATA_MODEL_ORG.md | ~80% | 员工日志字段；技术元数据 | P1 |
| DATA_MODEL_LOGIN.md（含 ACCOUNT） | ~70% | 登录尝试/会话字段；技术元数据 | P0 |
| DATA_MODEL_PERMISSION.md | ~85% | 权限种子数据字段说明；技术元数据 | P1 |
| DATA_MODEL_SETTING.md | ~75% | LookupItem 字段；技术元数据 | P2 |
| DATA_MODEL_PUBLIC.md（含 TENANT/RELEASE） | ~70% | tenant/domain/release 字段；技术元数据 | P1 |

### 9.2 检查清单（PM 自检）

补完后请逐文件检查：

- [ ] 每个字段表的"业务说明"列**全部填写**，无空行无 "-"
- [ ] 所有技术元数据字段（id/created_at/...）使用 §四 的标准注释
- [ ] 所有枚举字段列出全部取值的中英对照
- [ ] 所有外键字段说明关联表 + 业务含义
- [ ] 每张表有"业务作用"段落
- [ ] 每张表有"关键业务规则"段落（即使只有 1 条）
- [ ] DDL 块的每行 SQL 都有 `-- 中文注释`

---

## 十、补全完成后开发同步流程

PM 补完后，开发会按以下顺序同步到 Django 代码（无需 PM 介入）：

| 步骤 | 同步目标 | 来源 | 工时估算 |
|---|---|---|---|
| 1 | `Meta.verbose_name` / `verbose_name_plural` | 表名（"### 3.X xxx — 中文表名"中的中文部分） | 30 分钟 |
| 2 | 模型类 docstring | 表的"业务作用" + "关键业务规则" | 1 小时 |
| 3 | 字段 `verbose_name="..."` | 字段表"业务说明"的第一段 | 3-4 小时 |
| 4 | 字段 `help_text="..."`（关键字段） | 字段表"业务说明"的二/三段（示例 + 规则） | 2 小时 |

**总计开发工时**：约 7-8 小时，分批次按 app commit。

代码层面这些注释会被以下系统自动消费：
- **Django Admin**：列表页/表单页直接显示中文表名和字段名
- **drf-spectacular**：生成 OpenAPI 文档时 `verbose_name → title`、`help_text → description`
- **Django shell / 报错信息**：使用中文字段名

---

## 十一、范例：一张完整规范的表（参考标准）

参考 `DATA_MODEL_PROPERTY.md` §3.X `properties` 表，补全后应类似：

```markdown
### 3.1 `properties` — 房源主表

**业务作用**：存储经纪公司管理的所有待售/待租房屋的核心信息，是整个房源管理模块的根表。

**关键业务规则**：
- 软删除：通过 `deleted_at` 标记，绝不物理删除（合规要求）
- 楼层校验：`floor <= total_floors`（CheckConstraint）
- 完整度异步：`completeness_score` 由 Celery 任务计算，非实时
- 全文检索：`search_vector` 由数据库触发器自动维护

**字段表**：

| 字段 | 类型 | 约束 | 默认 | 业务说明 |
|------|------|------|------|----------|
| id | UUID | PK | gen_random_uuid() | 主键（系统生成，业务无关） |
| property_type | varchar(30) | NOT NULL | - | 房源类型：apartment=住宅 / villa=别墅 / shop=商铺 / office=写字楼（详见 ENUMS） |
| status | varchar(20) | NOT NULL | 'for_sale' | 房源状态：for_sale=在售 / sold=已成交 / rented=已出租 / off_market=下架（详见 ENUMS） |
| name | varchar(100) | NOT NULL | - | 房源名称（如"翠湖天地 3 号楼 1502 室"，展示给客户） |
| complex_id | UUID | FK → complexes.id | NOT NULL | 所属楼盘（房源必须挂在楼盘下） |
| floor | smallint | NOT NULL | - | 所在楼层（1=底层；不超过 total_floors） |
| total_floors | smallint | NOT NULL | - | 楼栋总层数 |
| sale_price | decimal(12,2) | NULL | - | 挂牌售价：单位元；可空（仅出租房源） |
| has_elevator | boolean | NULL | - | 是否有电梯：true=有 / false=无 / NULL=未确认 |
| seller_agent_id | UUID | FK → staff.id NULL | NULL | 出售经纪人（接单后填写，ON DELETE SET NULL） |
| completeness_score | smallint | NOT NULL | 0 | 房源完整度评分：0-100；由 Celery 异步计算，非实时 |
| created_at | TIMESTAMPTZ | NOT NULL | NOW() | 记录创建时间（系统自动） |
| updated_at | TIMESTAMPTZ | NOT NULL | NOW() | 记录最后更新时间（系统自动） |
| deleted_at | TIMESTAMPTZ | NULL | NULL | 软删除时间戳；NULL=未删除 |
| created_by | UUID | FK → staff.id NULL | NULL | 创建人（系统自动从登录会话填写） |
| version | integer | NOT NULL | 1 | 乐观锁版本号（每次更新 +1） |
| search_vector | TSVECTOR | NULL | NULL | 全文检索向量（由触发器自动维护） |
```

---

## 十二、变更与维护

- 本规范由开发与 PM 共同维护
- DATA_MODEL 任何新增字段必须遵循本规范
- 字段含义变更时，必须同步更新 DATA_MODEL 注释 → 触发开发同步代码注释
- 本规范版本变更需 PM + 开发双方确认

**联系人**：
- 规范问题 → Backend Engineer
- 业务字段含义 → Product Manager
- 枚举权威 → ENUMS.md