diff --git a/.claude/rules/project_rules.md b/.claude/rules/project_rules.md index 3998e9989..161f2ae69 100644 --- a/.claude/rules/project_rules.md +++ b/.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. **安全性**: 数据安全，权限控制，防止安全漏洞 --- diff --git a/.cursor/rules/project_rules.md b/.cursor/rules/project_rules.md index 3998e9989..687be168a 100644 --- a/.cursor/rules/project_rules.md +++ b/.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. **安全性**: 数据安全，权限控制，防止安全漏洞 --- diff --git a/.trae/rules/project_rules.md b/.trae/rules/project_rules.md index 3998e9989..687be168a 100644 --- a/.trae/rules/project_rules.md +++ b/.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. **安全性**: 数据安全，权限控制，防止安全漏洞 ---