b71eadd4f9
All checks were successful
Docker Build & Deploy / Build Docker Image (push) Successful in 26s
Docker Build & Deploy / Deploy to Production (push) Successful in 7s
Docker Build & Deploy / Cleanup Dangling Images (push) Successful in 2s
Docker Build & Deploy / WeChat Notification (push) Successful in 2s
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 |