注释补全

2026-04-30 06:33:50 +08:00
parent c961c6a394
commit eada3af824
5 changed files with 1287 additions and 299 deletions
--- a/Project/fonrey/规范/DATA_MODEL_注释补全规范_v1.md
+++ b/Project/fonrey/规范/DATA_MODEL_注释补全规范_v1.md
@@ -0,0 +1,320 @@
+# 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