feat: create ownership_costs backend feature capsule (refs #29)
Milestone 1: Complete backend feature with: - Migration with CHECK (amount > 0) constraint - Repository with mapRow() for snake_case -> camelCase - Service with CRUD and vehicle authorization - Controller with HTTP handlers - Routes registered at /api/ownership-costs - Validation with Zod schemas - README with endpoint documentation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Eric Gullickson
@@ -1,199 +1,141 @@
|
||||
/**
|
||||
* @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,
|
||||
import { randomUUID } from 'crypto';
|
||||
import type { Pool } from 'pg';
|
||||
import type {
|
||||
CreateOwnershipCostRequest,
|
||||
UpdateOwnershipCostRequest,
|
||||
OwnershipCost,
|
||||
OwnershipCostResponse,
|
||||
OwnershipCostStats,
|
||||
PAYMENTS_PER_YEAR,
|
||||
OwnershipCostType
|
||||
OwnershipCostType,
|
||||
OwnershipCostStats
|
||||
} from './ownership-costs.types';
|
||||
import { logger } from '../../../core/logging/logger';
|
||||
import { VehiclesRepository } from '../../vehicles/data/vehicles.repository';
|
||||
import { OwnershipCostsRepository } from '../data/ownership-costs.repository';
|
||||
import pool from '../../../core/config/database';
|
||||
|
||||
export class OwnershipCostsService {
|
||||
private repository: OwnershipCostsRepository;
|
||||
private vehiclesRepository: VehiclesRepository;
|
||||
private readonly repo: OwnershipCostsRepository;
|
||||
private readonly db: Pool;
|
||||
|
||||
constructor(pool: Pool) {
|
||||
this.repository = new OwnershipCostsRepository(pool);
|
||||
this.vehiclesRepository = new VehiclesRepository(pool);
|
||||
constructor(dbPool?: Pool) {
|
||||
this.db = dbPool || pool;
|
||||
this.repo = new OwnershipCostsRepository(this.db);
|
||||
}
|
||||
|
||||
async create(data: CreateOwnershipCostRequest, userId: string): Promise<OwnershipCostResponse> {
|
||||
logger.info('Creating ownership cost', { userId, vehicleId: data.vehicleId, costType: data.costType });
|
||||
async createCost(userId: string, body: CreateOwnershipCostRequest): Promise<OwnershipCost> {
|
||||
await this.assertVehicleOwnership(userId, body.vehicleId);
|
||||
|
||||
// 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 id = randomUUID();
|
||||
const cost = await this.repo.insert({
|
||||
id,
|
||||
userId,
|
||||
vehicleId: body.vehicleId,
|
||||
documentId: body.documentId,
|
||||
costType: body.costType,
|
||||
amount: body.amount,
|
||||
description: body.description,
|
||||
periodStart: body.periodStart,
|
||||
periodEnd: body.periodEnd,
|
||||
notes: body.notes,
|
||||
});
|
||||
|
||||
const cost = await this.repository.create({ ...data, userId });
|
||||
return cost;
|
||||
}
|
||||
|
||||
async getCost(userId: string, id: string): Promise<OwnershipCostResponse | null> {
|
||||
const cost = await this.repo.findById(id, userId);
|
||||
if (!cost) return null;
|
||||
return this.toResponse(cost);
|
||||
}
|
||||
|
||||
async getByVehicleId(vehicleId: string, userId: string): Promise<OwnershipCostResponse[]> {
|
||||
// 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 getCosts(userId: string, filters?: { vehicleId?: string; costType?: OwnershipCostType; documentId?: string }): Promise<OwnershipCostResponse[]> {
|
||||
const costs = await this.repo.findByUserId(userId, filters);
|
||||
return costs.map(c => this.toResponse(c));
|
||||
}
|
||||
|
||||
async getById(id: string, userId: string): Promise<OwnershipCostResponse> {
|
||||
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 getCostsByVehicle(userId: string, vehicleId: string): Promise<OwnershipCostResponse[]> {
|
||||
const costs = await this.repo.findByVehicleId(vehicleId, userId);
|
||||
return costs.map(c => this.toResponse(c));
|
||||
}
|
||||
|
||||
async update(id: string, data: UpdateOwnershipCostRequest, userId: string): Promise<OwnershipCostResponse> {
|
||||
// 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');
|
||||
}
|
||||
async getVehicleOwnershipCosts(vehicleId: string, userId: string): Promise<OwnershipCostStats> {
|
||||
const costs = await this.repo.findByVehicleId(vehicleId, userId);
|
||||
|
||||
const updated = await this.repository.update(id, data);
|
||||
if (!updated) {
|
||||
throw new Error('Update failed');
|
||||
}
|
||||
let totalCost = 0;
|
||||
let insuranceCosts = 0;
|
||||
let registrationCosts = 0;
|
||||
let taxCosts = 0;
|
||||
let otherCosts = 0;
|
||||
|
||||
return this.toResponse(updated);
|
||||
}
|
||||
for (const c of costs) {
|
||||
if (c.amount === null || c.amount === undefined) continue;
|
||||
const amount = Number(c.amount);
|
||||
if (isNaN(amount)) {
|
||||
throw new Error(`Invalid amount value for ownership cost ${c.id}`);
|
||||
}
|
||||
|
||||
async delete(id: string, userId: string): Promise<void> {
|
||||
// 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');
|
||||
}
|
||||
totalCost += amount;
|
||||
|
||||
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<OwnershipCostStats> {
|
||||
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<OwnershipCostType, keyof Omit<OwnershipCostStats, 'totalCosts'>> = {
|
||||
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 });
|
||||
// Breakdown by cost type for backward compatibility
|
||||
switch (c.costType) {
|
||||
case 'insurance':
|
||||
insuranceCosts += amount;
|
||||
break;
|
||||
case 'registration':
|
||||
registrationCosts += amount;
|
||||
break;
|
||||
case 'tax':
|
||||
taxCosts += amount;
|
||||
break;
|
||||
case 'inspection':
|
||||
case 'parking':
|
||||
case 'other':
|
||||
otherCosts += amount;
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
stats.totalCosts = stats.insuranceCosts + stats.registrationCosts + stats.taxCosts + stats.otherCosts;
|
||||
return stats;
|
||||
return {
|
||||
totalCost,
|
||||
recordCount: costs.length,
|
||||
insuranceCosts,
|
||||
registrationCosts,
|
||||
taxCosts,
|
||||
otherCosts
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 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);
|
||||
// Alias for backward compatibility with vehicles service
|
||||
async getVehicleCostStats(vehicleId: string, userId: string): Promise<OwnershipCostStats> {
|
||||
return this.getVehicleOwnershipCosts(vehicleId, userId);
|
||||
}
|
||||
|
||||
/**
|
||||
* 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;
|
||||
}
|
||||
async updateCost(userId: string, id: string, patch: UpdateOwnershipCostRequest): Promise<OwnershipCostResponse | null> {
|
||||
const existing = await this.repo.findById(id, userId);
|
||||
if (!existing) return null;
|
||||
|
||||
const paymentsPerYear = PAYMENTS_PER_YEAR[interval as keyof typeof PAYMENTS_PER_YEAR];
|
||||
if (!paymentsPerYear) {
|
||||
logger.warn('Invalid cost interval', { interval });
|
||||
return 0;
|
||||
}
|
||||
// Convert nulls to undefined for repository compatibility
|
||||
const cleanPatch = Object.fromEntries(
|
||||
Object.entries(patch).map(([k, v]) => [k, v === null ? undefined : v])
|
||||
) as Partial<Pick<OwnershipCost, 'documentId' | 'costType' | 'amount' | 'description' | 'periodStart' | 'periodEnd' | 'notes'>>;
|
||||
|
||||
// Calculate total payments over the covered period
|
||||
const yearsOwned = monthsCovered / 12;
|
||||
const totalPayments = yearsOwned * paymentsPerYear;
|
||||
return amount * totalPayments;
|
||||
const updated = await this.repo.update(id, userId, cleanPatch);
|
||||
if (!updated) return null;
|
||||
return this.toResponse(updated);
|
||||
}
|
||||
|
||||
async deleteCost(userId: string, id: string): Promise<void> {
|
||||
await this.repo.delete(id, userId);
|
||||
}
|
||||
|
||||
private async assertVehicleOwnership(userId: string, vehicleId: string) {
|
||||
const res = await this.db.query('SELECT id FROM vehicles WHERE id = $1 AND user_id = $2', [vehicleId, userId]);
|
||||
if (!res.rows[0]) {
|
||||
const err: any = new Error('Vehicle not found or not owned by user');
|
||||
err.statusCode = 403;
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
|
||||
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,
|
||||
};
|
||||
return cost;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,108 +1,69 @@
|
||||
/**
|
||||
* @ai-summary Type definitions for ownership-costs feature
|
||||
* @ai-context Tracks vehicle ownership costs (insurance, registration, tax, other)
|
||||
* @ai-context Tracks vehicle ownership costs (insurance, registration, tax, inspection, parking, other)
|
||||
*/
|
||||
|
||||
// Cost types supported by ownership-costs feature
|
||||
export type OwnershipCostType = 'insurance' | 'registration' | 'tax' | 'other';
|
||||
import { z } from 'zod';
|
||||
|
||||
// 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<CostInterval, number> = {
|
||||
monthly: 12,
|
||||
semi_annual: 2,
|
||||
annual: 1,
|
||||
one_time: 0, // Special case: calculated differently
|
||||
} as const;
|
||||
// Ownership cost types
|
||||
export type OwnershipCostType = 'insurance' | 'registration' | 'tax' | 'inspection' | 'parking' | 'other';
|
||||
|
||||
// Database record type (camelCase for TypeScript)
|
||||
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;
|
||||
periodStart?: string;
|
||||
periodEnd?: string;
|
||||
notes?: string;
|
||||
createdAt: string;
|
||||
updatedAt: string;
|
||||
}
|
||||
|
||||
// Aggregated cost statistics for TCO calculation
|
||||
// Zod schemas for validation (camelCase for API)
|
||||
export const OwnershipCostTypeSchema = z.enum(['insurance', 'registration', 'tax', 'inspection', 'parking', 'other']);
|
||||
|
||||
export const CreateOwnershipCostSchema = z.object({
|
||||
vehicleId: z.string().uuid(),
|
||||
documentId: z.string().uuid().optional(),
|
||||
costType: OwnershipCostTypeSchema,
|
||||
amount: z.number().positive(),
|
||||
description: z.string().max(200).optional(),
|
||||
periodStart: z.string().optional(),
|
||||
periodEnd: z.string().optional(),
|
||||
notes: z.string().max(10000).optional(),
|
||||
});
|
||||
export type CreateOwnershipCostRequest = z.infer<typeof CreateOwnershipCostSchema>;
|
||||
|
||||
export const UpdateOwnershipCostSchema = z.object({
|
||||
documentId: z.string().uuid().nullable().optional(),
|
||||
costType: OwnershipCostTypeSchema.optional(),
|
||||
amount: z.number().positive().optional(),
|
||||
description: z.string().max(200).nullable().optional(),
|
||||
periodStart: z.string().nullable().optional(),
|
||||
periodEnd: z.string().nullable().optional(),
|
||||
notes: z.string().max(10000).nullable().optional(),
|
||||
});
|
||||
export type UpdateOwnershipCostRequest = z.infer<typeof UpdateOwnershipCostSchema>;
|
||||
|
||||
// Response types
|
||||
export interface OwnershipCostResponse extends OwnershipCost {}
|
||||
|
||||
// TCO aggregation stats
|
||||
// NOTE: Extended for backward compatibility with vehicles service
|
||||
// The spec calls for totalCost and recordCount only, but the vehicles service
|
||||
// expects breakdown by cost type. This will be cleaned up when vehicles service
|
||||
// is refactored to use the new ownership-costs table directly.
|
||||
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;
|
||||
totalCost: number;
|
||||
recordCount: number;
|
||||
// Backward compatibility fields for vehicles service
|
||||
insuranceCosts?: number;
|
||||
registrationCosts?: number;
|
||||
taxCosts?: number;
|
||||
otherCosts?: number;
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user