Files

Shen Wei eada3af824 注释补全

2026-04-30 06:33:50 +08:00

14 KiB

Raw Blame History

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 现有格式已经很好，继续沿用：

| 字段 | 类型 | 约束 | 默认 | 业务说明 |
|------|------|------|------|----------|
| 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） |

关键要求：

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

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

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

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=永久保护；保护期内禁止其他经纪人接单`

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

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

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

规则：

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

七、外键字段注释规范

| 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 | 创建人（系统自动从登录会话填写） |

规则：

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

八、表级别补全要求

每张表在 DATA_MODEL 中必须有：

### 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 表，补全后应类似：

### 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

14 KiB Raw Blame History Unescape Escape