| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 1 | 14 | 7 | 5% |
| Commands | 0 | 2 | 0 | 0% |
| Section tags | 0 | 3 | 1 | 0% |
What each file covers
Sections
1 shared · 14 only in A · 7 only in B- − Copilot instructions
- − General recommendations for working with Aspire
- − Running the application
- − Checking resources
- − Listing integrations
- − Debugging issues
- − Other Aspire MCP tools
- − Playwright MCP server
- − Updating the app host
- − Persistent containers
- − Aspire workload
- − Official documentation
- − BMAD AI 工作流
- − 与 CodeSpirit 规范集成
- + 1. 标准业务控制器
- + 2. 设置页面控制器
- + 3. 内部 API 控制器
- + 4. 匿名访问控制器
- + Navigation 特性
- + Audit 特性
- + Operation 特性参数
- 获取帮助
Commands
0 shared · 2 only in A · 0 only in B- − dotnet tool install --global dotnet-outdated-tool
- − dotnet-outdated
Section tags
0 shared · 3 only in A · 1 only in B- − code-style
- − agent-behaviour
- − docs
- + api
Line diff
xin-lai/CodeSpirit · AGENTS.md
@@ −1 @@
1# Copilot instructions
2
3This repository is set up to use Aspire. Aspire is an orchestrator for the entire application and will take care of configuring dependencies, building, and running the application. The resources that make up the application are defined in `apphost.cs` including application code and external dependencies.
4
5## General recommendations for working with Aspire
61. Before making any changes always run the apphost using `aspire run` and inspect the state of resources to make sure you are building from a known state.
71. Changes to the _apphost.cs_ file will require a restart of the application to take effect.
82. Make changes incrementally and run the aspire application using the `aspire run` command to validate changes.
93. Use the Aspire MCP tools to check the status of resources and debug issues.
10
11## Running the application
12To run the application run the following command:
13
14```
15aspire run
16```
17
18If there is already an instance of the application running it will prompt to stop the existing instance. You only need to restart the application if code in `apphost.cs` is changed, but if you experience problems it can be useful to reset everything to the starting state.
19
20## Checking resources
21To check the status of resources defined in the app model use the _list resources_ tool. This will show you the current state of each resource and if there are any issues. If a resource is not running as expected you can use the _execute resource command_ tool to restart it or perform other actions.
22
23## Listing integrations
24IMPORTANT! When a user asks you to add a resource to the app model you should first use the _list integrations_ tool to get a list of the current versions of all the available integrations. You should try to use the version of the integration which aligns with the version of the Aspire.AppHost.Sdk. Some integration versions may have a preview suffix. Once you have identified the correct integration you should always use the _get integration docs_ tool to fetch the latest documentation for the integration and follow the links to get additional guidance.
25
26## Debugging issues
27IMPORTANT! Aspire is designed to capture rich logs and telemetry for all resources defined in the app model. Use the following diagnostic tools when debugging issues with the application before making changes to make sure you are focusing on the right things.
28
291. _list structured logs_; use this tool to get details about structured logs.
302. _list console logs_; use this tool to get details about console logs.
313. _list traces_; use this tool to get details about traces.
324. _list trace structured logs_; use this tool to get logs related to a trace
33
34## Other Aspire MCP tools
35
361. _select apphost_; use this tool if working with multiple app hosts within a workspace.
372. _list apphosts_; use this tool to get details about active app hosts.
38
39## Playwright MCP server
40
41The playwright MCP server has also been configured in this repository and you should use it to perform functional investigations of the resources defined in the app model as you work on the codebase. To get endpoints that can be used for navigation using the playwright MCP server use the list resources tool.
42
43## Updating the app host
44The user may request that you update the Aspire apphost. You can do this using the `aspire update` command. This will update the apphost to the latest version and some of the Aspire specific packages in referenced projects, however you may need to manually update other packages in the solution to ensure compatibility. You can consider using the `dotnet-outdated` with the users consent. To install the `dotnet-outdated` tool use the following command:
45
46```
47dotnet tool install --global dotnet-outdated-tool
48```
49
50## Persistent containers
51IMPORTANT! Consider avoiding persistent containers early during development to avoid creating state management issues when restarting the app.
52
53## Aspire workload
54IMPORTANT! The aspire workload is obsolete. You should never attempt to install or use the Aspire workload.
55
56## Official documentation
57IMPORTANT! Always prefer official documentation when available. The following sites contain the official documentation for Aspire and related components
58
591. https://aspire.dev
602. https://learn.microsoft.com/dotnet/aspire
613. https://nuget.org (for specific integration package details)
62
63## BMAD AI 工作流
64
65本项目已集成 BMAD (Breakthrough Method of Agile AI-Driven Development) 完整工作流，用于结构化的软件开发生命周期管理。
66
67### 快速开始
68
691. **小型任务/Bug 修复** (Quick Flow):
70 - `/quick-spec` - 创建技术规范
71 - `/quick-dev` - 实现变更
72 - `/code-review` - 代码审查
73
742. **完整功能开发** (Full Flow):
75 - `/product-brief` - 产品需求简报
76 - `/create-prd` - 创建 PRD
77 - `/create-architecture` - 架构设计
78 - `/create-epics-and-stories` - 拆分为 Epic 和 Story
79 - `/sprint-planning` - Sprint 规划
80 - `/dev-story` - 实现 Story
81 - `/code-review` - 代码审查
82 - `/retrospective` - 复盘
83
84### 与 CodeSpirit 规范集成
85
86BMAD 工作流已配置为自动遵循 CodeSpirit 的所有开发规范（位于 `.cursor/rules/`）。在使用 BMAD 时：
87
88- PRD 会自动考虑多租户、多数据库、AI 功能等项目特性
89- 架构设计会遵循依赖注入、缓存策略等规范
90- Story 实现会应用正确的命名约定、DTO 设计、控制器规范等
91- 代码审查会执行 CodeSpirit 特定的审查清单
92
93### 获取帮助
94
95任何时候，输入 `/bmad-help` 可获取上下文相关的指导。
96
97详细使用指南请参考：
98- **[BMAD 使用教程](Docs/bmad/bmad-tutorial.md)** - 完整的综合教程（推荐新手阅读）
99- [BMAD 工作流指南](Docs/bmad/bmad-workflow-guide.md) - 详细的工作流使用指南
100- [BMAD 团队培训指南](Docs/bmad/bmad-team-guide.md) - 团队培训材料
101- [BMAD 集成技能](.cursor/skills/bmad-integration/SKILL.md) - BMAD 与 CodeSpirit 集成
102- [项目上下文文档](project-context.md) - 项目上下文和规范引用
xin-lai/CodeSpirit · .cursor/rules/controller.mdc
@@ +1 @@
1---
2description: CodeSpirit 控制器开发规范 - API控制器特性、路由、响应格式和操作特性
3globs:
4 - "*Controller.cs"
5 - "**/Controllers/**/*.cs"
6alwaysApply: false
7---
8
9# 控制器开发规范
10
11> 📖 API 设计规范（RESTful、响应格式、状态码等）参见 [api-design.mdc](mdc:.cursor/rules/api-design.mdc)
12
13## 基本要求
14
15| 要求 | 说明 |
16|-----|------|
17| 继承基类 | 继承当前项目中的 `ApiControllerBase` |
18| 控制器特性 | 必须添加 `[DisplayName]` 和 `[Navigation]` 特性 |
19| Action 特性 | 所有方法必须添加 `[DisplayName]` 特性 |
20| 返回类型 | 所有方法返回 `ActionResult<ApiResponse<T>>` |
21| 异常处理 | 不在 Action 中捕获异常，由统一过滤器处理 |
22| 多参数处理 | 多个参数应封装为 DTO 模型 |
23| XML 注释 | 控制器类和公共方法应添加 XML 文档注释 |
24
25## 控制器类型
26
27### 1. 标准业务控制器
28
29```csharp
30using CodeSpirit.Core;
31using CodeSpirit.Core.Attributes;
32using CodeSpirit.Core.Enums;
33using CodeSpirit.Navigation.Resources;
34using Microsoft.AspNetCore.Mvc;
35using System.ComponentModel;
36
37namespace CodeSpirit.IdentityApi.Controllers;
38
39/// <summary>
40/// 用户管理控制器
41/// </summary>
42[DisplayName("用户管理")]
43[Navigation(Icon = "fa-solid fa-users",
44 PlatformType = PlatformType.Tenant,
45 TitleResourceKey = "Controller.Users",
46 TitleResourceType = typeof(NavigationResources))]
47public class UsersController : ApiControllerBase
48{
49 private readonly IUserService _userService;
50
51 public UsersController(IUserService userService)
52 {
53 _userService = userService;
54 }
55
56 /// <summary>
57 /// 获取用户列表
58 /// </summary>
59 [HttpGet]
60 [DisplayName("获取用户列表")]
61 public async Task<ActionResult<ApiResponse<PageList<UserDto>>>> GetUsers(
62 [FromQuery] UserQueryDto queryDto)
63 {
64 PageList<UserDto> users = await _userService.GetUsersAsync(queryDto);
65 return SuccessResponse(users);
66 }
67}
68```
69
70### 2. 设置页面控制器
71
72用于用户设置、系统配置等场景：
73
74```csharp
75[DisplayName("用户设置")]
76[Navigation(Icon = "fa-solid fa-user-cog", Order = 150, PlatformType = PlatformType.Tenant)]
77[SettingsPage(Title = "用户设置", Description = "管理用户偏好和系统配置")]
78public class UserSettingsController : ApiControllerBase { }
79```
80
81### 3. 内部 API 控制器
82
83用于微服务间内部通信，不对外暴露：
84
85```csharp
86/// <summary>
87/// 内部用户信息访问控制器
88/// </summary>
89[DisableAggregator] // 禁用 API 聚合
90[DisplayName("内部用户信息")]
91[Module("default")] // 指定模块
92[Route("api/identity/internal/users")] // 自定义路由
93[NoAudit("内部 API 不需要审计")]
94public class InternalUsersController : ControllerBase { } // 继承 ControllerBase
95```
96
97### 4. 匿名访问控制器
98
99无需认证的公开 API：
100
101```csharp
102[AllowAnonymous]
103[Navigation(Hidden = true)] // 隐藏导航
104[NoAudit("授权控制器不需要审计")]
105public class AuthController : ApiControllerBase { }
106```
107
108## 控制器特性详解
109
110### Navigation 特性
111
112配置导航菜单和权限：
113
114| 属性 | 类型 | 说明 |
115|-----|------|------|
116| `Icon` | string | Font Awesome 图标类名 |
117| `PlatformType` | PlatformType | 平台类型：`Tenant`（租户端）/ `System`（系统端）|
118| `Order` | int | 菜单排序（数字越小越靠前）|
119| `Hidden` | bool | 是否隐藏导航菜单 |
120| `TitleResourceKey` | string | 多语言标题资源键 |
121| `TitleResourceType` | Type | 多语言资源类型 |
122
123```csharp
124// 完整示例
125[Navigation(
126 Icon = "fa-solid fa-users",
127 PlatformType = PlatformType.Tenant,
128 Order = 100,
129 TitleResourceKey = "Controller.Users",
130 TitleResourceType = typeof(NavigationResources))]
131```
132
133### Audit 特性
134
135控制审计日志记录：
136
137```csharp
138// 启用审计
139[Audit(EntityName = nameof(Department), LogRequestParams = true, LogResponseData = true)]
140
141// 禁用审计
142[NoAudit("授权控制器不需要审计")]
143```
144
145### 其他控制器特性
146
147| 特性 | 用途 |
148|-----|------|
149| `[Module("name")]` | 指定模块名称，用于路由分组 |
150| `[DisableAggregator]` | 禁用 API 聚合，用于内部 API |
151| `[SettingsPage]` | 标记为设置页面控制器 |
152| `[AllowAnonymous]` | 允许匿名访问 |
153| `[Authorize]` | 显式要求认证 |
154
155## 操作特性
156
157除标准 CRUD 操作外，其他操作应添加 `Operation` 或其派生特性：
158
159### 操作特性类型
160
161| 特性 | 用途 | 典型场景 |
162|-----|------|---------|
163| `[Operation]` | 基础操作 | 行级操作（解锁、禁用、删除等）|
164| `[HeaderOperation]` | 表头操作 | 新增、导入、AI 生成 |
165| `[CrudDialogOperation]` | CRUD 弹窗操作 | 编辑、查看详情（简化配置）|
166
167> 💡 批量操作通过 `[Operation]` 的 `isBatch` 参数实现，设置为 `true` 即可。
168
169### Operation 特性参数
170
171```csharp
172[Operation(
173 label: "解锁", // 按钮文本
174 actionType: "ajax", // 操作类型：ajax, form, dialog, aiForm
175 dialog: null, // 弹窗配置（可选）
176 confirmText: "确定要解除用户锁定吗？", // 确认提示
177 visibleOn: "lockoutEnd != null", // 显示条件表达式
178 // 多语言支持
179 LabelResourceKey = "Operations.Unlock",
180 LabelResourceType = typeof(OperationsResources),
181 ConfirmTextResourceKey = "Operations.ConfirmUnlock",
182 ConfirmTextResourceType = typeof(OperationsResources),
183 // 图标
184 Icon = "fa-solid fa-unlock")]
185```
186
187### 操作类型说明
188
189| actionType | 说明 | 适用场景 |
190|-----------|------|---------|
191| `ajax` | 直接发送请求 | 简单操作（删除、状态切换）|
192| `form` | 弹出表单 | 需要输入参数的操作 |
193| `dialog` | 弹出对话框 | 复杂内容展示 |
194| `aiForm` | AI 长任务表单 | AI 生成、批量处理 |
195
196### 完整操作示例
197
198#### 行级 Ajax 操作
199
200```csharp
201[HttpPut("{id}/unlock")]
202[Operation("解锁", "ajax", null, "确定要解除用户锁定吗？", "lockoutEnd != null",
203 LabelResourceKey = "Operations.Unlock",
204 LabelResourceType = typeof(OperationsResources),
205 ConfirmTextResourceKey = "Operations.ConfirmUnlock",
206 ConfirmTextResourceType = typeof(OperationsResources),
207 Icon = "fa-solid fa-unlock")]
208[DisplayName("解锁用户")]
209public async Task<ActionResult<ApiResponse>> UnlockUser(long id)
210{
211 await _userService.UnlockUserAsync(id);
212 return SuccessResponse("用户已成功解锁。");
213}
214```
215
216#### 带反馈结果的操作
217
218```csharp
219[HttpPost("{id}/resetRandomPassword")]
220[Operation("重置密码", "ajax", null, "确定要重置密码吗？", "isActive == true",
221 LabelResourceKey = "Operations.ResetPassword",
222 LabelResourceType = typeof(OperationsResources),
223 FeedbackTitle = "重置密码结果",
224 FeedbackBodyTpl = @"{
225 'type': 'form',
226 'body': [
227 { 'type': 'button', 'label': '${newPassword}', 'icon': 'fa fa-copy',
228 'actionType': 'copy', 'content': '${newPassword}' }
229 ]
230 }")]
231[DisplayName("重置随机密码")]
232public async Task<ActionResult<ApiResponse>> ResetRandomPassword(long id)
233{
234 string newPassword = await _userService.ResetRandomPasswordAsync(id);
235 return Ok(new { message = "密码已重置成功！", data = new { newPassword } });
236}
237```
238
239#### 带重定向的操作
240
241```csharp
242[HttpPost("{id}/impersonate")]
243[Operation("模拟登录", "ajax", null, "确定要模拟此用户登录吗？", "isActive == true",
244 LabelResourceKey = "Operations.ImpersonateLogin",
245 LabelResourceType = typeof(OperationsResources),
246 Redirect = "/impersonate?token=${token}&tenantId=${tenantId}")]
247[DisplayName("模拟用户登录")]
248public async Task<ActionResult<ApiResponse<object>>> ImpersonateUser(long id) { }
249```
250
251#### AI 长任务操作
252
253```csharp
254[HttpPost("ai/generate")]
255[HeaderOperation("AI生成题目", "aiForm",
256 Icon = "fa-solid fa-magic",
257 StatusApi = "/exam/api/Questions/ai/task-status", // 状态查询 API
258 PollingInterval = 2000, // 轮询间隔（毫秒）
259 MaxPollingTime = 300000)] // 最大轮询时间
260[DisplayName("AI生成题目")]
261public async Task<ActionResult<ApiResponse<string>>> GenerateQuestionsAsync(
262 [FromBody] GenerateQuestionsRequest request)
263{
264 var taskId = await _service.GenerateQuestionsAsync(request);
265 return SuccessResponse(taskId);
266}
267```
268
269#### 批量操作
270
271```csharp
272[HttpPost("batch/delete")]
273[Operation("批量删除", "ajax", null, "确定要批量删除?", null, true, // isBatch = true
274 LabelResourceKey = "Common.BatchDelete",
275 LabelResourceType = typeof(SharedResources),
276 ConfirmTextResourceKey = "Common.ConfirmBatchDelete",
277 ConfirmTextResourceType = typeof(SharedResources))]
278[DisplayName("批量删除用户")]
279public async Task<ActionResult<ApiResponse>> BatchDelete([FromBody] BatchOperationDto<long> request)
280{
281 var (successCount, failedIds) = await _userService.BatchDeleteAsync(request.Ids);
282 return SuccessResponse($"成功删除 {successCount} 个用户！");
283}
284```
285
286## 构造函数注入
287
288```csharp
289public class UsersController : ApiControllerBase
290{
291 private readonly IUserService _userService;
292 private readonly IAuthService _authService;
293 private readonly ILogger<UsersController> _logger;
294
295 public UsersController(
296 IUserService userService,
297 IAuthService authService,
298 ILogger<UsersController> logger)
299 {
300 _userService = userService;
301 _authService = authService;
302 _logger = logger;
303 }
304}
305```
306
307> 💡 推荐使用主构造函数（C# 12+）简化注入代码。
308
309## 注意事项
310
3111. **无需添加 `[ApiController]` 和 `[Route]` 特性**：基类已包含默认配置
3122. **路由自动推断**：默认按 `/{service-name}/api/[controller]` 格式
3133. **Action 返回 DTO**：不要直接返回实体类
3144. **异步方法**：所有 I/O 操作使用 `async/await`
3155. **操作特性 Icon**：使用 Font Awesome 图标，格式为 `fa-solid fa-xxx`
316
317## 参考文件
318
319- 控制器基类: [ApiControllerBase.cs](mdc:Src/CodeSpirit.Shared/Controllers/ApiControllerBase.cs)
320- 导航特性: [NavigationAttribute.cs](mdc:Src/CodeSpirit.Core/Attributes/NavigationAttribute.cs)
321- 操作特性: [OperationAttribute.cs](mdc:Src/Components/CodeSpirit.Amis/Attributes/Buttons/OperationAttribute.cs)
322- 用户控制器示例: [UsersController.cs](mdc:Src/CodeSpirit.IdentityApi/Controllers/UsersController.cs)
323- API 设计规范: [api-design.mdc](mdc:.cursor/rules/api-design.mdc)
324
@@ −1 +1 @@
1−# Copilot instructions
1+---
2+description: CodeSpirit 控制器开发规范 - API控制器特性、路由、响应格式和操作特性
3+globs:
4+ - "*Controller.cs"
5+ - "**/Controllers/**/*.cs"
6+alwaysApply: false
7+---
28
3−This repository is set up to use Aspire. Aspire is an orchestrator for the entire application and will take care of configuring dependencies, building, and running the application. The resources that make up the application are defined in `apphost.cs` including application code and external dependencies.
9+# 控制器开发规范
410
5−## General recommendations for working with Aspire
6−1. Before making any changes always run the apphost using `aspire run` and inspect the state of resources to make sure you are building from a known state.
7−1. Changes to the _apphost.cs_ file will require a restart of the application to take effect.
8−2. Make changes incrementally and run the aspire application using the `aspire run` command to validate changes.
9−3. Use the Aspire MCP tools to check the status of resources and debug issues.
11+> 📖 API 设计规范（RESTful、响应格式、状态码等）参见 [api-design.mdc](mdc:.cursor/rules/api-design.mdc)
1012
11−## Running the application
12−To run the application run the following command:
13+## 基本要求
1314
15+| 要求 | 说明 |
16+|-----|------|
17+| 继承基类 | 继承当前项目中的 `ApiControllerBase` |
18+| 控制器特性 | 必须添加 `[DisplayName]` 和 `[Navigation]` 特性 |
19+| Action 特性 | 所有方法必须添加 `[DisplayName]` 特性 |
20+| 返回类型 | 所有方法返回 `ActionResult<ApiResponse<T>>` |
21+| 异常处理 | 不在 Action 中捕获异常，由统一过滤器处理 |
22+| 多参数处理 | 多个参数应封装为 DTO 模型 |
23+| XML 注释 | 控制器类和公共方法应添加 XML 文档注释 |
24+
25+## 控制器类型
26+
27+### 1. 标准业务控制器
28+
29+```csharp
30+using CodeSpirit.Core;
31+using CodeSpirit.Core.Attributes;
32+using CodeSpirit.Core.Enums;
33+using CodeSpirit.Navigation.Resources;
34+using Microsoft.AspNetCore.Mvc;
35+using System.ComponentModel;
36+
37+namespace CodeSpirit.IdentityApi.Controllers;
38+
39+/// <summary>
40+/// 用户管理控制器
41+/// </summary>
42+[DisplayName("用户管理")]
43+[Navigation(Icon = "fa-solid fa-users",
44+ PlatformType = PlatformType.Tenant,
45+ TitleResourceKey = "Controller.Users",
46+ TitleResourceType = typeof(NavigationResources))]
47+public class UsersController : ApiControllerBase
48+{
49+ private readonly IUserService _userService;
50+
51+ public UsersController(IUserService userService)
52+ {
53+ _userService = userService;
54+ }
55+
56+ /// <summary>
57+ /// 获取用户列表
58+ /// </summary>
59+ [HttpGet]
60+ [DisplayName("获取用户列表")]
61+ public async Task<ActionResult<ApiResponse<PageList<UserDto>>>> GetUsers(
62+ [FromQuery] UserQueryDto queryDto)
63+ {
64+ PageList<UserDto> users = await _userService.GetUsersAsync(queryDto);
65+ return SuccessResponse(users);
66+ }
67+}
1468 ```
15−aspire run
69+
70+### 2. 设置页面控制器
71+
72+用于用户设置、系统配置等场景：
73+
74+```csharp
75+[DisplayName("用户设置")]
76+[Navigation(Icon = "fa-solid fa-user-cog", Order = 150, PlatformType = PlatformType.Tenant)]
77+[SettingsPage(Title = "用户设置", Description = "管理用户偏好和系统配置")]
78+public class UserSettingsController : ApiControllerBase { }
1679 ```
1780
18−If there is already an instance of the application running it will prompt to stop the existing instance. You only need to restart the application if code in `apphost.cs` is changed, but if you experience problems it can be useful to reset everything to the starting state.
81+### 3. 内部 API 控制器
1982
20−## Checking resources
21−To check the status of resources defined in the app model use the _list resources_ tool. This will show you the current state of each resource and if there are any issues. If a resource is not running as expected you can use the _execute resource command_ tool to restart it or perform other actions.
83+用于微服务间内部通信，不对外暴露：
2284
23−## Listing integrations
24−IMPORTANT! When a user asks you to add a resource to the app model you should first use the _list integrations_ tool to get a list of the current versions of all the available integrations. You should try to use the version of the integration which aligns with the version of the Aspire.AppHost.Sdk. Some integration versions may have a preview suffix. Once you have identified the correct integration you should always use the _get integration docs_ tool to fetch the latest documentation for the integration and follow the links to get additional guidance.
85+```csharp
86+/// <summary>
87+/// 内部用户信息访问控制器
88+/// </summary>
89+[DisableAggregator] // 禁用 API 聚合
90+[DisplayName("内部用户信息")]
91+[Module("default")] // 指定模块
92+[Route("api/identity/internal/users")] // 自定义路由
93+[NoAudit("内部 API 不需要审计")]
94+public class InternalUsersController : ControllerBase { } // 继承 ControllerBase
95+```
2596
26−## Debugging issues
27−IMPORTANT! Aspire is designed to capture rich logs and telemetry for all resources defined in the app model. Use the following diagnostic tools when debugging issues with the application before making changes to make sure you are focusing on the right things.
97+### 4. 匿名访问控制器
2898
29−1. _list structured logs_; use this tool to get details about structured logs.
30−2. _list console logs_; use this tool to get details about console logs.
31−3. _list traces_; use this tool to get details about traces.
32−4. _list trace structured logs_; use this tool to get logs related to a trace
99+无需认证的公开 API：
33100
34−## Other Aspire MCP tools
101+```csharp
102+[AllowAnonymous]
103+[Navigation(Hidden = true)] // 隐藏导航
104+[NoAudit("授权控制器不需要审计")]
105+public class AuthController : ApiControllerBase { }
106+```
35107
36−1. _select apphost_; use this tool if working with multiple app hosts within a workspace.
37−2. _list apphosts_; use this tool to get details about active app hosts.
108+## 控制器特性详解
38109
39−## Playwright MCP server
110+### Navigation 特性
40111
41−The playwright MCP server has also been configured in this repository and you should use it to perform functional investigations of the resources defined in the app model as you work on the codebase. To get endpoints that can be used for navigation using the playwright MCP server use the list resources tool.
112+配置导航菜单和权限：
42113
43−## Updating the app host
44−The user may request that you update the Aspire apphost. You can do this using the `aspire update` command. This will update the apphost to the latest version and some of the Aspire specific packages in referenced projects, however you may need to manually update other packages in the solution to ensure compatibility. You can consider using the `dotnet-outdated` with the users consent. To install the `dotnet-outdated` tool use the following command:
114+| 属性 | 类型 | 说明 |
115+|-----|------|------|
116+| `Icon` | string | Font Awesome 图标类名 |
117+| `PlatformType` | PlatformType | 平台类型：`Tenant`（租户端）/ `System`（系统端）|
118+| `Order` | int | 菜单排序（数字越小越靠前）|
119+| `Hidden` | bool | 是否隐藏导航菜单 |
120+| `TitleResourceKey` | string | 多语言标题资源键 |
121+| `TitleResourceType` | Type | 多语言资源类型 |
45122
123+```csharp
124+// 完整示例
125+[Navigation(
126+ Icon = "fa-solid fa-users",
127+ PlatformType = PlatformType.Tenant,
128+ Order = 100,
129+ TitleResourceKey = "Controller.Users",
130+ TitleResourceType = typeof(NavigationResources))]
46131 ```
47−dotnet tool install --global dotnet-outdated-tool
132+
133+### Audit 特性
134+
135+控制审计日志记录：
136+
137+```csharp
138+// 启用审计
139+[Audit(EntityName = nameof(Department), LogRequestParams = true, LogResponseData = true)]
140+
141+// 禁用审计
142+[NoAudit("授权控制器不需要审计")]
48143 ```
49144
50−## Persistent containers
51−IMPORTANT! Consider avoiding persistent containers early during development to avoid creating state management issues when restarting the app.
145+### 其他控制器特性
52146
53−## Aspire workload
54−IMPORTANT! The aspire workload is obsolete. You should never attempt to install or use the Aspire workload.
147+| 特性 | 用途 |
148+|-----|------|
149+| `[Module("name")]` | 指定模块名称，用于路由分组 |
150+| `[DisableAggregator]` | 禁用 API 聚合，用于内部 API |
151+| `[SettingsPage]` | 标记为设置页面控制器 |
152+| `[AllowAnonymous]` | 允许匿名访问 |
153+| `[Authorize]` | 显式要求认证 |
55154
56−## Official documentation
57−IMPORTANT! Always prefer official documentation when available. The following sites contain the official documentation for Aspire and related components
155+## 操作特性
58156
59−1. https://aspire.dev
60−2. https://learn.microsoft.com/dotnet/aspire
61−3. https://nuget.org (for specific integration package details)
157+除标准 CRUD 操作外，其他操作应添加 `Operation` 或其派生特性：
62158
63−## BMAD AI 工作流
159+### 操作特性类型
64160
65−本项目已集成 BMAD (Breakthrough Method of Agile AI-Driven Development) 完整工作流，用于结构化的软件开发生命周期管理。
161+| 特性 | 用途 | 典型场景 |
162+|-----|------|---------|
163+| `[Operation]` | 基础操作 | 行级操作（解锁、禁用、删除等）|
164+| `[HeaderOperation]` | 表头操作 | 新增、导入、AI 生成 |
165+| `[CrudDialogOperation]` | CRUD 弹窗操作 | 编辑、查看详情（简化配置）|
66166
67−### 快速开始
167+> 💡 批量操作通过 `[Operation]` 的 `isBatch` 参数实现，设置为 `true` 即可。
68168
69−1. **小型任务/Bug 修复** (Quick Flow):
70− - `/quick-spec` - 创建技术规范
71− - `/quick-dev` - 实现变更
72− - `/code-review` - 代码审查
169+### Operation 特性参数
73170
74−2. **完整功能开发** (Full Flow):
75− - `/product-brief` - 产品需求简报
76− - `/create-prd` - 创建 PRD
77− - `/create-architecture` - 架构设计
78− - `/create-epics-and-stories` - 拆分为 Epic 和 Story
79− - `/sprint-planning` - Sprint 规划
80− - `/dev-story` - 实现 Story
81− - `/code-review` - 代码审查
82− - `/retrospective` - 复盘
171+```csharp
172+[Operation(
173+ label: "解锁", // 按钮文本
174+ actionType: "ajax", // 操作类型：ajax, form, dialog, aiForm
175+ dialog: null, // 弹窗配置（可选）
176+ confirmText: "确定要解除用户锁定吗？", // 确认提示
177+ visibleOn: "lockoutEnd != null", // 显示条件表达式
178+ // 多语言支持
179+ LabelResourceKey = "Operations.Unlock",
180+ LabelResourceType = typeof(OperationsResources),
181+ ConfirmTextResourceKey = "Operations.ConfirmUnlock",
182+ ConfirmTextResourceType = typeof(OperationsResources),
183+ // 图标
184+ Icon = "fa-solid fa-unlock")]
185+```
83186
84−### 与 CodeSpirit 规范集成
187+### 操作类型说明
85188
86−BMAD 工作流已配置为自动遵循 CodeSpirit 的所有开发规范（位于 `.cursor/rules/`）。在使用 BMAD 时：
189+| actionType | 说明 | 适用场景 |
190+|-----------|------|---------|
191+| `ajax` | 直接发送请求 | 简单操作（删除、状态切换）|
192+| `form` | 弹出表单 | 需要输入参数的操作 |
193+| `dialog` | 弹出对话框 | 复杂内容展示 |
194+| `aiForm` | AI 长任务表单 | AI 生成、批量处理 |
87195
88−- PRD 会自动考虑多租户、多数据库、AI 功能等项目特性
89−- 架构设计会遵循依赖注入、缓存策略等规范
90−- Story 实现会应用正确的命名约定、DTO 设计、控制器规范等
91−- 代码审查会执行 CodeSpirit 特定的审查清单
196+### 完整操作示例
92197
93−### 获取帮助
198+#### 行级 Ajax 操作
94199
95−任何时候，输入 `/bmad-help` 可获取上下文相关的指导。
200+```csharp
201+[HttpPut("{id}/unlock")]
202+[Operation("解锁", "ajax", null, "确定要解除用户锁定吗？", "lockoutEnd != null",
203+ LabelResourceKey = "Operations.Unlock",
204+ LabelResourceType = typeof(OperationsResources),
205+ ConfirmTextResourceKey = "Operations.ConfirmUnlock",
206+ ConfirmTextResourceType = typeof(OperationsResources),
207+ Icon = "fa-solid fa-unlock")]
208+[DisplayName("解锁用户")]
209+public async Task<ActionResult<ApiResponse>> UnlockUser(long id)
210+{
211+ await _userService.UnlockUserAsync(id);
212+ return SuccessResponse("用户已成功解锁。");
213+}
214+```
96215
97−详细使用指南请参考：
98−- **[BMAD 使用教程](Docs/bmad/bmad-tutorial.md)** - 完整的综合教程（推荐新手阅读）
99−- [BMAD 工作流指南](Docs/bmad/bmad-workflow-guide.md) - 详细的工作流使用指南
100−- [BMAD 团队培训指南](Docs/bmad/bmad-team-guide.md) - 团队培训材料
101−- [BMAD 集成技能](.cursor/skills/bmad-integration/SKILL.md) - BMAD 与 CodeSpirit 集成
102−- [项目上下文文档](project-context.md) - 项目上下文和规范引用
216+#### 带反馈结果的操作
217+
218+```csharp
219+[HttpPost("{id}/resetRandomPassword")]
220+[Operation("重置密码", "ajax", null, "确定要重置密码吗？", "isActive == true",
221+ LabelResourceKey = "Operations.ResetPassword",
222+ LabelResourceType = typeof(OperationsResources),
223+ FeedbackTitle = "重置密码结果",
224+ FeedbackBodyTpl = @"{
225+ 'type': 'form',
226+ 'body': [
227+ { 'type': 'button', 'label': '${newPassword}', 'icon': 'fa fa-copy',
228+ 'actionType': 'copy', 'content': '${newPassword}' }
229+ ]
230+ }")]
231+[DisplayName("重置随机密码")]
232+public async Task<ActionResult<ApiResponse>> ResetRandomPassword(long id)
233+{
234+ string newPassword = await _userService.ResetRandomPasswordAsync(id);
235+ return Ok(new { message = "密码已重置成功！", data = new { newPassword } });
236+}
237+```
238+
239+#### 带重定向的操作
240+
241+```csharp
242+[HttpPost("{id}/impersonate")]
243+[Operation("模拟登录", "ajax", null, "确定要模拟此用户登录吗？", "isActive == true",
244+ LabelResourceKey = "Operations.ImpersonateLogin",
245+ LabelResourceType = typeof(OperationsResources),
246+ Redirect = "/impersonate?token=${token}&tenantId=${tenantId}")]
247+[DisplayName("模拟用户登录")]
248+public async Task<ActionResult<ApiResponse<object>>> ImpersonateUser(long id) { }
249+```
250+
251+#### AI 长任务操作
252+
253+```csharp
254+[HttpPost("ai/generate")]
255+[HeaderOperation("AI生成题目", "aiForm",
256+ Icon = "fa-solid fa-magic",
257+ StatusApi = "/exam/api/Questions/ai/task-status", // 状态查询 API
258+ PollingInterval = 2000, // 轮询间隔（毫秒）
259+ MaxPollingTime = 300000)] // 最大轮询时间
260+[DisplayName("AI生成题目")]
261+public async Task<ActionResult<ApiResponse<string>>> GenerateQuestionsAsync(
262+ [FromBody] GenerateQuestionsRequest request)
263+{
264+ var taskId = await _service.GenerateQuestionsAsync(request);
265+ return SuccessResponse(taskId);
266+}
267+```
268+
269+#### 批量操作
270+
271+```csharp
272+[HttpPost("batch/delete")]
273+[Operation("批量删除", "ajax", null, "确定要批量删除?", null, true, // isBatch = true
274+ LabelResourceKey = "Common.BatchDelete",
275+ LabelResourceType = typeof(SharedResources),
276+ ConfirmTextResourceKey = "Common.ConfirmBatchDelete",
277+ ConfirmTextResourceType = typeof(SharedResources))]
278+[DisplayName("批量删除用户")]
279+public async Task<ActionResult<ApiResponse>> BatchDelete([FromBody] BatchOperationDto<long> request)
280+{
281+ var (successCount, failedIds) = await _userService.BatchDeleteAsync(request.Ids);
282+ return SuccessResponse($"成功删除 {successCount} 个用户！");
283+}
284+```
285+
286+## 构造函数注入
287+
288+```csharp
289+public class UsersController : ApiControllerBase
290+{
291+ private readonly IUserService _userService;
292+ private readonly IAuthService _authService;
293+ private readonly ILogger<UsersController> _logger;
294+
295+ public UsersController(
296+ IUserService userService,
297+ IAuthService authService,
298+ ILogger<UsersController> logger)
299+ {
300+ _userService = userService;
301+ _authService = authService;
302+ _logger = logger;
303+ }
304+}
305+```
306+
307+> 💡 推荐使用主构造函数（C# 12+）简化注入代码。
308+
309+## 注意事项
310+
311+1. **无需添加 `[ApiController]` 和 `[Route]` 特性**：基类已包含默认配置
312+2. **路由自动推断**：默认按 `/{service-name}/api/[controller]` 格式
313+3. **Action 返回 DTO**：不要直接返回实体类
314+4. **异步方法**：所有 I/O 操作使用 `async/await`
315+5. **操作特性 Icon**：使用 Font Awesome 图标，格式为 `fa-solid fa-xxx`
316+
317+## 参考文件
318+
319+- 控制器基类: [ApiControllerBase.cs](mdc:Src/CodeSpirit.Shared/Controllers/ApiControllerBase.cs)
320+- 导航特性: [NavigationAttribute.cs](mdc:Src/CodeSpirit.Core/Attributes/NavigationAttribute.cs)
321+- 操作特性: [OperationAttribute.cs](mdc:Src/Components/CodeSpirit.Amis/Attributes/Buttons/OperationAttribute.cs)
322+- 用户控制器示例: [UsersController.cs](mdc:Src/CodeSpirit.IdentityApi/Controllers/UsersController.cs)
323+- API 设计规范: [api-design.mdc](mdc:.cursor/rules/api-design.mdc)
324+
