# 数据库实体验证最佳实践

## 问题概述
在开发过程中，经常出现实体类字段与数据库表结构不一致的情况。这通常是由于在不了解真实数据库结构的情况下，凭经验或猜测添加字段导致的。

## 核心原则
**始终以数据库文档为准**：在创建或修改实体类之前，必须先查阅数据库设计文档，确保实体类与数据库表结构完全一致。

## 操作流程
1. **查找数据库文档**：优先查找项目中的数据库设计文档（如 `.pdm` 文件、`.md` 文档等）
2. **对照表结构**：逐一对比数据库表字段与实体类字段
3. **验证字段映射**：
   - 数据库字段名 ↔ 实体类字段名（使用 @Column 注解）
   - 数据类型匹配
   - 必填字段标识
   - 主键/外键关系
4. **同步更新**：确保实体类包含数据库表的所有字段

## 常见陷阱
- 仅凭业务逻辑推测字段名（如将 WorkTime 错误地映射为 PlanTime）
- 遗漏重要字段（如 CreateTime/ModifyTime、CreateUserID/ModifyUserID）
- 混淆相似字段（如 Status 与 RecordStatus）
- 字段类型不匹配（如将 int 映射为 String）

## 最佳实践
- 在项目开始阶段建立完整的数据库文档查阅习惯
- 创建实体类后，再次核对数据库文档确认一致性
- 使用工具或脚本来验证实体类与数据库表的映射关系
- 建立团队规范，要求所有实体类变更必须基于数据库文档

## 检查清单
- [ ] 数据库文档已查阅
- [ ] 实体类字段与数据库表字段一一对应
- [ ] Column 注解正确映射数据库字段名
- [ ] 数据类型匹配
- [ ] 必填字段正确标识
- [ ] 时间戳字段（创建时间、修改时间）已包含
- [ ] 用户ID字段（创建用户、修改用户）已包含
- [ ] 状态字段（如 RecordStatus）已包含

## 修复策略
当发现实体类与数据库不一致时：
1. 立即停止相关开发工作
2. 重新查阅数据库文档
3. 对照实体类，标识所有不匹配的字段
4. 按照数据库文档完整更新实体类
5. 更新相关的 Repository、Service 和 Controller 代码
6. 重新编译和测试