Update project_rules.md (#2083)

Author: xue-ding-e

.claude/rules/project_rules.md

@@ -189,13 +189,24 @@ web/
 #### **1. 模型层 (`model/`)**
 
 - **数据模型 (`model/xxx.go`)**:
-    
-    - 用于定义与数据库表映射的 GORM 结构体。
-        
-    - 结构体应继承 `global.GVA_MODEL` 以包含 `ID`, `CreatedAt`, `UpdatedAt` 等基础字段。
-        
-    - 必须为字段添加清晰的 `json` 和 `gorm` 标签。
-        
+
+   - 用于定义与数据库表映射的 GORM 结构体。
+
+   - 结构体应继承 `global.GVA_MODEL` 以包含 `ID`, `CreatedAt`, `UpdatedAt` 等基础字段。
+
+   - 必须为字段添加清晰的 `json` 和 `gorm` 标签。
+
+   - **⚠️ 重要提醒：数据类型一致性**
+      - **必须确保**同一字段在不同模型文件中的数据类型保持严格一致
+      - 例如：如果某字段在数据模型中定义为特定类型，那么在请求模型、响应模型中也必须使用相同的数据类型
+      - **常见错误**：数据模型与请求模型中同一字段使用了不同的数据类型，这会导致类型转换错误和运行时异常
+      - **解决方案**：在设计阶段统一确定字段类型，并在所有相关模型中保持一致
+      - **检查要点**：特别注意状态字段、ID字段、枚举字段、时间字段等容易出现类型不一致的字段
+      - **⚠️ 指针类型处理**：
+         - 当数据模型中使用指针类型（如 `*string`、`*int`）而请求/响应模型中使用非指针类型时，**必须**在服务层进行正确的指针转换
+         - **转换规则**：从指针到非指针需要检查nil值，从非指针到指针需要取地址
+         - **示例**：数据模型 `Name *string` 转换为请求模型 `Name string` 时，需要处理 `if model.Name != nil { request.Name = *model.Name }`
+
 - **请求模型 (`model/request/xxx.go`)**:
 
     - 用于定义接收前端请求参数的结构体（DTOs）。
@@ -212,7 +223,12 @@ web/
 - **结构**: 在 `service/` 下为每个模块创建 `xxx_service.go` 文件，并在 `service/enter.go` 中注册。
 
 - **函数签名**: 函数应接收具体的业务参数（如 `model.Xxx` 或 `request.XxxSearch`），并返回处理结果和 `error`。
-    
+
+- **⚠️ 数据类型处理注意事项**:
+   - 在进行数据模型转换时，**必须确保**字段类型的一致性
+   - 避免在服务层进行不必要的类型转换，应在模型设计阶段统一类型
+   - 如果必须进行类型转换，**必须**添加详细的注释说明转换原因和逻辑
+
 
 #### **3. API层 (`api/`)**
 
@@ -608,6 +624,12 @@ src/plugin/[插件名]/
    - **统一**响应格式：`{code, data, msg}`
    - **统一**分页格式：`{page, pageSize, total, list}`
    - **统一**时间格式：ISO 8601标准
+   - **⚠️ 数据类型一致性**：
+      - 前后端对于同一字段**必须**使用相同的数据类型
+      - 后端Go结构体中的字段类型必须与前端JavaScript/TypeScript中的类型定义保持一致
+      - 特别注意：状态字段、ID字段、枚举值、时间字段等容易出现类型不匹配的字段
+      - 示例：后端数值类型字段对应前端 `number` 类型，字符串类型对应 `string` 类型，布尔类型对应 `boolean` 类型
+      - **指针类型处理**：后端Go中的指针类型在JSON序列化时会自动处理nil值，前端接收到的是对应的基础类型或null值
 
 3. **错误处理**:
    - 后端**必须**返回标准化的错误码和错误信息
@@ -719,10 +741,11 @@ web/src/plugin/[插件名]/
 
 1. **功能完整性**: 插件功能完整，满足业务需求
 2. **代码质量**: 代码规范，注释完整，易于维护
-3. **性能表现**: 响应速度快，资源占用合理
-4. **用户体验**: 界面友好，操作流畅，错误处理完善
-5. **兼容性**: 与主系统兼容，不影响其他功能
-6. **安全性**: 数据安全，权限控制，防止安全漏洞
+3. **数据类型一致性**: 前后端数据模型字段类型保持严格一致，避免类型转换错误
+4. **性能表现**: 响应速度快，资源占用合理
+5. **用户体验**: 界面友好，操作流畅，错误处理完善
+6. **兼容性**: 与主系统兼容，不影响其他功能
+7. **安全性**: 数据安全，权限控制，防止安全漏洞
 
 ---
 

.cursor/rules/project_rules.md

@@ -195,7 +195,18 @@ web/
     - 结构体应继承 `global.GVA_MODEL` 以包含 `ID`, `CreatedAt`, `UpdatedAt` 等基础字段。
 
     - 必须为字段添加清晰的 `json` 和 `gorm` 标签。
-        
+
+    - **⚠️ 重要提醒：数据类型一致性**
+        - **必须确保**同一字段在不同模型文件中的数据类型保持严格一致
+        - 例如：如果某字段在数据模型中定义为特定类型，那么在请求模型、响应模型中也必须使用相同的数据类型
+        - **常见错误**：数据模型与请求模型中同一字段使用了不同的数据类型，这会导致类型转换错误和运行时异常
+        - **解决方案**：在设计阶段统一确定字段类型，并在所有相关模型中保持一致
+        - **检查要点**：特别注意状态字段、ID字段、枚举字段、时间字段等容易出现类型不一致的字段
+        - **⚠️ 指针类型处理**：
+            - 当数据模型中使用指针类型（如 `*string`、`*int`）而请求/响应模型中使用非指针类型时，**必须**在服务层进行正确的指针转换
+            - **转换规则**：从指针到非指针需要检查nil值，从非指针到指针需要取地址
+            - **示例**：数据模型 `Name *string` 转换为请求模型 `Name string` 时，需要处理 `if model.Name != nil { request.Name = *model.Name }`
+
 - **请求模型 (`model/request/xxx.go`)**:
 
     - 用于定义接收前端请求参数的结构体（DTOs）。
@@ -212,7 +223,12 @@ web/
 - **结构**: 在 `service/` 下为每个模块创建 `xxx_service.go` 文件，并在 `service/enter.go` 中注册。
 
 - **函数签名**: 函数应接收具体的业务参数（如 `model.Xxx` 或 `request.XxxSearch`），并返回处理结果和 `error`。
-    
+
+- **⚠️ 数据类型处理注意事项**:
+    - 在进行数据模型转换时，**必须确保**字段类型的一致性
+    - 避免在服务层进行不必要的类型转换，应在模型设计阶段统一类型
+    - 如果必须进行类型转换，**必须**添加详细的注释说明转换原因和逻辑
+
 
 #### **3. API层 (`api/`)**
 
@@ -604,10 +620,16 @@ src/plugin/[插件名]/
    - 接口变更**必须**提前通知并更新文档
 
 2. **数据格式**:
-   - **统一**使用JSON格式进行数据交换
-   - **统一**响应格式：`{code, data, msg}`
-   - **统一**分页格式：`{page, pageSize, total, list}`
-   - **统一**时间格式：ISO 8601标准
+    - **统一**使用JSON格式进行数据交换
+    - **统一**响应格式：`{code, data, msg}`
+    - **统一**分页格式：`{page, pageSize, total, list}`
+    - **统一**时间格式：ISO 8601标准
+    - **⚠️ 数据类型一致性**：
+        - 前后端对于同一字段**必须**使用相同的数据类型
+        - 后端Go结构体中的字段类型必须与前端JavaScript/TypeScript中的类型定义保持一致
+        - 特别注意：状态字段、ID字段、枚举值、时间字段等容易出现类型不匹配的字段
+        - 示例：后端数值类型字段对应前端 `number` 类型，字符串类型对应 `string` 类型，布尔类型对应 `boolean` 类型
+        - **指针类型处理**：后端Go中的指针类型在JSON序列化时会自动处理nil值，前端接收到的是对应的基础类型或null值
 
 3. **错误处理**:
    - 后端**必须**返回标准化的错误码和错误信息
@@ -719,10 +741,11 @@ web/src/plugin/[插件名]/
 
 1. **功能完整性**: 插件功能完整，满足业务需求
 2. **代码质量**: 代码规范，注释完整，易于维护
-3. **性能表现**: 响应速度快，资源占用合理
-4. **用户体验**: 界面友好，操作流畅，错误处理完善
-5. **兼容性**: 与主系统兼容，不影响其他功能
-6. **安全性**: 数据安全，权限控制，防止安全漏洞
+3. **数据类型一致性**: 前后端数据模型字段类型保持严格一致，避免类型转换错误
+4. **性能表现**: 响应速度快，资源占用合理
+5. **用户体验**: 界面友好，操作流畅，错误处理完善
+6. **兼容性**: 与主系统兼容，不影响其他功能
+7. **安全性**: 数据安全，权限控制，防止安全漏洞
 
 ---
 

.trae/rules/project_rules.md

@@ -195,7 +195,18 @@ web/
     - 结构体应继承 `global.GVA_MODEL` 以包含 `ID`, `CreatedAt`, `UpdatedAt` 等基础字段。
 
     - 必须为字段添加清晰的 `json` 和 `gorm` 标签。
-        
+
+    - **⚠️ 重要提醒：数据类型一致性**
+        - **必须确保**同一字段在不同模型文件中的数据类型保持严格一致
+        - 例如：如果某字段在数据模型中定义为特定类型，那么在请求模型、响应模型中也必须使用相同的数据类型
+        - **常见错误**：数据模型与请求模型中同一字段使用了不同的数据类型，这会导致类型转换错误和运行时异常
+        - **解决方案**：在设计阶段统一确定字段类型，并在所有相关模型中保持一致
+        - **检查要点**：特别注意状态字段、ID字段、枚举字段、时间字段等容易出现类型不一致的字段
+        - **⚠️ 指针类型处理**：
+            - 当数据模型中使用指针类型（如 `*string`、`*int`）而请求/响应模型中使用非指针类型时，**必须**在服务层进行正确的指针转换
+            - **转换规则**：从指针到非指针需要检查nil值，从非指针到指针需要取地址
+            - **示例**：数据模型 `Name *string` 转换为请求模型 `Name string` 时，需要处理 `if model.Name != nil { request.Name = *model.Name }`
+
 - **请求模型 (`model/request/xxx.go`)**:
 
     - 用于定义接收前端请求参数的结构体（DTOs）。
@@ -212,7 +223,12 @@ web/
 - **结构**: 在 `service/` 下为每个模块创建 `xxx_service.go` 文件，并在 `service/enter.go` 中注册。
 
 - **函数签名**: 函数应接收具体的业务参数（如 `model.Xxx` 或 `request.XxxSearch`），并返回处理结果和 `error`。
-    
+
+- **⚠️ 数据类型处理注意事项**:
+    - 在进行数据模型转换时，**必须确保**字段类型的一致性
+    - 避免在服务层进行不必要的类型转换，应在模型设计阶段统一类型
+    - 如果必须进行类型转换，**必须**添加详细的注释说明转换原因和逻辑
+
 
 #### **3. API层 (`api/`)**
 
@@ -604,10 +620,16 @@ src/plugin/[插件名]/
    - 接口变更**必须**提前通知并更新文档
 
 2. **数据格式**:
-   - **统一**使用JSON格式进行数据交换
-   - **统一**响应格式：`{code, data, msg}`
-   - **统一**分页格式：`{page, pageSize, total, list}`
-   - **统一**时间格式：ISO 8601标准
+    - **统一**使用JSON格式进行数据交换
+    - **统一**响应格式：`{code, data, msg}`
+    - **统一**分页格式：`{page, pageSize, total, list}`
+    - **统一**时间格式：ISO 8601标准
+    - **⚠️ 数据类型一致性**：
+        - 前后端对于同一字段**必须**使用相同的数据类型
+        - 后端Go结构体中的字段类型必须与前端JavaScript/TypeScript中的类型定义保持一致
+        - 特别注意：状态字段、ID字段、枚举值、时间字段等容易出现类型不匹配的字段
+        - 示例：后端数值类型字段对应前端 `number` 类型，字符串类型对应 `string` 类型，布尔类型对应 `boolean` 类型
+        - **指针类型处理**：后端Go中的指针类型在JSON序列化时会自动处理nil值，前端接收到的是对应的基础类型或null值
 
 3. **错误处理**:
    - 后端**必须**返回标准化的错误码和错误信息
@@ -719,10 +741,11 @@ web/src/plugin/[插件名]/
 
 1. **功能完整性**: 插件功能完整，满足业务需求
 2. **代码质量**: 代码规范，注释完整，易于维护
-3. **性能表现**: 响应速度快，资源占用合理
-4. **用户体验**: 界面友好，操作流畅，错误处理完善
-5. **兼容性**: 与主系统兼容，不影响其他功能
-6. **安全性**: 数据安全，权限控制，防止安全漏洞
+3. **数据类型一致性**: 前后端数据模型字段类型保持严格一致，避免类型转换错误
+4. **性能表现**: 响应速度快，资源占用合理
+5. **用户体验**: 界面友好，操作流畅，错误处理完善
+6. **兼容性**: 与主系统兼容，不影响其他功能
+7. **安全性**: 数据安全，权限控制，防止安全漏洞
 
 ---