# 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