Cursor rule

1---
2description: CodeSpirit DTO 开发规范 - 数据传输对象的特性、验证、映射和多语言支持
3globs: 
4  - "*Dto.cs"
5  - "**/Dtos/**/*.cs"
6alwaysApply: false
7---
8 
9# DTO 类规则
10 
11## 属性特性要求
12 
131. **所有属性必须添加 Display 特性（支持多语言）**
142. **Create/Update DTO 必须添加验证特性**
153. 列表 DTO 应参考 [UserDto.cs](mdc:Src/CodeSpirit.IdentityApi/Dtos/User/UserDto.cs) 添加必要的列特性
164. 查询 DTO 必须继承自 [QueryDtoBase.cs](mdc:Src/CodeSpirit.Core/Dtos/QueryDtoBase.cs)，并添加常见的查询逻辑，可以参考 [UserQueryDto.cs](mdc:Src/CodeSpirit.IdentityApi/Dtos/User/UserQueryDto.cs)
175. DTO 添加完成后，应添加或完善 DTO 映射文件，处理好映射关系，参考 [UserProfile.cs](mdc:Src/CodeSpirit.IdentityApi/MappingProfiles/UserProfile.cs)
186. BatchImportItemDto 需要添加 JsonProperty 特性，propertyName 与 DisplayName 一致，参考 [UserBatchImportItemDto.cs](mdc:Src/CodeSpirit.IdentityApi/Dtos/User/UserBatchImportItemDto.cs)
197. 如果需要显示用户信息，请使用聚合器字段特性 [AggregateFieldAttribute.cs](mdc:Src/CodeSpirit.Core/Attributes/AggregateFieldAttribute.cs)，参考 [CodeSpirit.Aggregator聚合器使用指南.md](mdc:Docs/CodeSpirit.Aggregator聚合器使用指南.md)
20 
21## 查询 DTO 中枚举字段
22 
23**枚举筛选字段仅需 `[DisplayName]`，不要使用 `[AmisSelectField]`。**
24 
25SearchFieldHelper 会自动为枚举类型生成 Select 下拉选项，选项文案来自枚举值的 `[Display(Name = "...")]` 特性。若添加 `AmisSelectField`（无论 Source 或 Options），会覆盖该自动行为，导致重复配置或硬编码。
26 
27```csharp
28// ✅ 正确：仅 DisplayName，框架自动生成选项
29[DisplayName("状态")]
30public QuestionStatus? Status { get; set; }
31 
32// ❌ 错误：不要为枚举添加 AmisSelectField
33[AmisSelectField(Options = "1:草稿,2:已发布,3:已归档")]  // 硬编码，无法多语言
34[AmisSelectField(Source = "${ROOT_API}/api/.../status-options")]  // 过度设计，枚举无需 API
35```
36 
37参考：[QuestionQueryDto.cs](mdc:Src/ApiServices/CodeSpirit.ExamApi/Dtos/Question/QuestionQueryDto.cs) 中的 Type、Difficulty、Status 字段。
38 
39## 多语言写法示例
40 
41```csharp
42using CodeSpirit.Localization.Resources;
43 
44public class CreateQuestionDto
45{
46    [Display(Name = "Content", ResourceType = typeof(DisplayResources))]
47    [Required(ErrorMessageResourceType = typeof(ValidationResources), 
48             ErrorMessageResourceName = "Required")]
49    [StringLength(2000, 
50        ErrorMessageResourceType = typeof(ValidationResources),
51        ErrorMessageResourceName = "StringLengthMax")]
52    public string Content { get; set; } = string.Empty;
53    
54    [Display(Name = "Score", ResourceType = typeof(DisplayResources))]
55    [Range(0, 100, 
56        ErrorMessageResourceType = typeof(ValidationResources),
57        ErrorMessageResourceName = "Range")]
58    public decimal Score { get; set; }
59}
60```
61 
62## 参考文件
63 
64- 列表 DTO: [UserDto.cs](mdc:Src/CodeSpirit.IdentityApi/Dtos/User/UserDto.cs)
65- 查询 DTO: [UserQueryDto.cs](mdc:Src/CodeSpirit.IdentityApi/Dtos/User/UserQueryDto.cs)
66- 查询 DTO 枚举字段: [QuestionQueryDto.cs](mdc:Src/ApiServices/CodeSpirit.ExamApi/Dtos/Question/QuestionQueryDto.cs)
67- 映射配置: [UserProfile.cs](mdc:Src/CodeSpirit.IdentityApi/MappingProfiles/UserProfile.cs)
68- 批量导入: [UserBatchImportItemDto.cs](mdc:Src/CodeSpirit.IdentityApi/Dtos/User/UserBatchImportItemDto.cs)
69