Improved docs for future AI
This commit is contained in:
Eric Gullickson
@@ -1,35 +1,211 @@
|
||||
# UfuelUlogs Feature Capsule
|
||||
# Fuel Logs Feature Capsule
|
||||
|
||||
## Quick Summary (50 tokens)
|
||||
[AI: Complete feature description, main operations, dependencies, caching strategy]
|
||||
Tracks fuel purchases and calculates MPG efficiency. Depends on vehicles feature for vehicle_id. Provides analytics for fuel costs, consumption trends, and efficiency metrics. Cached user logs for 5 minutes. Supports CRUD operations with user ownership validation.
|
||||
|
||||
## API Endpoints
|
||||
- GET /api/fuel-logs - List all fuel-logs
|
||||
- GET /api/fuel-logs/:id - Get specific lUfuelUlogs
|
||||
- POST /api/fuel-logs - Create new lUfuelUlogs
|
||||
- PUT /api/fuel-logs/:id - Update lUfuelUlogs
|
||||
- DELETE /api/fuel-logs/:id - Delete lUfuelUlogs
|
||||
- `POST /api/fuel-logs` - Create new fuel log entry
|
||||
- `GET /api/fuel-logs` - List all user's fuel logs (cached 5 min)
|
||||
- `GET /api/fuel-logs/:id` - Get specific fuel log
|
||||
- `PUT /api/fuel-logs/:id` - Update fuel log details
|
||||
- `DELETE /api/fuel-logs/:id` - Delete fuel log
|
||||
- `GET /api/fuel-logs/vehicle/:vehicleId` - Get fuel logs for specific vehicle
|
||||
- `GET /api/fuel-logs/vehicle/:vehicleId/stats` - Get fuel efficiency statistics
|
||||
|
||||
## Structure
|
||||
- **api/** - HTTP endpoints, routes, validators
|
||||
- **domain/** - Business logic, types, rules
|
||||
- **data/** - Repository, database queries
|
||||
- **migrations/** - Feature-specific schema
|
||||
- **external/** - External API integrations
|
||||
- **events/** - Event handlers
|
||||
- **tests/** - All feature tests
|
||||
- **docs/** - Detailed documentation
|
||||
## Authentication Required
|
||||
All endpoints require valid JWT token with user context.
|
||||
|
||||
## Request/Response Examples
|
||||
|
||||
### Create Fuel Log
|
||||
```json
|
||||
POST /api/fuel-logs
|
||||
{
|
||||
"vehicleId": "uuid-vehicle-id",
|
||||
"date": "2024-01-15",
|
||||
"odometer": 52000,
|
||||
"gallons": 12.5,
|
||||
"pricePerGallon": 3.299,
|
||||
"totalCost": 41.24,
|
||||
"station": "Shell Station",
|
||||
"location": "123 Main St, City, ST",
|
||||
"notes": "Full tank, premium gas"
|
||||
}
|
||||
|
||||
Response (201):
|
||||
{
|
||||
"id": "uuid-here",
|
||||
"userId": "user-id",
|
||||
"vehicleId": "uuid-vehicle-id",
|
||||
"date": "2024-01-15",
|
||||
"odometer": 52000,
|
||||
"gallons": 12.5,
|
||||
"pricePerGallon": 3.299,
|
||||
"totalCost": 41.24,
|
||||
"station": "Shell Station",
|
||||
"location": "123 Main St, City, ST",
|
||||
"notes": "Full tank, premium gas",
|
||||
"mpg": 28.4, // Auto-calculated from previous log
|
||||
"createdAt": "2024-01-15T10:30:00Z",
|
||||
"updatedAt": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Get Vehicle Statistics
|
||||
```json
|
||||
GET /api/fuel-logs/vehicle/:vehicleId/stats
|
||||
|
||||
Response (200):
|
||||
{
|
||||
"totalLogs": 15,
|
||||
"totalGallons": 187.5,
|
||||
"totalCost": 618.45,
|
||||
"averageMpg": 29.2,
|
||||
"averagePricePerGallon": 3.299,
|
||||
"lastFillUp": "2024-01-15",
|
||||
"milesTracked": 5475
|
||||
}
|
||||
```
|
||||
|
||||
## Feature Architecture
|
||||
|
||||
### Complete Self-Contained Structure
|
||||
```
|
||||
fuel-logs/
|
||||
├── README.md # This file
|
||||
├── index.ts # Public API exports
|
||||
├── api/ # HTTP layer
|
||||
│ ├── fuel-logs.controller.ts
|
||||
│ ├── fuel-logs.routes.ts
|
||||
│ └── fuel-logs.validators.ts
|
||||
├── domain/ # Business logic
|
||||
│ ├── fuel-logs.service.ts
|
||||
│ └── fuel-logs.types.ts
|
||||
├── data/ # Database layer
|
||||
│ └── fuel-logs.repository.ts
|
||||
├── migrations/ # Feature schema
|
||||
│ └── 001_create_fuel_logs_table.sql
|
||||
├── tests/ # All tests
|
||||
│ ├── unit/
|
||||
│ │ └── fuel-logs.service.test.ts
|
||||
│ └── integration/
|
||||
│ └── fuel-logs.integration.test.ts
|
||||
└── docs/ # Additional docs
|
||||
```
|
||||
|
||||
## Key Features
|
||||
|
||||
### MPG Calculation
|
||||
- **Auto-calculation**: Computes MPG based on odometer difference from previous log
|
||||
- **First Entry**: No MPG for first fuel log (no baseline)
|
||||
- **Accuracy**: Requires consistent odometer readings
|
||||
- **Validation**: Ensures odometer readings increase over time
|
||||
|
||||
### Database Schema
|
||||
- **Primary Table**: `fuel_logs` with foreign key to vehicles
|
||||
- **Indexes**: Optimized for user queries, vehicle lookups, date ranges
|
||||
- **Constraints**: Valid vehicle_id, positive gallons/cost, future dates allowed
|
||||
|
||||
### Performance Optimizations
|
||||
- **Redis Caching**: User fuel logs cached for 5 minutes
|
||||
- **Indexes**: Strategic database indexes for fast queries
|
||||
- **Efficient Queries**: Single query for MPG calculations
|
||||
|
||||
## Business Rules
|
||||
|
||||
### Data Validation
|
||||
- **Vehicle Ownership**: User must own the vehicle
|
||||
- **Positive Values**: Gallons, price, cost must be > 0
|
||||
- **Odometer Logic**: Reading must be >= previous reading for same vehicle
|
||||
- **Date Validation**: No fuel logs in future (beyond today)
|
||||
|
||||
### MPG Calculation Logic
|
||||
- **Formula**: (Current Odometer - Previous Odometer) / Gallons
|
||||
- **Baseline**: Requires at least 2 fuel logs for calculation
|
||||
- **Edge Cases**: Handles first log, odometer resets, missing data
|
||||
|
||||
## Dependencies
|
||||
- Internal: core/auth, core/cache
|
||||
- External: [List any external APIs]
|
||||
- Database: fuel-logs table
|
||||
|
||||
## Quick Commands
|
||||
### Internal Core Services
|
||||
- `core/auth` - JWT authentication middleware
|
||||
- `core/config` - Database pool, Redis cache
|
||||
- `core/logging` - Structured logging with Winston
|
||||
- `shared-minimal/utils` - Pure validation utilities
|
||||
|
||||
### Feature Dependencies
|
||||
- **vehicles** - REQUIRED: vehicle_id foreign key relationship
|
||||
- Must have valid vehicle before creating fuel logs
|
||||
|
||||
### Database Tables
|
||||
- `fuel_logs` - Primary fuel tracking data
|
||||
- `vehicles` - Referenced via vehicle_id foreign key
|
||||
|
||||
## Caching Strategy
|
||||
|
||||
### User Fuel Logs (5 minutes)
|
||||
- **Key**: `fuel-logs:user:{userId}`
|
||||
- **TTL**: 300 seconds (5 minutes)
|
||||
- **Invalidation**: On create, update, delete
|
||||
|
||||
### Vehicle Statistics (15 minutes)
|
||||
- **Key**: `fuel-stats:vehicle:{vehicleId}`
|
||||
- **TTL**: 900 seconds (15 minutes)
|
||||
- **Rationale**: Stats change less frequently than individual logs
|
||||
|
||||
## Testing
|
||||
|
||||
### Unit Tests
|
||||
- `fuel-logs.service.test.ts` - Business logic with mocked dependencies
|
||||
- Tests MPG calculation logic
|
||||
- Tests vehicle ownership validation
|
||||
- Tests error handling paths
|
||||
|
||||
### Integration Tests
|
||||
- `fuel-logs.integration.test.ts` - Complete API workflow with test database
|
||||
|
||||
### Run Tests
|
||||
```bash
|
||||
# Run feature tests
|
||||
# All fuel log tests
|
||||
npm test -- features/fuel-logs
|
||||
|
||||
# Run feature migrations
|
||||
npm run migrate:feature fuel-logs
|
||||
# Unit tests only
|
||||
npm test -- features/fuel-logs/tests/unit
|
||||
|
||||
# Integration tests only
|
||||
npm test -- features/fuel-logs/tests/integration
|
||||
|
||||
# With coverage
|
||||
npm test -- features/fuel-logs --coverage
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Client Errors (4xx)
|
||||
- `400` - Invalid data, negative values, validation errors
|
||||
- `401` - Missing or invalid JWT token
|
||||
- `403` - User not authorized for vehicle/fuel log
|
||||
- `404` - Vehicle or fuel log not found
|
||||
- `409` - Odometer reading conflicts
|
||||
|
||||
### Server Errors (5xx)
|
||||
- `500` - Database connection failures
|
||||
- Graceful error responses with meaningful messages
|
||||
|
||||
## Development Commands
|
||||
|
||||
```bash
|
||||
# Run migrations
|
||||
make migrate
|
||||
|
||||
# Start development environment
|
||||
make dev
|
||||
|
||||
# View feature logs
|
||||
make logs-backend | grep fuel-logs
|
||||
|
||||
# Open container shell
|
||||
make shell-backend
|
||||
|
||||
# Inside container - run feature tests
|
||||
npm test -- features/fuel-logs
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user