feat: implement fuel card management API for mobile app
feat: implement fuel card management API for mobile app
Add complete fuel card management feature with receipt handling and photo upload capabilities for mobile application integration.
Features:
- Fuel card listing and details retrieval for drivers
- Manual receipt creation, update and deletion
- Receipt photo upload to S3
- Consumption aggregation from DKV imports and manual receipts
- Fuel card history tracking
API Endpoints:
- GET /api/fleet/driver/{driverId}/fuel-cards - Get driver's fuel cards
- GET /api/fleet/fuel-cards/{cardId} - Get fuel card details
- POST /api/fleet/fuel-cards/{cardId}/receipts - Create receipt
- PUT /api/fleet/fuel-cards/{cardId}/receipts/{receiptId} - Update receipt
- DELETE /api/fleet/fuel-cards/{cardId}/receipts/{receiptId} - Delete receipt
- POST /api/fleet/receipts/photo - Upload receipt photo
New Components:
- FuelCardController: REST controller for fuel card operations
- FuelCardService/Impl: Business logic for fuel card management
- ReceiptService/Impl: Business logic for receipt CRUD operations
- PhotoUploadService/Impl: S3 photo upload service
- FuelCardMapper: Entity to DTO mapping for fuel cards
- ReceiptMapper: Entity to DTO mapping for receipts
DTOs:
- FuelCardDTO: Complete fuel card information with aggregations
- FuelCardHistoryDTO: Historical fuel card data
- DriverFuelCardsResponseDTO: Response wrapper for driver's cards
- ReceiptDTO: Receipt information
- ReceiptCreateDTO: Receipt creation request with validation
- ReceiptUpdateDTO: Receipt update request
- ConsumptionDTO: DKV consumption data for fuel cards
- PhotoUploadResponseDTO: Photo upload response
- ApiResponse: Generic API response wrapper
Repositories:
- ReceiptRepository: JPA repository for Receipt entity
- ConsumptionRepository: Added sumAmountByCardBoxNumber query
Architecture:
- Integrated with existing FuelCardAssignment entity (no new FuelCard table)
- Receipts linked to FuelCardAssignment via cardNumber
- Amount calculations aggregate DKV consumptions and manual receipts
- Proper separation of concerns (controller -> service -> repository)