diff --git a/backend/src/_system/migrations/run-all.ts b/backend/src/_system/migrations/run-all.ts index a134ee9..2d0fd9e 100644 --- a/backend/src/_system/migrations/run-all.ts +++ b/backend/src/_system/migrations/run-all.ts @@ -28,6 +28,7 @@ const MIGRATION_ORDER = [ 'features/user-profile', // User profile management; independent 'features/terms-agreement', // Terms & Conditions acceptance audit trail 'features/audit-log', // Centralized audit logging; independent + 'features/ownership-costs', // Depends on vehicles and documents; TCO recurring costs ]; // Base directory where migrations are copied inside the image (set by Dockerfile) diff --git a/backend/src/app.ts b/backend/src/app.ts index e3d8db4..cbe60d0 100644 --- a/backend/src/app.ts +++ b/backend/src/app.ts @@ -32,6 +32,7 @@ import { onboardingRoutes } from './features/onboarding'; import { userPreferencesRoutes } from './features/user-preferences'; import { userExportRoutes } from './features/user-export'; import { userImportRoutes } from './features/user-import'; +import { ownershipCostsRoutes } from './features/ownership-costs'; import { pool } from './core/config/database'; import { configRoutes } from './core/config/config.routes'; @@ -93,7 +94,7 @@ async function buildApp(): Promise { status: 'healthy', timestamp: new Date().toISOString(), environment: process.env['NODE_ENV'], - features: ['admin', 'auth', 'config', 'onboarding', 'vehicles', 'documents', 'fuel-logs', 'stations', 'maintenance', 'platform', 'notifications', 'user-profile', 'user-preferences', 'user-export', 'user-import'] + features: ['admin', 'auth', 'config', 'onboarding', 'vehicles', 'documents', 'fuel-logs', 'stations', 'maintenance', 'platform', 'notifications', 'user-profile', 'user-preferences', 'user-export', 'user-import', 'ownership-costs'] }); }); @@ -103,7 +104,7 @@ async function buildApp(): Promise { status: 'healthy', scope: 'api', timestamp: new Date().toISOString(), - features: ['admin', 'auth', 'config', 'onboarding', 'vehicles', 'documents', 'fuel-logs', 'stations', 'maintenance', 'platform', 'notifications', 'user-profile', 'user-preferences', 'user-export', 'user-import'] + features: ['admin', 'auth', 'config', 'onboarding', 'vehicles', 'documents', 'fuel-logs', 'stations', 'maintenance', 'platform', 'notifications', 'user-profile', 'user-preferences', 'user-export', 'user-import', 'ownership-costs'] }); }); @@ -145,6 +146,7 @@ async function buildApp(): Promise { await app.register(userPreferencesRoutes, { prefix: '/api' }); await app.register(userExportRoutes, { prefix: '/api' }); await app.register(userImportRoutes, { prefix: '/api' }); + await app.register(ownershipCostsRoutes, { prefix: '/api' }); await app.register(configRoutes, { prefix: '/api' }); // 404 handler diff --git a/backend/src/features/maintenance/domain/maintenance.service.ts b/backend/src/features/maintenance/domain/maintenance.service.ts index 7990ac4..da04b7e 100644 --- a/backend/src/features/maintenance/domain/maintenance.service.ts +++ b/backend/src/features/maintenance/domain/maintenance.service.ts @@ -9,7 +9,8 @@ import type { MaintenanceRecordResponse, MaintenanceScheduleResponse, MaintenanceCategory, - ScheduleType + ScheduleType, + MaintenanceCostStats } from './maintenance.types'; import { validateSubtypes } from './maintenance.types'; import { MaintenanceRepository } from '../data/maintenance.repository'; @@ -63,6 +64,19 @@ export class MaintenanceService { return records.map(r => this.toRecordResponse(r)); } + async getVehicleMaintenanceCosts(vehicleId: string, userId: string): Promise { + const records = await this.repo.findRecordsByVehicleId(vehicleId, userId); + const totalCost = records.reduce((sum, r) => { + if (r.cost === null || r.cost === undefined) return sum; + const cost = Number(r.cost); + if (isNaN(cost)) { + throw new Error(`Invalid cost value for maintenance record ${r.id}`); + } + return sum + cost; + }, 0); + return { totalCost, recordCount: records.length }; + } + async updateRecord(userId: string, id: string, patch: UpdateMaintenanceRecordRequest): Promise { const existing = await this.repo.findRecordById(id, userId); if (!existing) return null; diff --git a/backend/src/features/maintenance/domain/maintenance.types.ts b/backend/src/features/maintenance/domain/maintenance.types.ts index caeeeb5..ce85ac1 100644 --- a/backend/src/features/maintenance/domain/maintenance.types.ts +++ b/backend/src/features/maintenance/domain/maintenance.types.ts @@ -162,6 +162,12 @@ export interface MaintenanceRecordResponse extends MaintenanceRecord { subtypeCount: number; } +// TCO aggregation stats +export interface MaintenanceCostStats { + totalCost: number; + recordCount: number; +} + export interface MaintenanceScheduleResponse extends MaintenanceSchedule { subtypeCount: number; isDueSoon?: boolean; diff --git a/backend/src/features/ownership-costs/api/ownership-costs.controller.ts b/backend/src/features/ownership-costs/api/ownership-costs.controller.ts new file mode 100644 index 0000000..ca3326f --- /dev/null +++ b/backend/src/features/ownership-costs/api/ownership-costs.controller.ts @@ -0,0 +1,225 @@ +/** + * @ai-summary Fastify route handlers for ownership costs API + * @ai-context HTTP request/response handling with Fastify reply methods + */ + +import { FastifyRequest, FastifyReply } from 'fastify'; +import { OwnershipCostsService } from '../domain/ownership-costs.service'; +import { pool } from '../../../core/config/database'; +import { logger } from '../../../core/logging/logger'; +import { + OwnershipCostParams, + VehicleParams, + CreateOwnershipCostBody, + UpdateOwnershipCostBody +} from '../domain/ownership-costs.types'; + +export class OwnershipCostsController { + private service: OwnershipCostsService; + + constructor() { + this.service = new OwnershipCostsService(pool); + } + + async create(request: FastifyRequest<{ Body: CreateOwnershipCostBody }>, reply: FastifyReply) { + try { + // eslint-disable-next-line @typescript-eslint/no-explicit-any + const userId = (request as any).user.sub; + const cost = await this.service.create(request.body, userId); + + return reply.code(201).send(cost); + } catch (error: unknown) { + const err = error as Error; + // eslint-disable-next-line @typescript-eslint/no-explicit-any + logger.error('Error creating ownership cost', { error: err, userId: (request as any).user?.sub }); + + if (err.message.includes('not found')) { + return reply.code(404).send({ + error: 'Not Found', + message: err.message + }); + } + if (err.message.includes('Unauthorized')) { + return reply.code(403).send({ + error: 'Forbidden', + message: err.message + }); + } + + return reply.code(500).send({ + error: 'Internal server error', + message: 'Failed to create ownership cost' + }); + } + } + + async getByVehicle(request: FastifyRequest<{ Params: VehicleParams }>, reply: FastifyReply) { + try { + // eslint-disable-next-line @typescript-eslint/no-explicit-any + const userId = (request as any).user.sub; + const { vehicleId } = request.params; + + const costs = await this.service.getByVehicleId(vehicleId, userId); + + return reply.code(200).send(costs); + } catch (error: unknown) { + const err = error as Error; + // eslint-disable-next-line @typescript-eslint/no-explicit-any + logger.error('Error listing ownership costs', { error: err, vehicleId: request.params.vehicleId, userId: (request as any).user?.sub }); + + if (err.message.includes('not found')) { + return reply.code(404).send({ + error: 'Not Found', + message: err.message + }); + } + if (err.message.includes('Unauthorized')) { + return reply.code(403).send({ + error: 'Forbidden', + message: err.message + }); + } + + return reply.code(500).send({ + error: 'Internal server error', + message: 'Failed to get ownership costs' + }); + } + } + + async getById(request: FastifyRequest<{ Params: OwnershipCostParams }>, reply: FastifyReply) { + try { + // eslint-disable-next-line @typescript-eslint/no-explicit-any + const userId = (request as any).user.sub; + const { id } = request.params; + + const cost = await this.service.getById(id, userId); + + return reply.code(200).send(cost); + } catch (error: unknown) { + const err = error as Error; + // eslint-disable-next-line @typescript-eslint/no-explicit-any + logger.error('Error getting ownership cost', { error: err, costId: request.params.id, userId: (request as any).user?.sub }); + + if (err.message.includes('not found')) { + return reply.code(404).send({ + error: 'Not Found', + message: err.message + }); + } + if (err.message.includes('Unauthorized')) { + return reply.code(403).send({ + error: 'Forbidden', + message: err.message + }); + } + + return reply.code(500).send({ + error: 'Internal server error', + message: 'Failed to get ownership cost' + }); + } + } + + async update(request: FastifyRequest<{ Params: OwnershipCostParams; Body: UpdateOwnershipCostBody }>, reply: FastifyReply) { + try { + // eslint-disable-next-line @typescript-eslint/no-explicit-any + const userId = (request as any).user.sub; + const { id } = request.params; + + const updatedCost = await this.service.update(id, request.body, userId); + + return reply.code(200).send(updatedCost); + } catch (error: unknown) { + const err = error as Error; + // eslint-disable-next-line @typescript-eslint/no-explicit-any + logger.error('Error updating ownership cost', { error: err, costId: request.params.id, userId: (request as any).user?.sub }); + + if (err.message.includes('not found')) { + return reply.code(404).send({ + error: 'Not Found', + message: err.message + }); + } + if (err.message.includes('Unauthorized')) { + return reply.code(403).send({ + error: 'Forbidden', + message: err.message + }); + } + + return reply.code(500).send({ + error: 'Internal server error', + message: 'Failed to update ownership cost' + }); + } + } + + async delete(request: FastifyRequest<{ Params: OwnershipCostParams }>, reply: FastifyReply) { + try { + // eslint-disable-next-line @typescript-eslint/no-explicit-any + const userId = (request as any).user.sub; + const { id } = request.params; + + await this.service.delete(id, userId); + + return reply.code(204).send(); + } catch (error: unknown) { + const err = error as Error; + // eslint-disable-next-line @typescript-eslint/no-explicit-any + logger.error('Error deleting ownership cost', { error: err, costId: request.params.id, userId: (request as any).user?.sub }); + + if (err.message.includes('not found')) { + return reply.code(404).send({ + error: 'Not Found', + message: err.message + }); + } + if (err.message.includes('Unauthorized')) { + return reply.code(403).send({ + error: 'Forbidden', + message: err.message + }); + } + + return reply.code(500).send({ + error: 'Internal server error', + message: 'Failed to delete ownership cost' + }); + } + } + + async getVehicleStats(request: FastifyRequest<{ Params: VehicleParams }>, reply: FastifyReply) { + try { + // eslint-disable-next-line @typescript-eslint/no-explicit-any + const userId = (request as any).user.sub; + const { vehicleId } = request.params; + + const stats = await this.service.getVehicleCostStats(vehicleId, userId); + + return reply.code(200).send(stats); + } catch (error: unknown) { + const err = error as Error; + // eslint-disable-next-line @typescript-eslint/no-explicit-any + logger.error('Error getting ownership cost stats', { error: err, vehicleId: request.params.vehicleId, userId: (request as any).user?.sub }); + + if (err.message.includes('not found')) { + return reply.code(404).send({ + error: 'Not Found', + message: err.message + }); + } + if (err.message.includes('Unauthorized')) { + return reply.code(403).send({ + error: 'Forbidden', + message: err.message + }); + } + + return reply.code(500).send({ + error: 'Internal server error', + message: 'Failed to get ownership cost stats' + }); + } + } +} diff --git a/backend/src/features/ownership-costs/api/ownership-costs.routes.ts b/backend/src/features/ownership-costs/api/ownership-costs.routes.ts new file mode 100644 index 0000000..4a357c7 --- /dev/null +++ b/backend/src/features/ownership-costs/api/ownership-costs.routes.ts @@ -0,0 +1,56 @@ +/** + * @ai-summary Fastify routes for ownership costs API + * @ai-context Route definitions with Fastify plugin pattern and authentication + */ + +import { FastifyInstance, FastifyPluginOptions } from 'fastify'; +import { FastifyPluginAsync } from 'fastify'; +import { OwnershipCostsController } from './ownership-costs.controller'; + +export const ownershipCostsRoutes: FastifyPluginAsync = async ( + fastify: FastifyInstance, + _opts: FastifyPluginOptions +) => { + const controller = new OwnershipCostsController(); + + // POST /api/ownership-costs - Create new ownership cost + fastify.post('/ownership-costs', { + preHandler: [fastify.authenticate], + handler: controller.create.bind(controller) + }); + + // GET /api/ownership-costs/:id - Get specific ownership cost + fastify.get('/ownership-costs/:id', { + preHandler: [fastify.authenticate], + handler: controller.getById.bind(controller) + }); + + // PUT /api/ownership-costs/:id - Update ownership cost + fastify.put('/ownership-costs/:id', { + preHandler: [fastify.authenticate], + handler: controller.update.bind(controller) + }); + + // DELETE /api/ownership-costs/:id - Delete ownership cost + fastify.delete('/ownership-costs/:id', { + preHandler: [fastify.authenticate], + handler: controller.delete.bind(controller) + }); + + // GET /api/ownership-costs/vehicle/:vehicleId - Get costs for a vehicle + fastify.get('/ownership-costs/vehicle/:vehicleId', { + preHandler: [fastify.authenticate], + handler: controller.getByVehicle.bind(controller) + }); + + // GET /api/ownership-costs/vehicle/:vehicleId/stats - Get aggregated cost stats + fastify.get('/ownership-costs/vehicle/:vehicleId/stats', { + preHandler: [fastify.authenticate], + handler: controller.getVehicleStats.bind(controller) + }); +}; + +// For backward compatibility during migration +export function registerOwnershipCostsRoutes() { + throw new Error('registerOwnershipCostsRoutes is deprecated - use ownershipCostsRoutes Fastify plugin instead'); +} diff --git a/backend/src/features/ownership-costs/data/ownership-costs.repository.ts b/backend/src/features/ownership-costs/data/ownership-costs.repository.ts new file mode 100644 index 0000000..71aaa7d --- /dev/null +++ b/backend/src/features/ownership-costs/data/ownership-costs.repository.ts @@ -0,0 +1,210 @@ +/** + * @ai-summary Data access layer for ownership costs + * @ai-context Handles database operations for vehicle ownership costs + */ + +import { Pool } from 'pg'; +import { + OwnershipCost, + CreateOwnershipCostRequest, + UpdateOwnershipCostRequest, + CostInterval, + OwnershipCostType +} from '../domain/ownership-costs.types'; + +export class OwnershipCostsRepository { + constructor(private pool: Pool) {} + + async create(data: CreateOwnershipCostRequest & { userId: string }): Promise { + const query = ` + INSERT INTO ownership_costs ( + user_id, vehicle_id, document_id, cost_type, description, + amount, interval, start_date, end_date + ) + VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9) + RETURNING * + `; + + const values = [ + data.userId, + data.vehicleId, + data.documentId ?? null, + data.costType, + data.description ?? null, + data.amount, + data.interval, + data.startDate, + data.endDate ?? null + ]; + + const result = await this.pool.query(query, values); + return this.mapRow(result.rows[0]); + } + + async findByVehicleId(vehicleId: string, userId: string): Promise { + const query = ` + SELECT * FROM ownership_costs + WHERE vehicle_id = $1 AND user_id = $2 + ORDER BY start_date DESC, created_at DESC + `; + + const result = await this.pool.query(query, [vehicleId, userId]); + return result.rows.map(row => this.mapRow(row)); + } + + async findByUserId(userId: string): Promise { + const query = ` + SELECT * FROM ownership_costs + WHERE user_id = $1 + ORDER BY start_date DESC, created_at DESC + `; + + const result = await this.pool.query(query, [userId]); + return result.rows.map(row => this.mapRow(row)); + } + + async findById(id: string): Promise { + const query = 'SELECT * FROM ownership_costs WHERE id = $1'; + const result = await this.pool.query(query, [id]); + + if (result.rows.length === 0) { + return null; + } + + return this.mapRow(result.rows[0]); + } + + async findByDocumentId(documentId: string): Promise { + const query = ` + SELECT * FROM ownership_costs + WHERE document_id = $1 + ORDER BY start_date DESC + `; + + const result = await this.pool.query(query, [documentId]); + return result.rows.map(row => this.mapRow(row)); + } + + async update(id: string, data: UpdateOwnershipCostRequest): Promise { + const fields = []; + const values = []; + let paramCount = 1; + + // Build dynamic update query + if (data.documentId !== undefined) { + fields.push(`document_id = $${paramCount++}`); + values.push(data.documentId); + } + if (data.costType !== undefined) { + fields.push(`cost_type = $${paramCount++}`); + values.push(data.costType); + } + if (data.description !== undefined) { + fields.push(`description = $${paramCount++}`); + values.push(data.description); + } + if (data.amount !== undefined) { + fields.push(`amount = $${paramCount++}`); + values.push(data.amount); + } + if (data.interval !== undefined) { + fields.push(`interval = $${paramCount++}`); + values.push(data.interval); + } + if (data.startDate !== undefined) { + fields.push(`start_date = $${paramCount++}`); + values.push(data.startDate); + } + if (data.endDate !== undefined) { + fields.push(`end_date = $${paramCount++}`); + values.push(data.endDate); + } + + if (fields.length === 0) { + return this.findById(id); + } + + values.push(id); + const query = ` + UPDATE ownership_costs + SET ${fields.join(', ')} + WHERE id = $${paramCount} + RETURNING * + `; + + const result = await this.pool.query(query, values); + + if (result.rows.length === 0) { + return null; + } + + return this.mapRow(result.rows[0]); + } + + async delete(id: string): Promise { + const query = 'DELETE FROM ownership_costs WHERE id = $1'; + const result = await this.pool.query(query, [id]); + return (result.rowCount ?? 0) > 0; + } + + async batchInsert( + costs: Array, + client?: Pool + ): Promise { + if (costs.length === 0) { + return []; + } + + const queryClient = client || this.pool; + const placeholders: string[] = []; + const values: unknown[] = []; + let paramCount = 1; + + costs.forEach((cost) => { + const costParams = [ + cost.userId, + cost.vehicleId, + cost.documentId ?? null, + cost.costType, + cost.description ?? null, + cost.amount, + cost.interval, + cost.startDate, + cost.endDate ?? null + ]; + + const placeholder = `($${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++})`; + placeholders.push(placeholder); + values.push(...costParams); + }); + + const query = ` + INSERT INTO ownership_costs ( + user_id, vehicle_id, document_id, cost_type, description, + amount, interval, start_date, end_date + ) + VALUES ${placeholders.join(', ')} + RETURNING * + `; + + const result = await queryClient.query(query, values); + return result.rows.map((row: Record) => this.mapRow(row)); + } + + private mapRow(row: Record): OwnershipCost { + return { + id: row.id as string, + userId: row.user_id as string, + vehicleId: row.vehicle_id as string, + documentId: row.document_id as string | undefined, + costType: row.cost_type as OwnershipCostType, + description: row.description as string | undefined, + amount: Number(row.amount), + interval: row.interval as CostInterval, + startDate: row.start_date as Date, + endDate: row.end_date as Date | undefined, + createdAt: row.created_at as Date, + updatedAt: row.updated_at as Date, + }; + } +} diff --git a/backend/src/features/ownership-costs/domain/ownership-costs.service.ts b/backend/src/features/ownership-costs/domain/ownership-costs.service.ts new file mode 100644 index 0000000..4acf5df --- /dev/null +++ b/backend/src/features/ownership-costs/domain/ownership-costs.service.ts @@ -0,0 +1,199 @@ +/** + * @ai-summary Business logic for ownership costs feature + * @ai-context Handles ownership cost operations and TCO aggregation + */ + +import { Pool } from 'pg'; +import { OwnershipCostsRepository } from '../data/ownership-costs.repository'; +import { + OwnershipCost, + CreateOwnershipCostRequest, + UpdateOwnershipCostRequest, + OwnershipCostResponse, + OwnershipCostStats, + PAYMENTS_PER_YEAR, + OwnershipCostType +} from './ownership-costs.types'; +import { logger } from '../../../core/logging/logger'; +import { VehiclesRepository } from '../../vehicles/data/vehicles.repository'; + +export class OwnershipCostsService { + private repository: OwnershipCostsRepository; + private vehiclesRepository: VehiclesRepository; + + constructor(pool: Pool) { + this.repository = new OwnershipCostsRepository(pool); + this.vehiclesRepository = new VehiclesRepository(pool); + } + + async create(data: CreateOwnershipCostRequest, userId: string): Promise { + logger.info('Creating ownership cost', { userId, vehicleId: data.vehicleId, costType: data.costType }); + + // Verify vehicle ownership + const vehicle = await this.vehiclesRepository.findById(data.vehicleId); + if (!vehicle) { + throw new Error('Vehicle not found'); + } + if (vehicle.userId !== userId) { + throw new Error('Unauthorized'); + } + + const cost = await this.repository.create({ ...data, userId }); + return this.toResponse(cost); + } + + async getByVehicleId(vehicleId: string, userId: string): Promise { + // Verify vehicle ownership + const vehicle = await this.vehiclesRepository.findById(vehicleId); + if (!vehicle) { + throw new Error('Vehicle not found'); + } + if (vehicle.userId !== userId) { + throw new Error('Unauthorized'); + } + + const costs = await this.repository.findByVehicleId(vehicleId, userId); + return costs.map(cost => this.toResponse(cost)); + } + + async getById(id: string, userId: string): Promise { + const cost = await this.repository.findById(id); + + if (!cost) { + throw new Error('Ownership cost not found'); + } + + if (cost.userId !== userId) { + throw new Error('Unauthorized'); + } + + return this.toResponse(cost); + } + + async update(id: string, data: UpdateOwnershipCostRequest, userId: string): Promise { + // Verify ownership + const existing = await this.repository.findById(id); + if (!existing) { + throw new Error('Ownership cost not found'); + } + if (existing.userId !== userId) { + throw new Error('Unauthorized'); + } + + const updated = await this.repository.update(id, data); + if (!updated) { + throw new Error('Update failed'); + } + + return this.toResponse(updated); + } + + async delete(id: string, userId: string): Promise { + // Verify ownership + const existing = await this.repository.findById(id); + if (!existing) { + throw new Error('Ownership cost not found'); + } + if (existing.userId !== userId) { + throw new Error('Unauthorized'); + } + + await this.repository.delete(id); + logger.info('Ownership cost deleted', { id, userId }); + } + + /** + * Get aggregated cost statistics for a vehicle + * Used by TCO calculation in vehicles service + */ + async getVehicleCostStats(vehicleId: string, userId: string): Promise { + const costs = await this.repository.findByVehicleId(vehicleId, userId); + const now = new Date(); + + const stats: OwnershipCostStats = { + insuranceCosts: 0, + registrationCosts: 0, + taxCosts: 0, + otherCosts: 0, + totalCosts: 0 + }; + + for (const cost of costs) { + const startDate = new Date(cost.startDate); + const endDate = cost.endDate ? new Date(cost.endDate) : now; + + // Skip future costs + if (startDate > now) continue; + + // Calculate effective end date (either specified end, or now for ongoing costs) + const effectiveEnd = endDate < now ? endDate : now; + const monthsCovered = this.calculateMonthsBetween(startDate, effectiveEnd); + const normalizedCost = this.normalizeToTotal(cost.amount, cost.interval, monthsCovered); + + // Type-safe key access + const keyMap: Record> = { + insurance: 'insuranceCosts', + registration: 'registrationCosts', + tax: 'taxCosts', + other: 'otherCosts' + }; + + const key = keyMap[cost.costType]; + if (key) { + stats[key] += normalizedCost; + } else { + logger.warn('Unknown cost type in aggregation', { costType: cost.costType, costId: cost.id }); + } + } + + stats.totalCosts = stats.insuranceCosts + stats.registrationCosts + stats.taxCosts + stats.otherCosts; + return stats; + } + + /** + * Calculate months between two dates + */ + private calculateMonthsBetween(startDate: Date, endDate: Date): number { + const yearDiff = endDate.getFullYear() - startDate.getFullYear(); + const monthDiff = endDate.getMonth() - startDate.getMonth(); + return Math.max(1, yearDiff * 12 + monthDiff); + } + + /** + * Normalize recurring cost to total based on interval and months covered + */ + private normalizeToTotal(amount: number, interval: string, monthsCovered: number): number { + // One-time costs are just the amount + if (interval === 'one_time') { + return amount; + } + + const paymentsPerYear = PAYMENTS_PER_YEAR[interval as keyof typeof PAYMENTS_PER_YEAR]; + if (!paymentsPerYear) { + logger.warn('Invalid cost interval', { interval }); + return 0; + } + + // Calculate total payments over the covered period + const yearsOwned = monthsCovered / 12; + const totalPayments = yearsOwned * paymentsPerYear; + return amount * totalPayments; + } + + private toResponse(cost: OwnershipCost): OwnershipCostResponse { + return { + id: cost.id, + userId: cost.userId, + vehicleId: cost.vehicleId, + documentId: cost.documentId, + costType: cost.costType, + description: cost.description, + amount: cost.amount, + interval: cost.interval, + startDate: cost.startDate instanceof Date ? cost.startDate.toISOString().split('T')[0] : cost.startDate as unknown as string, + endDate: cost.endDate ? (cost.endDate instanceof Date ? cost.endDate.toISOString().split('T')[0] : cost.endDate as unknown as string) : undefined, + createdAt: cost.createdAt instanceof Date ? cost.createdAt.toISOString() : cost.createdAt as unknown as string, + updatedAt: cost.updatedAt instanceof Date ? cost.updatedAt.toISOString() : cost.updatedAt as unknown as string, + }; + } +} diff --git a/backend/src/features/ownership-costs/domain/ownership-costs.types.ts b/backend/src/features/ownership-costs/domain/ownership-costs.types.ts new file mode 100644 index 0000000..f367cc7 --- /dev/null +++ b/backend/src/features/ownership-costs/domain/ownership-costs.types.ts @@ -0,0 +1,108 @@ +/** + * @ai-summary Type definitions for ownership-costs feature + * @ai-context Tracks vehicle ownership costs (insurance, registration, tax, other) + */ + +// Cost types supported by ownership-costs feature +export type OwnershipCostType = 'insurance' | 'registration' | 'tax' | 'other'; + +// Cost interval types (one_time added for things like purchase price) +export type CostInterval = 'monthly' | 'semi_annual' | 'annual' | 'one_time'; + +// Payments per year for each interval type +export const PAYMENTS_PER_YEAR: Record = { + monthly: 12, + semi_annual: 2, + annual: 1, + one_time: 0, // Special case: calculated differently +} as const; + +export interface OwnershipCost { + id: string; + userId: string; + vehicleId: string; + documentId?: string; + costType: OwnershipCostType; + description?: string; + amount: number; + interval: CostInterval; + startDate: Date; + endDate?: Date; + createdAt: Date; + updatedAt: Date; +} + +export interface CreateOwnershipCostRequest { + vehicleId: string; + documentId?: string; + costType: OwnershipCostType; + description?: string; + amount: number; + interval: CostInterval; + startDate: string; // ISO date string + endDate?: string; // ISO date string +} + +export interface UpdateOwnershipCostRequest { + documentId?: string | null; + costType?: OwnershipCostType; + description?: string | null; + amount?: number; + interval?: CostInterval; + startDate?: string; + endDate?: string | null; +} + +export interface OwnershipCostResponse { + id: string; + userId: string; + vehicleId: string; + documentId?: string; + costType: OwnershipCostType; + description?: string; + amount: number; + interval: CostInterval; + startDate: string; + endDate?: string; + createdAt: string; + updatedAt: string; +} + +// Aggregated cost statistics for TCO calculation +export interface OwnershipCostStats { + insuranceCosts: number; + registrationCosts: number; + taxCosts: number; + otherCosts: number; + totalCosts: number; +} + +// Fastify-specific types for HTTP handling +export interface CreateOwnershipCostBody { + vehicleId: string; + documentId?: string; + costType: OwnershipCostType; + description?: string; + amount: number; + interval: CostInterval; + startDate: string; + endDate?: string; +} + +export interface UpdateOwnershipCostBody { + documentId?: string | null; + costType?: OwnershipCostType; + description?: string | null; + amount?: number; + interval?: CostInterval; + startDate?: string; + endDate?: string | null; +} + +export interface OwnershipCostParams { + id: string; +} + +export interface VehicleParams { + vehicleId: string; +} diff --git a/backend/src/features/ownership-costs/index.ts b/backend/src/features/ownership-costs/index.ts new file mode 100644 index 0000000..7b97d0e --- /dev/null +++ b/backend/src/features/ownership-costs/index.ts @@ -0,0 +1,22 @@ +/** + * @ai-summary Public API for ownership-costs feature capsule + */ + +// Export service for use by other features +export { OwnershipCostsService } from './domain/ownership-costs.service'; + +// Export types +export type { + OwnershipCost, + CreateOwnershipCostRequest, + UpdateOwnershipCostRequest, + OwnershipCostResponse, + OwnershipCostStats, + OwnershipCostType, + CostInterval +} from './domain/ownership-costs.types'; + +export { PAYMENTS_PER_YEAR } from './domain/ownership-costs.types'; + +// Internal: Register routes with Fastify app +export { ownershipCostsRoutes, registerOwnershipCostsRoutes } from './api/ownership-costs.routes'; diff --git a/backend/src/features/ownership-costs/migrations/001_create_ownership_costs_table.sql b/backend/src/features/ownership-costs/migrations/001_create_ownership_costs_table.sql new file mode 100644 index 0000000..5cc9749 --- /dev/null +++ b/backend/src/features/ownership-costs/migrations/001_create_ownership_costs_table.sql @@ -0,0 +1,61 @@ +-- Migration: Create ownership_costs table +-- Issue: #15 +-- Description: Store vehicle ownership costs (insurance, registration, tax, other) +-- with explicit date ranges and optional document association + +CREATE TABLE IF NOT EXISTS ownership_costs ( + id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), + user_id VARCHAR(255) NOT NULL, + vehicle_id UUID NOT NULL, + document_id UUID, + cost_type VARCHAR(50) NOT NULL, + description TEXT, + amount DECIMAL(12, 2) NOT NULL, + interval VARCHAR(20) NOT NULL, + start_date DATE NOT NULL, + end_date DATE, + created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + + -- Foreign key to vehicles (cascade delete) + CONSTRAINT fk_ownership_costs_vehicle + FOREIGN KEY (vehicle_id) + REFERENCES vehicles(id) + ON DELETE CASCADE, + + -- Foreign key to documents (set null on delete) + CONSTRAINT fk_ownership_costs_document + FOREIGN KEY (document_id) + REFERENCES documents(id) + ON DELETE SET NULL, + + -- Enforce valid cost types + CONSTRAINT chk_ownership_costs_type + CHECK (cost_type IN ('insurance', 'registration', 'tax', 'other')), + + -- Enforce valid intervals + CONSTRAINT chk_ownership_costs_interval + CHECK (interval IN ('monthly', 'semi_annual', 'annual', 'one_time')), + + -- Enforce non-negative amounts + CONSTRAINT chk_ownership_costs_amount_non_negative + CHECK (amount >= 0), + + -- Enforce end_date >= start_date when end_date is provided + CONSTRAINT chk_ownership_costs_date_range + CHECK (end_date IS NULL OR end_date >= start_date) +); + +-- Create indexes for common queries +CREATE INDEX IF NOT EXISTS idx_ownership_costs_user_id ON ownership_costs(user_id); +CREATE INDEX IF NOT EXISTS idx_ownership_costs_vehicle_id ON ownership_costs(vehicle_id); +CREATE INDEX IF NOT EXISTS idx_ownership_costs_cost_type ON ownership_costs(cost_type); +CREATE INDEX IF NOT EXISTS idx_ownership_costs_start_date ON ownership_costs(start_date DESC); +CREATE INDEX IF NOT EXISTS idx_ownership_costs_document_id ON ownership_costs(document_id) WHERE document_id IS NOT NULL; + +-- Add updated_at trigger +DROP TRIGGER IF EXISTS update_ownership_costs_updated_at ON ownership_costs; +CREATE TRIGGER update_ownership_costs_updated_at + BEFORE UPDATE ON ownership_costs + FOR EACH ROW + EXECUTE FUNCTION update_updated_at_column(); diff --git a/backend/src/features/ownership-costs/migrations/002_migrate_vehicle_tco_data.sql b/backend/src/features/ownership-costs/migrations/002_migrate_vehicle_tco_data.sql new file mode 100644 index 0000000..9206040 --- /dev/null +++ b/backend/src/features/ownership-costs/migrations/002_migrate_vehicle_tco_data.sql @@ -0,0 +1,73 @@ +-- Migration: Migrate existing vehicle TCO data to ownership_costs table +-- Issue: #15 +-- Description: Copy insurance and registration costs from vehicles table to ownership_costs + +-- Insert insurance costs from vehicles that have insurance data +INSERT INTO ownership_costs ( + user_id, + vehicle_id, + document_id, + cost_type, + description, + amount, + interval, + start_date, + end_date +) +SELECT + v.user_id, + v.id AS vehicle_id, + NULL AS document_id, + 'insurance' AS cost_type, + 'Migrated from vehicle record' AS description, + v.insurance_cost AS amount, + v.insurance_interval AS interval, + COALESCE(v.purchase_date, v.created_at::date) AS start_date, + NULL AS end_date +FROM vehicles v +WHERE v.insurance_cost IS NOT NULL + AND v.insurance_cost > 0 + AND v.insurance_interval IS NOT NULL + AND v.is_active = true + AND NOT EXISTS ( + -- Only migrate if no insurance cost already exists for this vehicle + SELECT 1 FROM ownership_costs oc + WHERE oc.vehicle_id = v.id + AND oc.cost_type = 'insurance' + AND oc.description = 'Migrated from vehicle record' + ); + +-- Insert registration costs from vehicles that have registration data +INSERT INTO ownership_costs ( + user_id, + vehicle_id, + document_id, + cost_type, + description, + amount, + interval, + start_date, + end_date +) +SELECT + v.user_id, + v.id AS vehicle_id, + NULL AS document_id, + 'registration' AS cost_type, + 'Migrated from vehicle record' AS description, + v.registration_cost AS amount, + v.registration_interval AS interval, + COALESCE(v.purchase_date, v.created_at::date) AS start_date, + NULL AS end_date +FROM vehicles v +WHERE v.registration_cost IS NOT NULL + AND v.registration_cost > 0 + AND v.registration_interval IS NOT NULL + AND v.is_active = true + AND NOT EXISTS ( + -- Only migrate if no registration cost already exists for this vehicle + SELECT 1 FROM ownership_costs oc + WHERE oc.vehicle_id = v.id + AND oc.cost_type = 'registration' + AND oc.description = 'Migrated from vehicle record' + ); diff --git a/backend/src/features/vehicles/api/vehicles.controller.ts b/backend/src/features/vehicles/api/vehicles.controller.ts index 3e94dfa..4bf7870 100644 --- a/backend/src/features/vehicles/api/vehicles.controller.ts +++ b/backend/src/features/vehicles/api/vehicles.controller.ts @@ -166,20 +166,20 @@ export class VehiclesController { try { const userId = (request as any).user.sub; const { id } = request.params; - + await this.vehiclesService.deleteVehicle(id, userId); - + return reply.code(204).send(); } catch (error: any) { logger.error('Error deleting vehicle', { error, vehicleId: request.params.id, userId: (request as any).user?.sub }); - + if (error.message === 'Vehicle not found' || error.message === 'Unauthorized') { return reply.code(404).send({ error: 'Not Found', message: 'Vehicle not found' }); } - + return reply.code(500).send({ error: 'Internal server error', message: 'Failed to delete vehicle' @@ -187,6 +187,37 @@ export class VehiclesController { } } + async getTCO(request: FastifyRequest<{ Params: VehicleParams }>, reply: FastifyReply) { + try { + const userId = (request as any).user.sub; + const { id } = request.params; + + const tco = await this.vehiclesService.getTCO(id, userId); + return reply.code(200).send(tco); + } catch (error: any) { + logger.error('Error getting vehicle TCO', { error, vehicleId: request.params.id, userId: (request as any).user?.sub }); + + if (error.statusCode === 404 || error.message === 'Vehicle not found') { + return reply.code(404).send({ + error: 'Not Found', + message: 'Vehicle not found' + }); + } + + if (error.statusCode === 403 || error.message === 'Unauthorized') { + return reply.code(403).send({ + error: 'Forbidden', + message: 'Not authorized to access this vehicle' + }); + } + + return reply.code(500).send({ + error: 'Internal server error', + message: 'Failed to calculate TCO' + }); + } + } + async getDropdownMakes(request: FastifyRequest<{ Querystring: { year: number } }>, reply: FastifyReply) { try { const { year } = request.query; diff --git a/backend/src/features/vehicles/api/vehicles.routes.ts b/backend/src/features/vehicles/api/vehicles.routes.ts index c874441..e82cb6c 100644 --- a/backend/src/features/vehicles/api/vehicles.routes.ts +++ b/backend/src/features/vehicles/api/vehicles.routes.ts @@ -100,6 +100,12 @@ export const vehiclesRoutes: FastifyPluginAsync = async ( handler: vehiclesController.deleteImage.bind(vehiclesController) }); + // GET /api/vehicles/:id/tco - Get vehicle Total Cost of Ownership + fastify.get<{ Params: VehicleParams }>('/vehicles/:id/tco', { + preHandler: [fastify.authenticate], + handler: vehiclesController.getTCO.bind(vehiclesController) + }); + // Dynamic :id routes MUST come last to avoid matching specific paths like "dropdown" // GET /api/vehicles/:id - Get specific vehicle fastify.get<{ Params: VehicleParams }>('/vehicles/:id', { diff --git a/backend/src/features/vehicles/api/vehicles.validation.ts b/backend/src/features/vehicles/api/vehicles.validation.ts index e2538c4..6e8755c 100644 --- a/backend/src/features/vehicles/api/vehicles.validation.ts +++ b/backend/src/features/vehicles/api/vehicles.validation.ts @@ -6,6 +6,9 @@ import { z } from 'zod'; import { isValidVIN } from '../../../shared-minimal/utils/validators'; +// Cost interval enum for TCO recurring costs +const costIntervalSchema = z.enum(['monthly', 'semi_annual', 'annual']); + export const createVehicleSchema = z.object({ vin: z.string() .length(17, 'VIN must be exactly 17 characters') @@ -14,6 +17,14 @@ export const createVehicleSchema = z.object({ color: z.string().min(1).max(50).optional(), licensePlate: z.string().min(1).max(20).optional(), odometerReading: z.number().min(0).max(9999999).optional(), + // TCO fields + purchasePrice: z.number().min(0).max(99999999.99).optional(), + purchaseDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be YYYY-MM-DD').optional(), + insuranceCost: z.number().min(0).max(9999999.99).optional(), + insuranceInterval: costIntervalSchema.optional(), + registrationCost: z.number().min(0).max(9999999.99).optional(), + registrationInterval: costIntervalSchema.optional(), + tcoEnabled: z.boolean().optional(), }); export const updateVehicleSchema = z.object({ @@ -30,6 +41,14 @@ export const updateVehicleSchema = z.object({ color: z.string().min(1).max(50).optional(), licensePlate: z.string().min(1).max(20).optional(), odometerReading: z.number().min(0).max(9999999).optional(), + // TCO fields + purchasePrice: z.number().min(0).max(99999999.99).optional().nullable(), + purchaseDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be YYYY-MM-DD').optional().nullable(), + insuranceCost: z.number().min(0).max(9999999.99).optional().nullable(), + insuranceInterval: costIntervalSchema.optional().nullable(), + registrationCost: z.number().min(0).max(9999999.99).optional().nullable(), + registrationInterval: costIntervalSchema.optional().nullable(), + tcoEnabled: z.boolean().optional(), }); export const vehicleIdSchema = z.object({ diff --git a/backend/src/features/vehicles/data/vehicles.repository.ts b/backend/src/features/vehicles/data/vehicles.repository.ts index 3f2df8a..7e98bae 100644 --- a/backend/src/features/vehicles/data/vehicles.repository.ts +++ b/backend/src/features/vehicles/data/vehicles.repository.ts @@ -4,7 +4,7 @@ */ import { Pool } from 'pg'; -import { Vehicle, CreateVehicleRequest, VehicleImageMeta } from '../domain/vehicles.types'; +import { Vehicle, CreateVehicleRequest, VehicleImageMeta, CostInterval } from '../domain/vehicles.types'; export class VehiclesRepository { constructor(private pool: Pool) {} @@ -12,14 +12,16 @@ export class VehiclesRepository { async create(data: CreateVehicleRequest & { userId: string, make?: string, model?: string, year?: number }): Promise { const query = ` INSERT INTO vehicles ( - user_id, vin, make, model, year, + user_id, vin, make, model, year, engine, transmission, trim_level, drive_type, fuel_type, - nickname, color, license_plate, odometer_reading + nickname, color, license_plate, odometer_reading, + purchase_price, purchase_date, insurance_cost, insurance_interval, + registration_cost, registration_interval, tco_enabled ) - VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14) + VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19, $20, $21) RETURNING * `; - + const values = [ data.userId, (data.vin && data.vin.trim().length > 0) ? data.vin.trim() : null, @@ -34,7 +36,14 @@ export class VehiclesRepository { data.nickname, data.color, data.licensePlate, - data.odometerReading || 0 + data.odometerReading || 0, + data.purchasePrice ?? null, + data.purchaseDate ?? null, + data.insuranceCost ?? null, + data.insuranceInterval ?? null, + data.registrationCost ?? null, + data.registrationInterval ?? null, + data.tcoEnabled ?? false ]; const result = await this.pool.query(query, values); @@ -142,6 +151,35 @@ export class VehiclesRepository { fields.push(`odometer_reading = $${paramCount++}`); values.push(data.odometerReading); } + // TCO fields + if (data.purchasePrice !== undefined) { + fields.push(`purchase_price = $${paramCount++}`); + values.push(data.purchasePrice); + } + if (data.purchaseDate !== undefined) { + fields.push(`purchase_date = $${paramCount++}`); + values.push(data.purchaseDate); + } + if (data.insuranceCost !== undefined) { + fields.push(`insurance_cost = $${paramCount++}`); + values.push(data.insuranceCost); + } + if (data.insuranceInterval !== undefined) { + fields.push(`insurance_interval = $${paramCount++}`); + values.push(data.insuranceInterval); + } + if (data.registrationCost !== undefined) { + fields.push(`registration_cost = $${paramCount++}`); + values.push(data.registrationCost); + } + if (data.registrationInterval !== undefined) { + fields.push(`registration_interval = $${paramCount++}`); + values.push(data.registrationInterval); + } + if (data.tcoEnabled !== undefined) { + fields.push(`tco_enabled = $${paramCount++}`); + values.push(data.tcoEnabled); + } if (fields.length === 0) { return this.findById(id); @@ -193,10 +231,17 @@ export class VehiclesRepository { vehicle.nickname, vehicle.color, vehicle.licensePlate, - vehicle.odometerReading || 0 + vehicle.odometerReading || 0, + vehicle.purchasePrice ?? null, + vehicle.purchaseDate ?? null, + vehicle.insuranceCost ?? null, + vehicle.insuranceInterval ?? null, + vehicle.registrationCost ?? null, + vehicle.registrationInterval ?? null, + vehicle.tcoEnabled ?? false ]; - const placeholder = `($${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++})`; + const placeholder = `($${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++})`; placeholders.push(placeholder); values.push(...vehicleParams); }); @@ -205,7 +250,9 @@ export class VehiclesRepository { INSERT INTO vehicles ( user_id, vin, make, model, year, engine, transmission, trim_level, drive_type, fuel_type, - nickname, color, license_plate, odometer_reading + nickname, color, license_plate, odometer_reading, + purchase_price, purchase_date, insurance_cost, insurance_interval, + registration_cost, registration_interval, tco_enabled ) VALUES ${placeholders.join(', ')} RETURNING * @@ -292,6 +339,14 @@ export class VehiclesRepository { imageFileName: row.image_file_name, imageContentType: row.image_content_type, imageFileSize: row.image_file_size, + // TCO fields + purchasePrice: row.purchase_price ? Number(row.purchase_price) : undefined, + purchaseDate: row.purchase_date, + insuranceCost: row.insurance_cost ? Number(row.insurance_cost) : undefined, + insuranceInterval: row.insurance_interval as CostInterval | undefined, + registrationCost: row.registration_cost ? Number(row.registration_cost) : undefined, + registrationInterval: row.registration_interval as CostInterval | undefined, + tcoEnabled: row.tco_enabled, }; } } diff --git a/backend/src/features/vehicles/domain/vehicles.service.ts b/backend/src/features/vehicles/domain/vehicles.service.ts index cde91b5..4ab2b6f 100644 --- a/backend/src/features/vehicles/domain/vehicles.service.ts +++ b/backend/src/features/vehicles/domain/vehicles.service.ts @@ -10,7 +10,10 @@ import { CreateVehicleRequest, UpdateVehicleRequest, VehicleResponse, - VehicleImageMeta + VehicleImageMeta, + TCOResponse, + CostInterval, + PAYMENTS_PER_YEAR } from './vehicles.types'; import { logger } from '../../../core/logging/logger'; import { cacheService } from '../../../core/config/redis'; @@ -25,6 +28,11 @@ import { NHTSAClient, NHTSADecodeResponse, DecodedVehicleData, MatchedField } fr import { canAddVehicle, getVehicleLimitConfig } from '../../../core/config/feature-tiers'; import { UserProfileRepository } from '../../user-profile/data/user-profile.repository'; import { SubscriptionTier } from '../../user-profile/domain/user-profile.types'; +import { OwnershipCostsService } from '../../ownership-costs'; +import { FuelLogsService } from '../../fuel-logs/domain/fuel-logs.service'; +import { FuelLogsRepository } from '../../fuel-logs/data/fuel-logs.repository'; +import { MaintenanceService } from '../../maintenance/domain/maintenance.service'; +import { UserSettingsService } from '../../fuel-logs/external/user-settings.service'; export class VehicleLimitExceededError extends Error { constructor( @@ -378,6 +386,129 @@ export class VehiclesService { ).catch(err => logger.error('Failed to log vehicle delete audit event', { error: err })); } + async getTCO(id: string, userId: string): Promise { + // Get vehicle and verify ownership + const vehicle = await this.repository.findById(id); + if (!vehicle) { + const err: any = new Error('Vehicle not found'); + err.statusCode = 404; + throw err; + } + if (vehicle.userId !== userId) { + const err: any = new Error('Unauthorized'); + err.statusCode = 403; + throw err; + } + + // Get user preferences for units + const userSettings = await UserSettingsService.getUserSettings(userId); + const distanceUnit = userSettings.unitSystem === 'metric' ? 'km' : 'mi'; + const currencyCode = userSettings.currencyCode || 'USD'; + + // Get fuel costs from fuel-logs service + const fuelLogsRepository = new FuelLogsRepository(this.pool); + const fuelLogsService = new FuelLogsService(fuelLogsRepository); + let fuelCosts = 0; + try { + const fuelStats = await fuelLogsService.getVehicleStats(id, userId); + fuelCosts = fuelStats.totalCost || 0; + } catch { + // Vehicle may have no fuel logs + fuelCosts = 0; + } + + // Get maintenance costs from maintenance service + const maintenanceService = new MaintenanceService(); + let maintenanceCosts = 0; + try { + const maintenanceStats = await maintenanceService.getVehicleMaintenanceCosts(id, userId); + maintenanceCosts = maintenanceStats.totalCost || 0; + } catch { + // Vehicle may have no maintenance records + maintenanceCosts = 0; + } + + // Get fixed costs from vehicle record + const purchasePrice = vehicle.purchasePrice || 0; + + // Get recurring ownership costs from ownership-costs service + const ownershipCostsService = new OwnershipCostsService(this.pool); + let insuranceCosts = 0; + let registrationCosts = 0; + let taxCosts = 0; + let otherCosts = 0; + try { + const ownershipStats = await ownershipCostsService.getVehicleCostStats(id, userId); + insuranceCosts = ownershipStats.insuranceCosts || 0; + registrationCosts = ownershipStats.registrationCosts || 0; + taxCosts = ownershipStats.taxCosts || 0; + otherCosts = ownershipStats.otherCosts || 0; + } catch { + // Vehicle may have no ownership cost records + // Fall back to legacy vehicle fields if they exist + insuranceCosts = this.normalizeRecurringCost( + vehicle.insuranceCost, + vehicle.insuranceInterval, + vehicle.purchaseDate + ); + registrationCosts = this.normalizeRecurringCost( + vehicle.registrationCost, + vehicle.registrationInterval, + vehicle.purchaseDate + ); + } + + // Calculate lifetime total (includes all ownership costs: insurance, registration, tax, other) + const lifetimeTotal = purchasePrice + insuranceCosts + registrationCosts + taxCosts + otherCosts + fuelCosts + maintenanceCosts; + + // Calculate cost per distance + const odometerReading = vehicle.odometerReading || 0; + const costPerDistance = odometerReading > 0 ? lifetimeTotal / odometerReading : 0; + + return { + vehicleId: id, + purchasePrice, + insuranceCosts, + registrationCosts, + taxCosts, + otherCosts, + fuelCosts, + maintenanceCosts, + lifetimeTotal, + costPerDistance, + distanceUnit, + currencyCode + }; + } + + private normalizeRecurringCost( + cost: number | null | undefined, + interval: CostInterval | null | undefined, + purchaseDate: string | null | undefined + ): number { + if (!cost || !interval || !purchaseDate) return 0; + + const monthsOwned = Math.max(1, this.calculateMonthsOwned(purchaseDate)); + const paymentsPerYear = PAYMENTS_PER_YEAR[interval]; + if (!paymentsPerYear) { + throw new Error(`Invalid cost interval: ${interval}`); + } + const totalPayments = (monthsOwned / 12) * paymentsPerYear; + return cost * totalPayments; + } + + private calculateMonthsOwned(purchaseDate: string): number { + const purchase = new Date(purchaseDate); + const now = new Date(); + // Guard against future dates - treat as 0 months owned + if (purchase > now) { + return 0; + } + const yearDiff = now.getFullYear() - purchase.getFullYear(); + const monthDiff = now.getMonth() - purchase.getMonth(); + return yearDiff * 12 + monthDiff; + } + async getVehicleRaw(id: string, userId: string): Promise { const vehicle = await this.repository.findById(id); if (!vehicle || vehicle.userId !== userId) { diff --git a/backend/src/features/vehicles/domain/vehicles.types.ts b/backend/src/features/vehicles/domain/vehicles.types.ts index 3c14334..024d54c 100644 --- a/backend/src/features/vehicles/domain/vehicles.types.ts +++ b/backend/src/features/vehicles/domain/vehicles.types.ts @@ -3,6 +3,15 @@ * @ai-context Core business types, no external dependencies */ +// TCO cost interval types +export type CostInterval = 'monthly' | 'semi_annual' | 'annual'; + +export const PAYMENTS_PER_YEAR: Record = { + monthly: 12, + semi_annual: 2, + annual: 1, +} as const; + export interface Vehicle { id: string; userId: string; @@ -28,6 +37,14 @@ export interface Vehicle { imageFileName?: string; imageContentType?: string; imageFileSize?: number; + // TCO fields + purchasePrice?: number; + purchaseDate?: string; + insuranceCost?: number; + insuranceInterval?: CostInterval; + registrationCost?: number; + registrationInterval?: CostInterval; + tcoEnabled?: boolean; } export interface CreateVehicleRequest { @@ -44,6 +61,14 @@ export interface CreateVehicleRequest { color?: string; licensePlate?: string; odometerReading?: number; + // TCO fields + purchasePrice?: number; + purchaseDate?: string; + insuranceCost?: number; + insuranceInterval?: CostInterval; + registrationCost?: number; + registrationInterval?: CostInterval; + tcoEnabled?: boolean; } export interface UpdateVehicleRequest { @@ -60,6 +85,14 @@ export interface UpdateVehicleRequest { color?: string; licensePlate?: string; odometerReading?: number; + // TCO fields + purchasePrice?: number; + purchaseDate?: string; + insuranceCost?: number; + insuranceInterval?: CostInterval; + registrationCost?: number; + registrationInterval?: CostInterval; + tcoEnabled?: boolean; } export interface VehicleResponse { @@ -82,6 +115,14 @@ export interface VehicleResponse { createdAt: string; updatedAt: string; imageUrl?: string; + // TCO fields + purchasePrice?: number; + purchaseDate?: string; + insuranceCost?: number; + insuranceInterval?: CostInterval; + registrationCost?: number; + registrationInterval?: CostInterval; + tcoEnabled?: boolean; } export interface VehicleImageMeta { @@ -116,6 +157,14 @@ export interface CreateVehicleBody { color?: string; licensePlate?: string; odometerReading?: number; + // TCO fields + purchasePrice?: number; + purchaseDate?: string; + insuranceCost?: number; + insuranceInterval?: CostInterval; + registrationCost?: number; + registrationInterval?: CostInterval; + tcoEnabled?: boolean; } export interface UpdateVehicleBody { @@ -132,8 +181,32 @@ export interface UpdateVehicleBody { color?: string; licensePlate?: string; odometerReading?: number; + // TCO fields + purchasePrice?: number; + purchaseDate?: string; + insuranceCost?: number; + insuranceInterval?: CostInterval; + registrationCost?: number; + registrationInterval?: CostInterval; + tcoEnabled?: boolean; } export interface VehicleParams { id: string; } + +// TCO (Total Cost of Ownership) response +export interface TCOResponse { + vehicleId: string; + purchasePrice: number; + insuranceCosts: number; + registrationCosts: number; + taxCosts: number; + otherCosts: number; + fuelCosts: number; + maintenanceCosts: number; + lifetimeTotal: number; + costPerDistance: number; + distanceUnit: string; + currencyCode: string; +} diff --git a/backend/src/features/vehicles/migrations/006_add_tco_fields.sql b/backend/src/features/vehicles/migrations/006_add_tco_fields.sql new file mode 100644 index 0000000..0f1e993 --- /dev/null +++ b/backend/src/features/vehicles/migrations/006_add_tco_fields.sql @@ -0,0 +1,33 @@ +-- Migration: Add TCO (Total Cost of Ownership) fields to vehicles table +-- Issue: #15 + +ALTER TABLE vehicles + ADD COLUMN IF NOT EXISTS purchase_price DECIMAL(12,2), + ADD COLUMN IF NOT EXISTS purchase_date DATE, + ADD COLUMN IF NOT EXISTS insurance_cost DECIMAL(10,2), + ADD COLUMN IF NOT EXISTS insurance_interval VARCHAR(20), + ADD COLUMN IF NOT EXISTS registration_cost DECIMAL(10,2), + ADD COLUMN IF NOT EXISTS registration_interval VARCHAR(20), + ADD COLUMN IF NOT EXISTS tco_enabled BOOLEAN DEFAULT false; + +-- Add CHECK constraints to enforce valid interval values +ALTER TABLE vehicles + ADD CONSTRAINT chk_insurance_interval + CHECK (insurance_interval IS NULL OR insurance_interval IN ('monthly', 'semi_annual', 'annual')); + +ALTER TABLE vehicles + ADD CONSTRAINT chk_registration_interval + CHECK (registration_interval IS NULL OR registration_interval IN ('monthly', 'semi_annual', 'annual')); + +-- Add CHECK constraints for non-negative costs +ALTER TABLE vehicles + ADD CONSTRAINT chk_purchase_price_non_negative + CHECK (purchase_price IS NULL OR purchase_price >= 0); + +ALTER TABLE vehicles + ADD CONSTRAINT chk_insurance_cost_non_negative + CHECK (insurance_cost IS NULL OR insurance_cost >= 0); + +ALTER TABLE vehicles + ADD CONSTRAINT chk_registration_cost_non_negative + CHECK (registration_cost IS NULL OR registration_cost >= 0); diff --git a/backend/src/features/vehicles/tests/unit/vehicles.service.test.ts b/backend/src/features/vehicles/tests/unit/vehicles.service.test.ts index 2f413dd..d1d3c4e 100644 --- a/backend/src/features/vehicles/tests/unit/vehicles.service.test.ts +++ b/backend/src/features/vehicles/tests/unit/vehicles.service.test.ts @@ -91,32 +91,32 @@ describe('VehiclesService', () => { it('retrieves models scoped to year and make', async () => { vehicleDataServiceMock.getModels.mockResolvedValue([{ id: 20, name: 'Civic' }]); - const result = await service.getDropdownModels(2024, 10); + const result = await service.getDropdownModels(2024, 'Honda'); - expect(vehicleDataServiceMock.getModels).toHaveBeenCalledWith('mock-pool', 2024, 10); + expect(vehicleDataServiceMock.getModels).toHaveBeenCalledWith('mock-pool', 2024, 'Honda'); expect(result).toEqual([{ id: 20, name: 'Civic' }]); }); it('retrieves trims scoped to year, make, and model', async () => { vehicleDataServiceMock.getTrims.mockResolvedValue([{ id: 30, name: 'Sport' }]); - const result = await service.getDropdownTrims(2024, 10, 20); + const result = await service.getDropdownTrims(2024, 'Honda', 'Civic'); - expect(vehicleDataServiceMock.getTrims).toHaveBeenCalledWith('mock-pool', 2024, 20); + expect(vehicleDataServiceMock.getTrims).toHaveBeenCalledWith('mock-pool', 2024, 'Honda', 'Civic'); expect(result).toEqual([{ id: 30, name: 'Sport' }]); }); it('retrieves engines scoped to selection', async () => { vehicleDataServiceMock.getEngines.mockResolvedValue([{ id: 40, name: '2.0L Turbo' }]); - const result = await service.getDropdownEngines(2024, 10, 20, 30); + const result = await service.getDropdownEngines(2024, 'Honda', 'Civic', 'Sport'); - expect(vehicleDataServiceMock.getEngines).toHaveBeenCalledWith('mock-pool', 2024, 20, 30); + expect(vehicleDataServiceMock.getEngines).toHaveBeenCalledWith('mock-pool', 2024, 'Honda', 'Civic', 'Sport'); expect(result).toEqual([{ id: 40, name: '2.0L Turbo' }]); }); it('returns static transmission options', async () => { - const result = await service.getDropdownTransmissions(2024, 10, 20); + const result = await service.getDropdownTransmissions(2024, 'Honda', 'Civic', 'Sport'); expect(result).toEqual([ { id: 1, name: 'Automatic' }, @@ -355,4 +355,237 @@ describe('VehiclesService', () => { await expect(service.deleteVehicle('vehicle-id-123', 'user-123')).rejects.toThrow('Unauthorized'); }); }); + + describe('getTCO', () => { + const mockVehicle = { + id: 'vehicle-id-123', + userId: 'user-123', + vin: '1HGBH41JXMN109186', + make: 'Honda', + model: 'Civic', + year: 2021, + odometerReading: 50000, + isActive: true, + purchasePrice: 25000, + purchaseDate: '2022-01-15', + insuranceCost: 150, + insuranceInterval: 'monthly' as const, + registrationCost: 200, + registrationInterval: 'annual' as const, + tcoEnabled: true, + createdAt: new Date('2024-01-01T00:00:00Z'), + updatedAt: new Date('2024-01-01T00:00:00Z'), + }; + + it('should throw error if vehicle not found', async () => { + repositoryInstance.findById.mockResolvedValue(null); + + await expect(service.getTCO('vehicle-id-123', 'user-123')).rejects.toThrow('Vehicle not found'); + }); + + it('should throw error if user is not owner', async () => { + repositoryInstance.findById.mockResolvedValue({ ...mockVehicle, userId: 'other-user' }); + + await expect(service.getTCO('vehicle-id-123', 'user-123')).rejects.toThrow('Unauthorized'); + }); + + it('should return TCO with all cost components', async () => { + repositoryInstance.findById.mockResolvedValue(mockVehicle); + + const result = await service.getTCO('vehicle-id-123', 'user-123'); + + expect(result.vehicleId).toBe('vehicle-id-123'); + expect(result.purchasePrice).toBe(25000); + expect(result.lifetimeTotal).toBeGreaterThan(25000); + expect(result.distanceUnit).toBeDefined(); + expect(result.currencyCode).toBeDefined(); + }); + + it('should handle missing optional TCO fields gracefully', async () => { + const vehicleWithoutTCO = { + ...mockVehicle, + purchasePrice: undefined, + purchaseDate: undefined, + insuranceCost: undefined, + insuranceInterval: undefined, + registrationCost: undefined, + registrationInterval: undefined, + }; + repositoryInstance.findById.mockResolvedValue(vehicleWithoutTCO); + + const result = await service.getTCO('vehicle-id-123', 'user-123'); + + expect(result.purchasePrice).toBe(0); + expect(result.insuranceCosts).toBe(0); + expect(result.registrationCosts).toBe(0); + }); + + it('should return zero costPerDistance when odometer is zero', async () => { + const vehicleWithZeroOdometer = { ...mockVehicle, odometerReading: 0 }; + repositoryInstance.findById.mockResolvedValue(vehicleWithZeroOdometer); + + const result = await service.getTCO('vehicle-id-123', 'user-123'); + + expect(result.costPerDistance).toBe(0); + }); + + it('should calculate costPerDistance correctly', async () => { + const vehicleWith100Miles = { + ...mockVehicle, + odometerReading: 100, + purchasePrice: 1000, + insuranceCost: undefined, + registrationCost: undefined, + purchaseDate: undefined, + }; + repositoryInstance.findById.mockResolvedValue(vehicleWith100Miles); + + const result = await service.getTCO('vehicle-id-123', 'user-123'); + + // With only $1000 purchase price and 100 miles, costPerDistance should be ~$10/mile + // (plus any fuel/maintenance costs which may be 0 in mock) + expect(result.costPerDistance).toBeGreaterThan(0); + }); + }); + + describe('normalizeRecurringCost (via getTCO)', () => { + it('should normalize monthly costs correctly', async () => { + // Vehicle purchased 12 months ago with $100/month insurance + const oneYearAgo = new Date(); + oneYearAgo.setFullYear(oneYearAgo.getFullYear() - 1); + + const mockVehicle = { + id: 'vehicle-id-123', + userId: 'user-123', + odometerReading: 10000, + isActive: true, + purchasePrice: 0, + purchaseDate: oneYearAgo.toISOString().split('T')[0], + insuranceCost: 100, + insuranceInterval: 'monthly' as const, + registrationCost: 0, + tcoEnabled: true, + createdAt: new Date(), + updatedAt: new Date(), + }; + repositoryInstance.findById.mockResolvedValue(mockVehicle); + + const result = await service.getTCO('vehicle-id-123', 'user-123'); + + // 12 months * $100/month = $1200 insurance + expect(result.insuranceCosts).toBeCloseTo(1200, 0); + }); + + it('should normalize annual costs correctly', async () => { + // Vehicle purchased 24 months ago with $200/year registration + const twoYearsAgo = new Date(); + twoYearsAgo.setFullYear(twoYearsAgo.getFullYear() - 2); + + const mockVehicle = { + id: 'vehicle-id-123', + userId: 'user-123', + odometerReading: 20000, + isActive: true, + purchasePrice: 0, + purchaseDate: twoYearsAgo.toISOString().split('T')[0], + insuranceCost: 0, + registrationCost: 200, + registrationInterval: 'annual' as const, + tcoEnabled: true, + createdAt: new Date(), + updatedAt: new Date(), + }; + repositoryInstance.findById.mockResolvedValue(mockVehicle); + + const result = await service.getTCO('vehicle-id-123', 'user-123'); + + // 2 years * $200/year = $400 registration + expect(result.registrationCosts).toBeCloseTo(400, 0); + }); + + it('should handle semi-annual costs correctly', async () => { + // Vehicle purchased 12 months ago with $300/6months insurance + const oneYearAgo = new Date(); + oneYearAgo.setFullYear(oneYearAgo.getFullYear() - 1); + + const mockVehicle = { + id: 'vehicle-id-123', + userId: 'user-123', + odometerReading: 10000, + isActive: true, + purchasePrice: 0, + purchaseDate: oneYearAgo.toISOString().split('T')[0], + insuranceCost: 300, + insuranceInterval: 'semi_annual' as const, + registrationCost: 0, + tcoEnabled: true, + createdAt: new Date(), + updatedAt: new Date(), + }; + repositoryInstance.findById.mockResolvedValue(mockVehicle); + + const result = await service.getTCO('vehicle-id-123', 'user-123'); + + // 12 months / 12 * 2 payments/year * $300 = $600 insurance + expect(result.insuranceCosts).toBeCloseTo(600, 0); + }); + + it('should guard against division by zero with new purchase', async () => { + // Vehicle purchased today + const today = new Date().toISOString().split('T')[0]; + + const mockVehicle = { + id: 'vehicle-id-123', + userId: 'user-123', + odometerReading: 0, + isActive: true, + purchasePrice: 30000, + purchaseDate: today, + insuranceCost: 100, + insuranceInterval: 'monthly' as const, + registrationCost: 0, + tcoEnabled: true, + createdAt: new Date(), + updatedAt: new Date(), + }; + repositoryInstance.findById.mockResolvedValue(mockVehicle); + + // Should not throw - Math.max(1, monthsOwned) should prevent division by zero + const result = await service.getTCO('vehicle-id-123', 'user-123'); + + expect(result.lifetimeTotal).toBeGreaterThanOrEqual(30000); + // Insurance should be calculated for at least 1 month + expect(result.insuranceCosts).toBeGreaterThan(0); + }); + + it('should handle future purchase date gracefully', async () => { + // Vehicle with purchase date in the future (should treat as 0 months) + const futureDate = new Date(); + futureDate.setFullYear(futureDate.getFullYear() + 1); + + const mockVehicle = { + id: 'vehicle-id-123', + userId: 'user-123', + odometerReading: 0, + isActive: true, + purchasePrice: 30000, + purchaseDate: futureDate.toISOString().split('T')[0], + insuranceCost: 100, + insuranceInterval: 'monthly' as const, + registrationCost: 0, + tcoEnabled: true, + createdAt: new Date(), + updatedAt: new Date(), + }; + repositoryInstance.findById.mockResolvedValue(mockVehicle); + + // Should not throw + const result = await service.getTCO('vehicle-id-123', 'user-123'); + + expect(result.purchasePrice).toBe(30000); + // With future date, monthsOwned returns 0, but Math.max(1, 0) = 1 + // so insurance should still calculate for minimum 1 payment period + expect(result.insuranceCosts).toBeGreaterThanOrEqual(0); + }); + }); }); diff --git a/frontend/src/features/ownership-costs/api/ownership-costs.api.ts b/frontend/src/features/ownership-costs/api/ownership-costs.api.ts new file mode 100644 index 0000000..57c300b --- /dev/null +++ b/frontend/src/features/ownership-costs/api/ownership-costs.api.ts @@ -0,0 +1,60 @@ +/** + * @ai-summary API calls for ownership-costs feature + */ + +import { apiClient } from '../../../core/api/client'; +import { + OwnershipCost, + CreateOwnershipCostRequest, + UpdateOwnershipCostRequest, + OwnershipCostStats +} from '../types/ownership-costs.types'; + +export const ownershipCostsApi = { + /** + * Get all ownership costs for a vehicle + */ + getByVehicle: async (vehicleId: string): Promise => { + const response = await apiClient.get(`/ownership-costs/vehicle/${vehicleId}`); + return response.data; + }, + + /** + * Get a single ownership cost by ID + */ + getById: async (id: string): Promise => { + const response = await apiClient.get(`/ownership-costs/${id}`); + return response.data; + }, + + /** + * Create a new ownership cost + */ + create: async (data: CreateOwnershipCostRequest): Promise => { + const response = await apiClient.post('/ownership-costs', data); + return response.data; + }, + + /** + * Update an existing ownership cost + */ + update: async (id: string, data: UpdateOwnershipCostRequest): Promise => { + const response = await apiClient.put(`/ownership-costs/${id}`, data); + return response.data; + }, + + /** + * Delete an ownership cost + */ + delete: async (id: string): Promise => { + await apiClient.delete(`/ownership-costs/${id}`); + }, + + /** + * Get aggregated cost stats for a vehicle + */ + getVehicleStats: async (vehicleId: string): Promise => { + const response = await apiClient.get(`/ownership-costs/vehicle/${vehicleId}/stats`); + return response.data; + }, +}; diff --git a/frontend/src/features/ownership-costs/components/OwnershipCostForm.tsx b/frontend/src/features/ownership-costs/components/OwnershipCostForm.tsx new file mode 100644 index 0000000..8030b9f --- /dev/null +++ b/frontend/src/features/ownership-costs/components/OwnershipCostForm.tsx @@ -0,0 +1,214 @@ +/** + * @ai-summary Form component for adding/editing ownership costs + */ + +import React, { useState, useEffect } from 'react'; +import { Button } from '../../../shared-minimal/components/Button'; +import { + OwnershipCost, + OwnershipCostType, + CostInterval, + COST_TYPE_LABELS, + INTERVAL_LABELS +} from '../types/ownership-costs.types'; + +interface OwnershipCostFormProps { + vehicleId: string; + initialData?: OwnershipCost; + onSubmit: (data: { + costType: OwnershipCostType; + description?: string; + amount: number; + interval: CostInterval; + startDate: string; + endDate?: string; + }) => Promise; + onCancel: () => void; + loading?: boolean; +} + +export const OwnershipCostForm: React.FC = ({ + initialData, + onSubmit, + onCancel, + loading, +}) => { + const [costType, setCostType] = useState(initialData?.costType || 'insurance'); + const [description, setDescription] = useState(initialData?.description || ''); + const [amount, setAmount] = useState(initialData?.amount?.toString() || ''); + const [interval, setInterval] = useState(initialData?.interval || 'monthly'); + const [startDate, setStartDate] = useState(initialData?.startDate || new Date().toISOString().split('T')[0]); + const [endDate, setEndDate] = useState(initialData?.endDate || ''); + const [error, setError] = useState(null); + + useEffect(() => { + if (initialData) { + setCostType(initialData.costType); + setDescription(initialData.description || ''); + setAmount(initialData.amount.toString()); + setInterval(initialData.interval); + setStartDate(initialData.startDate); + setEndDate(initialData.endDate || ''); + } + }, [initialData]); + + const handleSubmit = async (e: React.FormEvent) => { + e.preventDefault(); + setError(null); + + // Validate amount + const parsedAmount = parseFloat(amount); + if (isNaN(parsedAmount) || parsedAmount < 0) { + setError('Please enter a valid amount'); + return; + } + + // Validate dates + if (!startDate) { + setError('Start date is required'); + return; + } + + if (endDate && new Date(endDate) < new Date(startDate)) { + setError('End date must be after start date'); + return; + } + + try { + await onSubmit({ + costType, + description: description.trim() || undefined, + amount: parsedAmount, + interval, + startDate, + endDate: endDate || undefined, + }); + } catch (err: unknown) { + const message = err instanceof Error ? err.message : 'Failed to save cost'; + setError(message); + } + }; + + const isEditMode = !!initialData; + + return ( +
+ {error && ( +
+ {error} +
+ )} + +
+ + +
+ +
+ + setDescription(e.target.value)} + placeholder="e.g., Geico Full Coverage" + className="w-full px-3 py-2 border rounded-md min-h-[44px] bg-white text-gray-900 border-gray-300 placeholder-gray-500 focus:outline-none focus:ring-2 focus:ring-primary-500 dark:bg-scuro dark:text-avus dark:border-silverstone dark:placeholder-canna" + style={{ fontSize: '16px' }} + /> +
+ +
+
+ + setAmount(e.target.value)} + placeholder="0.00" + inputMode="decimal" + step="0.01" + min="0" + required + className="w-full px-3 py-2 border rounded-md min-h-[44px] bg-white text-gray-900 border-gray-300 placeholder-gray-500 focus:outline-none focus:ring-2 focus:ring-primary-500 dark:bg-scuro dark:text-avus dark:border-silverstone dark:placeholder-canna" + style={{ fontSize: '16px' }} + /> +
+ +
+ + +
+
+ +
+
+ + setStartDate(e.target.value)} + required + className="w-full px-3 py-2 border rounded-md min-h-[44px] bg-white text-gray-900 border-gray-300 focus:outline-none focus:ring-2 focus:ring-primary-500 dark:bg-scuro dark:text-avus dark:border-silverstone" + style={{ fontSize: '16px' }} + /> +
+ +
+ + setEndDate(e.target.value)} + className="w-full px-3 py-2 border rounded-md min-h-[44px] bg-white text-gray-900 border-gray-300 focus:outline-none focus:ring-2 focus:ring-primary-500 dark:bg-scuro dark:text-avus dark:border-silverstone" + style={{ fontSize: '16px' }} + /> +

+ Leave blank for ongoing costs +

+
+
+ +
+ + +
+
+ ); +}; diff --git a/frontend/src/features/ownership-costs/components/OwnershipCostsList.tsx b/frontend/src/features/ownership-costs/components/OwnershipCostsList.tsx new file mode 100644 index 0000000..3b69dfb --- /dev/null +++ b/frontend/src/features/ownership-costs/components/OwnershipCostsList.tsx @@ -0,0 +1,210 @@ +/** + * @ai-summary List component for displaying ownership costs + */ + +import React, { useState } from 'react'; +import { + OwnershipCost, + CreateOwnershipCostRequest, + COST_TYPE_LABELS, + INTERVAL_LABELS +} from '../types/ownership-costs.types'; +import { OwnershipCostForm } from './OwnershipCostForm'; +import { useOwnershipCosts } from '../hooks/useOwnershipCosts'; +import { Button } from '../../../shared-minimal/components/Button'; + +interface OwnershipCostsListProps { + vehicleId: string; +} + +export const OwnershipCostsList: React.FC = ({ + vehicleId, +}) => { + const { costs, isLoading, error, createCost, updateCost, deleteCost } = useOwnershipCosts(vehicleId); + const [showForm, setShowForm] = useState(false); + const [editingCost, setEditingCost] = useState(null); + const [isSubmitting, setIsSubmitting] = useState(false); + const [deleteConfirm, setDeleteConfirm] = useState(null); + + const handleSubmit = async (data: Omit) => { + setIsSubmitting(true); + try { + if (editingCost) { + await updateCost(editingCost.id, data); + } else { + await createCost({ ...data, vehicleId }); + } + setShowForm(false); + setEditingCost(null); + } finally { + setIsSubmitting(false); + } + }; + + const handleEdit = (cost: OwnershipCost) => { + setEditingCost(cost); + setShowForm(true); + }; + + const handleDelete = async (id: string) => { + try { + await deleteCost(id); + setDeleteConfirm(null); + } catch (err) { + console.error('Failed to delete cost:', err); + } + }; + + const handleCancel = () => { + setShowForm(false); + setEditingCost(null); + }; + + // Format currency + const formatCurrency = (value: number): string => { + return value.toLocaleString(undefined, { + minimumFractionDigits: 2, + maximumFractionDigits: 2, + }); + }; + + // Format date + const formatDate = (dateString: string): string => { + return new Date(dateString).toLocaleDateString(); + }; + + if (isLoading) { + return ( +
+ {[1, 2].map((i) => ( +
+ ))} +
+ ); + } + + if (error) { + // Show a subtle message if the feature isn't set up yet, don't block the page + return ( +
+
+

+ Recurring Costs +

+
+
+

Recurring costs tracking is being set up.

+

Run migrations to enable this feature.

+
+
+ ); + } + + return ( +
+
+

+ Recurring Costs +

+ {!showForm && ( + + )} +
+ + {showForm && ( +
+

+ {editingCost ? 'Edit Cost' : 'Add New Cost'} +

+ +
+ )} + + {costs.length === 0 && !showForm ? ( +
+

No recurring costs added yet.

+

Track insurance, registration, and other recurring vehicle costs.

+
+ ) : ( +
+ {costs.map((cost) => ( +
+
+
+
+ + {COST_TYPE_LABELS[cost.costType]} + + + {INTERVAL_LABELS[cost.interval]} + +
+ {cost.description && ( +

+ {cost.description} +

+ )} +

+ {formatDate(cost.startDate)} + {cost.endDate ? ` - ${formatDate(cost.endDate)}` : ' - Ongoing'} +

+
+
+
+ ${formatCurrency(cost.amount)} +
+
+ + {deleteConfirm === cost.id ? ( +
+ + +
+ ) : ( + + )} +
+
+
+
+ ))} +
+ )} +
+ ); +}; diff --git a/frontend/src/features/ownership-costs/hooks/useOwnershipCosts.ts b/frontend/src/features/ownership-costs/hooks/useOwnershipCosts.ts new file mode 100644 index 0000000..c7c568e --- /dev/null +++ b/frontend/src/features/ownership-costs/hooks/useOwnershipCosts.ts @@ -0,0 +1,75 @@ +/** + * @ai-summary React hook for ownership costs management + */ + +import { useState, useEffect, useCallback } from 'react'; +import { ownershipCostsApi } from '../api/ownership-costs.api'; +import { + OwnershipCost, + CreateOwnershipCostRequest, + UpdateOwnershipCostRequest +} from '../types/ownership-costs.types'; + +interface UseOwnershipCostsResult { + costs: OwnershipCost[]; + isLoading: boolean; + error: string | null; + refresh: () => Promise; + createCost: (data: CreateOwnershipCostRequest) => Promise; + updateCost: (id: string, data: UpdateOwnershipCostRequest) => Promise; + deleteCost: (id: string) => Promise; +} + +export function useOwnershipCosts(vehicleId: string): UseOwnershipCostsResult { + const [costs, setCosts] = useState([]); + const [isLoading, setIsLoading] = useState(false); + const [error, setError] = useState(null); + + const fetchCosts = useCallback(async () => { + if (!vehicleId) return; + + setIsLoading(true); + setError(null); + try { + const data = await ownershipCostsApi.getByVehicle(vehicleId); + setCosts(data); + } catch (err: unknown) { + const message = err instanceof Error ? err.message : 'Failed to load ownership costs'; + setError(message); + console.error('Failed to fetch ownership costs:', err); + } finally { + setIsLoading(false); + } + }, [vehicleId]); + + useEffect(() => { + fetchCosts(); + }, [fetchCosts]); + + const createCost = useCallback(async (data: CreateOwnershipCostRequest): Promise => { + const newCost = await ownershipCostsApi.create(data); + setCosts(prev => [newCost, ...prev]); + return newCost; + }, []); + + const updateCost = useCallback(async (id: string, data: UpdateOwnershipCostRequest): Promise => { + const updated = await ownershipCostsApi.update(id, data); + setCosts(prev => prev.map(cost => cost.id === id ? updated : cost)); + return updated; + }, []); + + const deleteCost = useCallback(async (id: string): Promise => { + await ownershipCostsApi.delete(id); + setCosts(prev => prev.filter(cost => cost.id !== id)); + }, []); + + return { + costs, + isLoading, + error, + refresh: fetchCosts, + createCost, + updateCost, + deleteCost, + }; +} diff --git a/frontend/src/features/ownership-costs/index.ts b/frontend/src/features/ownership-costs/index.ts new file mode 100644 index 0000000..45a863e --- /dev/null +++ b/frontend/src/features/ownership-costs/index.ts @@ -0,0 +1,25 @@ +/** + * @ai-summary Public API for ownership-costs frontend feature + */ + +// Export components +export { OwnershipCostForm } from './components/OwnershipCostForm'; +export { OwnershipCostsList } from './components/OwnershipCostsList'; + +// Export hooks +export { useOwnershipCosts } from './hooks/useOwnershipCosts'; + +// Export API +export { ownershipCostsApi } from './api/ownership-costs.api'; + +// Export types +export type { + OwnershipCost, + CreateOwnershipCostRequest, + UpdateOwnershipCostRequest, + OwnershipCostStats, + OwnershipCostType, + CostInterval +} from './types/ownership-costs.types'; + +export { COST_TYPE_LABELS, INTERVAL_LABELS } from './types/ownership-costs.types'; diff --git a/frontend/src/features/ownership-costs/types/ownership-costs.types.ts b/frontend/src/features/ownership-costs/types/ownership-costs.types.ts new file mode 100644 index 0000000..6bd6338 --- /dev/null +++ b/frontend/src/features/ownership-costs/types/ownership-costs.types.ts @@ -0,0 +1,70 @@ +/** + * @ai-summary Type definitions for ownership-costs feature + */ + +// Cost types supported by ownership-costs feature +export type OwnershipCostType = 'insurance' | 'registration' | 'tax' | 'other'; + +// Cost interval types +export type CostInterval = 'monthly' | 'semi_annual' | 'annual' | 'one_time'; + +export interface OwnershipCost { + id: string; + userId: string; + vehicleId: string; + documentId?: string; + costType: OwnershipCostType; + description?: string; + amount: number; + interval: CostInterval; + startDate: string; + endDate?: string; + createdAt: string; + updatedAt: string; +} + +export interface CreateOwnershipCostRequest { + vehicleId: string; + documentId?: string; + costType: OwnershipCostType; + description?: string; + amount: number; + interval: CostInterval; + startDate: string; + endDate?: string; +} + +export interface UpdateOwnershipCostRequest { + documentId?: string | null; + costType?: OwnershipCostType; + description?: string | null; + amount?: number; + interval?: CostInterval; + startDate?: string; + endDate?: string | null; +} + +// Aggregated cost statistics +export interface OwnershipCostStats { + insuranceCosts: number; + registrationCosts: number; + taxCosts: number; + otherCosts: number; + totalCosts: number; +} + +// Display labels for cost types +export const COST_TYPE_LABELS: Record = { + insurance: 'Insurance', + registration: 'Registration', + tax: 'Tax', + other: 'Other', +}; + +// Display labels for intervals +export const INTERVAL_LABELS: Record = { + monthly: 'Monthly', + semi_annual: 'Semi-Annual (6 months)', + annual: 'Annual', + one_time: 'One-Time', +}; diff --git a/frontend/src/features/vehicles/api/vehicles.api.ts b/frontend/src/features/vehicles/api/vehicles.api.ts index ed409c7..d24d6b0 100644 --- a/frontend/src/features/vehicles/api/vehicles.api.ts +++ b/frontend/src/features/vehicles/api/vehicles.api.ts @@ -3,7 +3,7 @@ */ import { apiClient } from '../../../core/api/client'; -import { Vehicle, CreateVehicleRequest, UpdateVehicleRequest, DecodedVehicleData } from '../types/vehicles.types'; +import { Vehicle, CreateVehicleRequest, UpdateVehicleRequest, DecodedVehicleData, TCOResponse } from '../types/vehicles.types'; // All requests (including dropdowns) use authenticated apiClient @@ -88,5 +88,13 @@ export const vehiclesApi = { decodeVin: async (vin: string): Promise => { const response = await apiClient.post('/vehicles/decode-vin', { vin }); return response.data; + }, + + /** + * Get Total Cost of Ownership data for a vehicle + */ + getTCO: async (vehicleId: string): Promise => { + const response = await apiClient.get(`/vehicles/${vehicleId}/tco`); + return response.data; } }; diff --git a/frontend/src/features/vehicles/components/TCODisplay.tsx b/frontend/src/features/vehicles/components/TCODisplay.tsx new file mode 100644 index 0000000..32a5187 --- /dev/null +++ b/frontend/src/features/vehicles/components/TCODisplay.tsx @@ -0,0 +1,140 @@ +/** + * @ai-summary TCO (Total Cost of Ownership) display component + * Right-justified display showing lifetime cost and cost per mile/km + */ + +import React, { useEffect, useState } from 'react'; +import { TCOResponse } from '../types/vehicles.types'; +import { vehiclesApi } from '../api/vehicles.api'; + +interface TCODisplayProps { + vehicleId: string; + tcoEnabled?: boolean; +} + +// Currency symbol mapping +const CURRENCY_SYMBOLS: Record = { + USD: '$', + EUR: '€', + GBP: '£', + CAD: 'CA$', + AUD: 'A$', +}; + +export const TCODisplay: React.FC = ({ vehicleId, tcoEnabled }) => { + const [tco, setTco] = useState(null); + const [isLoading, setIsLoading] = useState(false); + const [error, setError] = useState(null); + + useEffect(() => { + if (!tcoEnabled) { + setTco(null); + return; + } + + const fetchTCO = async () => { + setIsLoading(true); + setError(null); + try { + const data = await vehiclesApi.getTCO(vehicleId); + setTco(data); + } catch (err: any) { + console.error('Failed to fetch TCO:', err); + setError('Unable to load TCO data'); + } finally { + setIsLoading(false); + } + }; + + fetchTCO(); + }, [vehicleId, tcoEnabled]); + + // Don't render if TCO is disabled + if (!tcoEnabled) { + return null; + } + + // Loading state + if (isLoading) { + return ( +
+
+
+
+
+
+ ); + } + + // Error state + if (error) { + return ( +
+ {error} +
+ ); + } + + // No data + if (!tco) { + return null; + } + + const currencySymbol = CURRENCY_SYMBOLS[tco.currencyCode] || tco.currencyCode; + + // Format currency with proper separators + const formatCurrency = (value: number): string => { + return value.toLocaleString(undefined, { + minimumFractionDigits: 2, + maximumFractionDigits: 2, + }); + }; + + return ( +
+
+ {currencySymbol}{formatCurrency(tco.lifetimeTotal)} +
+
+ Lifetime Total +
+ {tco.costPerDistance > 0 && ( + <> +
+ {currencySymbol}{formatCurrency(tco.costPerDistance)}/{tco.distanceUnit} +
+
+ Cost per {tco.distanceUnit} +
+ + )} + + {/* Cost breakdown tooltip/details */} +
+
+ {tco.purchasePrice > 0 && ( +
Purchase: {currencySymbol}{formatCurrency(tco.purchasePrice)}
+ )} + {tco.insuranceCosts > 0 && ( +
Insurance: {currencySymbol}{formatCurrency(tco.insuranceCosts)}
+ )} + {tco.registrationCosts > 0 && ( +
Registration: {currencySymbol}{formatCurrency(tco.registrationCosts)}
+ )} + {tco.taxCosts > 0 && ( +
Tax: {currencySymbol}{formatCurrency(tco.taxCosts)}
+ )} + {tco.otherCosts > 0 && ( +
Other: {currencySymbol}{formatCurrency(tco.otherCosts)}
+ )} + {tco.fuelCosts > 0 && ( +
Fuel: {currencySymbol}{formatCurrency(tco.fuelCosts)}
+ )} + {tco.maintenanceCosts > 0 && ( +
Maintenance: {currencySymbol}{formatCurrency(tco.maintenanceCosts)}
+ )} +
+
+
+ ); +}; diff --git a/frontend/src/features/vehicles/components/VehicleForm.tsx b/frontend/src/features/vehicles/components/VehicleForm.tsx index 559d351..094becf 100644 --- a/frontend/src/features/vehicles/components/VehicleForm.tsx +++ b/frontend/src/features/vehicles/components/VehicleForm.tsx @@ -7,12 +7,19 @@ import { useForm } from 'react-hook-form'; import { zodResolver } from '@hookform/resolvers/zod'; import { z } from 'zod'; import { Button } from '../../../shared-minimal/components/Button'; -import { CreateVehicleRequest, Vehicle } from '../types/vehicles.types'; +import { CreateVehicleRequest, Vehicle, CostInterval } from '../types/vehicles.types'; import { vehiclesApi } from '../api/vehicles.api'; import { VehicleImageUpload } from './VehicleImageUpload'; import { useTierAccess } from '../../../core/hooks/useTierAccess'; import { UpgradeRequiredDialog } from '../../../shared-minimal/components/UpgradeRequiredDialog'; +// Cost interval options +const costIntervalOptions: { value: CostInterval; label: string }[] = [ + { value: 'monthly', label: 'Monthly' }, + { value: 'semi_annual', label: 'Semi-Annual (6 months)' }, + { value: 'annual', label: 'Annual' }, +]; + const vehicleSchema = z .object({ vin: z.string().max(17).nullable().optional().transform(val => val ?? undefined), @@ -28,6 +35,14 @@ const vehicleSchema = z color: z.string().nullable().optional(), licensePlate: z.string().nullable().optional(), odometerReading: z.number().min(0).nullable().optional(), + // TCO fields + purchasePrice: z.number().min(0).nullable().optional(), + purchaseDate: z.string().nullable().optional(), + insuranceCost: z.number().min(0).nullable().optional(), + insuranceInterval: z.enum(['monthly', 'semi_annual', 'annual']).nullable().optional(), + registrationCost: z.number().min(0).nullable().optional(), + registrationInterval: z.enum(['monthly', 'semi_annual', 'annual']).nullable().optional(), + tcoEnabled: z.boolean().nullable().optional(), }) .refine( (data) => { @@ -824,6 +839,131 @@ export const VehicleForm: React.FC = ({ />
+ {/* Ownership Costs Section (TCO) */} +
+

+ Ownership Costs +

+

+ Track your total cost of ownership including purchase price and recurring costs. +

+ +
+
+ + +
+ +
+ + +
+
+ +
+
+ + +
+ +
+ + +
+
+ +
+
+ + +
+ +
+ + +
+
+ +
+ +

+ When enabled, shows lifetime cost and cost per mile/km on the vehicle detail page. +

+
+
+
- + {/* Recurring Ownership Costs */} + + + + Vehicle Records diff --git a/frontend/src/features/vehicles/types/vehicles.types.ts b/frontend/src/features/vehicles/types/vehicles.types.ts index 13bab8e..8238c1d 100644 --- a/frontend/src/features/vehicles/types/vehicles.types.ts +++ b/frontend/src/features/vehicles/types/vehicles.types.ts @@ -2,6 +2,9 @@ * @ai-summary Type definitions for vehicles feature */ +// TCO cost interval types +export type CostInterval = 'monthly' | 'semi_annual' | 'annual'; + export interface Vehicle { id: string; userId: string; @@ -22,6 +25,14 @@ export interface Vehicle { createdAt: string; updatedAt: string; imageUrl?: string; + // TCO fields + purchasePrice?: number; + purchaseDate?: string; + insuranceCost?: number; + insuranceInterval?: CostInterval; + registrationCost?: number; + registrationInterval?: CostInterval; + tcoEnabled?: boolean; } export interface CreateVehicleRequest { @@ -38,6 +49,14 @@ export interface CreateVehicleRequest { color?: string; licensePlate?: string; odometerReading?: number; + // TCO fields + purchasePrice?: number; + purchaseDate?: string; + insuranceCost?: number; + insuranceInterval?: CostInterval; + registrationCost?: number; + registrationInterval?: CostInterval; + tcoEnabled?: boolean; } export interface UpdateVehicleRequest { @@ -54,6 +73,30 @@ export interface UpdateVehicleRequest { color?: string; licensePlate?: string; odometerReading?: number; + // TCO fields + purchasePrice?: number | null; + purchaseDate?: string | null; + insuranceCost?: number | null; + insuranceInterval?: CostInterval | null; + registrationCost?: number | null; + registrationInterval?: CostInterval | null; + tcoEnabled?: boolean; +} + +// TCO (Total Cost of Ownership) response +export interface TCOResponse { + vehicleId: string; + purchasePrice: number; + insuranceCosts: number; + registrationCosts: number; + taxCosts: number; + otherCosts: number; + fuelCosts: number; + maintenanceCosts: number; + lifetimeTotal: number; + costPerDistance: number; + distanceUnit: string; + currencyCode: string; } /** diff --git a/frontend/src/shared-minimal/components/VehicleLimitDialog.test.tsx b/frontend/src/shared-minimal/components/VehicleLimitDialog.test.tsx index 75ddfad..b057cbb 100644 --- a/frontend/src/shared-minimal/components/VehicleLimitDialog.test.tsx +++ b/frontend/src/shared-minimal/components/VehicleLimitDialog.test.tsx @@ -3,7 +3,6 @@ * @ai-context Validates props, mobile/desktop modes, and user interactions */ -import React from 'react'; import { render, screen, fireEvent } from '@testing-library/react'; import '@testing-library/jest-dom'; import { VehicleLimitDialog } from './VehicleLimitDialog';