Cursor rule

1---
2description: CodeSpirit 全局开发规范概览 - 核心原则和规范索引
3globs: 
4alwaysApply: true
5---
6 
7# 通用要求
8 
9- 严格遵守项目结构规范，保持代码组织一致性
10- EF 迁移按数据库目录创建（SqlServer/MySql）
11- 分布式程序优先考虑：高可用、容错、降级、最终一致性
12- 所有面向用户的文本必须支持多语言（中文/英文）
13- 异步编程：所有 I/O 操作使用 `async/await`，禁止 `Task.Result` 和 `Task.Wait()`
14 
15> 💡 **详细规范**: 本文件是全局概览，详细规范请参考专项文档
16 
17# 技术栈
18 
19- **框架**: .NET 10 + Aspire 13.0
20- **数据库**: MySQL 8.0 / SQL Server 2022 + GreptimeDB（审计）
21- **缓存/消息**: Redis + RabbitMQ
22- **前端**: React + AMIS (AntD 主题)
23- **AI**: OpenAI、通义千问、DeepSeek
24 
25# 核心规范
26 
27## 统一启动框架
28- Program.cs 仅需 2 行代码 + 配置类继承 `BaseApiConfiguration`
29- 📖 [详细规范](mdc:.cursor/rules/startup-framework.mdc)
30 
31## 依赖注入
32- 自动注册：`IScopedDependency` / `ITransientDependency` / `ISingletonDependency`
33- 📖 [详细规范](mdc:.cursor/rules/dependency-injection.mdc)
34 
35## 命名约定
36- 实体：`User`、DTO：`CreateUserDto`、服务：`UserService`、控制器：`UsersController`
37- 📖 [详细规范](mdc:.cursor/rules/naming-conventions.mdc)
38 
39## API 设计
40- RESTful 标准 + 统一响应格式 `ApiResponse<T>` + 操作特性标记
41- 📖 [详细规范](mdc:.cursor/rules/api-design.mdc)
42 
43## 多语言国际化
44- 支持中英文 + 资源文件 + DTO 验证特性多语言
45- 📖 [详细规范](mdc:.cursor/rules/i18n.mdc)
46 
47## AI 功能开发
48- AI 表单填充（`[AiFormFill]`）+ AI 长任务（`aiForm`）+ LLM 集成
49- 📖 [详细规范](mdc:.cursor/rules/ai-development.mdc)
50 
51## 性能优化
52- 异步编程 + 多级缓存（L1+L2）+ EF Core 查询优化
53- 📖 [详细规范](mdc:.cursor/rules/performance.mdc)
54 
55## 安全规范
56- 权限控制（`[Authorize]` + `[RequirePermission]`）+ 审计追踪 + 数据加密
57- 📖 [详细规范](mdc:.cursor/rules/security.mdc)
58 
59## 包管理规范
60- 集中式包管理：所有包版本在 `Directory.Packages.props` 中统一管理
61- 项目文件中只引用包名，不指定版本
62- 避免冗余引用：通过传递依赖可用的包不需要显式引用
63- 📖 [详细规范](mdc:.cursor/rules/package-management.mdc)
64 
65# 数据访问
66 
67- **多数据库支持**: 使用数据库特定 DbContext（`SqlServer{Service}DbContext` / `MySql{Service}DbContext`）
68- **Code First 迁移**: 按数据库创建独立迁移（SqlServer/MySql），**必须使用数据库特定 DbContext**
69- **雪花 ID 配置**: 使用 `IIdGenerator` 的实体必须配置 `ValueGeneratedNever()`
70- **实体配置**: `IEntityTypeConfiguration<T>`
71- **只读查询**: `AsNoTracking()`，避免 N+1 用 `Include` + `AsSplitQuery()`
72- **多租户**: 实体实现 `IMultiTenant`，自动应用租户过滤器
73- 📖 [详细规范](mdc:.cursor/rules/database.mdc)
74 
75# 代码质量
76 
77- 一个 .cs 文件一个顶级类型
78- XML 文档注释：`<summary>`, `<param>`, `<returns>`, `<exception>`
79- 时间使用 UTC 格式
80 
81# 组件使用
82 
83- **AMIS**: `antd` 主题，CSS 类用 `antd-` 前缀，特性驱动
84- **LLM**: 使用 `ILLMClientFactory`，提示词指定 JSON 输出
85 
86# 调试运行
87 
88- **启动**: `CodeSpirit.AppHost` (Aspire 协调) → `aspire run` 或 F5
89- **Dashboard**: Aspire 管理面板
90- **健康检查**: `/health`
91 
92# 项目结构
93 
94```
95Src/
96├── ApiServices/        # 14个API服务（Identity, Exam, Survey, AI等）
97├── Components/         # 多个核心组件（Amis, LLM, Caching等）
98├── CodeSpirit.AppHost/ # Aspire应用宿主
99├── CodeSpirit.Core/    # 核心框架
100└── CodeSpirit.Web/     # Web前端
101```
102 
103📖 [完整项目结构](mdc:.cursor/rules/project-structure.mdc)
104 
105# 规范文档索引
106 
107## 通用规范
108- [C#通用规范](mdc:.cursor/rules/cs.mdc) - XML注释、时间格式、序列化
109- [命名约定](mdc:.cursor/rules/naming-conventions.mdc) - 实体、DTO、服务、控制器命名
110 
111## 按文件类型
112- [DTO规范](mdc:.cursor/rules/dto.mdc) - DTO特性、验证、映射
113- [控制器规范](mdc:.cursor/rules/controller.mdc) - API控制器、操作特性
114- [服务类规范](mdc:.cursor/rules/service.mdc) - 服务接口、实现、生命周期
115- [枚举规范](mdc:.cursor/rules/enum.mdc) - 枚举定义、多语言支持
116 
117## 专项规范
118- [API设计](mdc:.cursor/rules/api-design.mdc) - RESTful、路由、响应格式
119- [依赖注入](mdc:.cursor/rules/dependency-injection.mdc) - Scrutor自动注册
120- [启动框架](mdc:.cursor/rules/startup-framework.mdc) - Program.cs配置
121- [数据库迁移](mdc:.cursor/rules/database.mdc) - 多数据库、DbContext、迁移命令
122- [多语言](mdc:.cursor/rules/i18n.mdc) - 资源文件、本地化
123- [AI开发](mdc:.cursor/rules/ai-development.mdc) - AI表单、长任务、LLM
124- [性能优化](mdc:.cursor/rules/performance.mdc) - 异步、缓存、查询
125- [安全规范](mdc:.cursor/rules/security.mdc) - 权限、审计、加密
126- [测试规范](mdc:.cursor/rules/testing.mdc) - 单元测试、集成测试、Mock使用
127 
128## 项目结构
129- [项目结构](mdc:.cursor/rules/project-structure.mdc) - 完整目录树
130 
131## 包管理
132- [包管理规范](mdc:.cursor/rules/package-management.mdc) - 集中式包管理、版本统一、传递依赖处理
133 
134> 💡 专项规范会根据文件类型自动应用