提交代码

docs/开发文档/API开发最佳实践总结.md

@@ -391,6 +391,35 @@ def run_all_tests(self):
 **问题**：代码变更后文档未更新
 **解决**：建立强制性文档同步更新规则，代码完成后立即更新文档
 
+#### 5. MyBatis-Plus 实体字段映射问题 (2025-08-13 新增)
+
+**问题**：SQL 错误 "Unknown column 'parent_name' in 'field list'"
+**原因**：实体类中包含数据库表不存在的字段，MyBatis-Plus 自动生成 SQL 时包含了这些字段
+**典型场景**：实体类中有用于显示的冗余字段（如 parentName），但数据库表中没有对应字段
+
+**解决方案**：
+
+```java
+/**
+ * 父部门名称（冗余字段，用于显示，不持久化到数据库）
+ */
+@TableField(exist = false)
+private String parentName;
+```
+
+**关键要点**：
+- 添加 `@TableField(exist = false)` 注解告诉 MyBatis-Plus 该字段不存在于数据库表中
+- 导入正确的注解包：`import com.baomidou.mybatisplus.annotation.TableField;`
+- 适用于所有用于显示但不持久化的冗余字段
+- 避免在使用 `selectList()` 等 MyBatis-Plus 方法时出现字段不存在的错误
+
+**错误示例**：
+```
+org.springframework.jdbc.BadSqlGrammarException: 
+### Error querying database. Cause: java.sql.SQLSyntaxErrorException: Unknown column 'parent_name' in 'field list'
+### SQL: SELECT dept_id, parent_id, ancestors, dept_name, order_num, leader, phone, email, status, del_flag, parent_name, dept_category, create_dept, create_by, create_time, update_by, update_time FROM sys_dept WHERE...
+```
+
 ### 性能优化建议
 
 1. **数据库查询优化**：合理使用索引，避免全表扫描