56 lines
2.2 KiB
Markdown
56 lines
2.2 KiB
Markdown
|
# API CONTROLLERS KNOWLEDGE BASE
|
||
|
|
|
||
|
|
**Generated:** 2026-01-28
|
||
|
|
**Parent:** EmailBill/AGENTS.md
|
||
|
|
|
||
|
|
## OVERVIEW
|
||
|
|
REST API controllers using ASP.NET Core with DTO patterns and standardized responses.
|
||
|
|
|
||
|
|
## STRUCTURE
|
||
|
|
```
|
||
|
|
WebApi/Controllers/
|
||
|
|
├── Dto/ # Data transfer objects
|
||
|
|
│ ├── BaseResponse.cs # Standard response wrapper
|
||
|
|
│ ├── LoginRequest/Response.cs # Authentication DTOs
|
||
|
|
│ ├── BudgetDto.cs # Budget data transfer
|
||
|
|
│ ├── EmailMessageDto.cs # Email data transfer
|
||
|
|
│ └── PagedResponse.cs # Pagination wrapper
|
||
|
|
├── AuthController.cs # Authentication endpoints
|
||
|
|
├── BudgetController.cs # Budget management
|
||
|
|
├── TransactionRecordController.cs # Transaction CRUD
|
||
|
|
├── EmailMessageController.cs # Email processing
|
||
|
|
├── MessageRecordController.cs # Message handling
|
||
|
|
└── [Other controllers] # Feature-specific endpoints
|
||
|
|
```
|
||
|
|
|
||
|
|
## WHERE TO LOOK
|
||
|
|
| Task | Location | Notes |
|
||
|
|
|------|----------|-------|
|
||
|
|
| Authentication | AuthController.cs | JWT login, token refresh |
|
||
|
|
| Budget APIs | BudgetController.cs | Budget CRUD, statistics |
|
||
|
|
| Transaction APIs | TransactionRecordController.cs | Financial transactions |
|
||
|
|
| Email APIs | EmailMessageController.cs | Email processing |
|
||
|
|
| DTO patterns | Dto/ | Request/response models |
|
||
|
|
| Standard responses | BaseResponse.cs, PagedResponse.cs | Consistent API format |
|
||
|
|
|
||
|
|
## CONVENTIONS
|
||
|
|
- Controllers inherit from ControllerBase
|
||
|
|
- Route attributes: [ApiController], [Route("api/[controller]")]
|
||
|
|
- All actions return Task<IActionResult> or Task<BaseResponse<T>>
|
||
|
|
- Use DTOs for all request/response data
|
||
|
|
- HTTP verb attributes: [HttpGet], [HttpPost], [HttpPut], [HttpDelete]
|
||
|
|
- Validation via model state and attributes
|
||
|
|
|
||
|
|
## ANTI-PATTERNS (THIS LAYER)
|
||
|
|
- Never return domain entities directly
|
||
|
|
- Don't access repositories from controllers (use services)
|
||
|
|
- Avoid business logic in controllers
|
||
|
|
- No synchronous I/O operations
|
||
|
|
- Don't skip authentication/authorization where needed
|
||
|
|
|
||
|
|
## UNIQUE STYLES
|
||
|
|
- BaseResponse<T> wrapper for consistent API format
|
||
|
|
- PagedResponse<T> for list endpoints
|
||
|
|
- Chinese error messages for user-facing errors
|
||
|
|
- JWT-based authentication patterns
|
||
|
|
- Swagger/OpenAPI documentation via attributes
|