321 lines
14 KiB
Markdown
321 lines
14 KiB
Markdown
# 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
|