feat: add ownership-costs feature capsule (refs #15)

- Create ownership_costs table for recurring vehicle costs - Add backend feature capsule with types, repository, service, routes - Update TCO calculation to use ownership_costs (with fallback to legacy vehicle fields) - Add taxCosts and otherCosts to TCO response - Create frontend ownership-costs feature with form, list, API, hooks - Update TCODisplay to show all cost types This implements a more flexible approach to tracking recurring ownership costs (insurance, registration, tax, other) with explicit date ranges and optional document association. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-12 21:28:25 -06:00
parent 5c93150a58
commit a8c4eba8d1
19 changed files with 1644 additions and 15 deletions
--- a/backend/src/features/ownership-costs/api/ownership-costs.controller.ts
+++ 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'
+      });
+    }
+  }
+}
--- a/backend/src/features/ownership-costs/api/ownership-costs.routes.ts
+++ 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');
+}
--- a/backend/src/features/ownership-costs/data/ownership-costs.repository.ts
+++ 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<OwnershipCost> {
+    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<OwnershipCost[]> {
+    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<OwnershipCost[]> {
+    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<OwnershipCost | null> {
+    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<OwnershipCost[]> {
+    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<OwnershipCost | null> {
+    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<boolean> {
+    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<CreateOwnershipCostRequest & { userId: string }>,
+    client?: Pool
+  ): Promise<OwnershipCost[]> {
+    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<string, unknown>) => this.mapRow(row));
+  }
+
+  private mapRow(row: Record<string, unknown>): 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,
+    };
+  }
+}
--- a/backend/src/features/ownership-costs/domain/ownership-costs.service.ts
+++ 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<OwnershipCostResponse> {
+    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<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 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 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');
+    }
+
+    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<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');
+    }
+
+    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 });
+      }
+    }
+
+    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,
+    };
+  }
+}
--- a/backend/src/features/ownership-costs/domain/ownership-costs.types.ts
+++ 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<CostInterval, number> = {
+  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;
+}
--- a/backend/src/features/ownership-costs/index.ts
+++ 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';
--- 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
@@ -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();
--- 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
@@ -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'
+  );
--- a/backend/src/features/vehicles/domain/vehicles.service.ts
+++ b/backend/src/features/vehicles/domain/vehicles.service.ts
@@ -28,6 +28,7 @@ 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';
@@ -430,20 +431,35 @@ export class VehiclesService {
    // Get fixed costs from vehicle record
    const purchasePrice = vehicle.purchasePrice || 0;

-    // Normalize recurring costs based on purchase date
-    const insuranceCosts = this.normalizeRecurringCost(
-      vehicle.insuranceCost,
-      vehicle.insuranceInterval,
-      vehicle.purchaseDate
-    );
-    const registrationCosts = this.normalizeRecurringCost(
-      vehicle.registrationCost,
-      vehicle.registrationInterval,
-      vehicle.purchaseDate
-    );
+    // 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
-    const lifetimeTotal = purchasePrice + insuranceCosts + registrationCosts + fuelCosts + maintenanceCosts;
+    // 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;
@@ -454,6 +470,8 @@ export class VehiclesService {
      purchasePrice,
      insuranceCosts,
      registrationCosts,
+      taxCosts,
+      otherCosts,
      fuelCosts,
      maintenanceCosts,
      lifetimeTotal,
--- a/backend/src/features/vehicles/domain/vehicles.types.ts
+++ b/backend/src/features/vehicles/domain/vehicles.types.ts
@@ -201,6 +201,8 @@ export interface TCOResponse {
  purchasePrice: number;
  insuranceCosts: number;
  registrationCosts: number;
+  taxCosts: number;
+  otherCosts: number;
  fuelCosts: number;
  maintenanceCosts: number;
  lifetimeTotal: number;