Task Car Service History

Task: Car Service History (Beginner-Friendly Version)

1. What problem are we solving?

Each car can be serviced many times:

• oil change
• tire replacement
• brake service
• diagnostics

We need a way to:

• store those service records
• attach them to the correct car
• allow the user to view, add, edit, and delete them

Think of it like:

One car → many service history records

---

2. Architecture Overview (IMPORTANT)

Separate Service = Separate Responsibility

We will create a separate backend service called:

CarServiceHistoryService

This service:

• does NOT manage cars
• does NOT create or update car data
• only manages service history records

The Car Service (already existing) owns car data. The Service History Service only references cars by vehicleId.

👉 This keeps services small, simple, and independent.

---

3. How do we store service history in MongoDB?

❓ Embed history inside car document?

NO. Here’s why:

If we store service history inside the car document:

• car document grows forever
• pagination becomes hard
• updates are more complex
• one service history change rewrites the whole car document

This is bad design for real systems.

---

✅ Correct approach: Separate collection

We create a separate MongoDB collection:

serviceHistory

Each document represents one service event.

---

4. MongoDB Document Structure

Collection: serviceHistory

{
  "_id": "GUID",
  "vehicleId": "GUID",
  "title": "Oil Change",
  "description": "Replaced oil and filter",
  "price": 120,
  "createdDate": "2026-01-10T10:30:00Z",
  "updatedDate": "2026-01-10T10:30:00Z"
}

Key idea

• vehicleId is how we connect service history to a car
• MongoDB does not enforce relationships
• Our code is responsible for correctness

---

5. How is a car tied to its service history?

There is no direct MongoDB relation like SQL foreign keys.

Instead:

• each service record stores vehicleId

• when we want service history for a car:

  find all serviceHistory where vehicleId = X
  

Example:

Car ID:

vehicleId = "abc-123"

Query:

db.serviceHistory.find({ vehicleId: "abc-123" })

That’s it. Simple and fast.

---

6. Indexing (VERY IMPORTANT)

We must create an index:

vehicleId + createdDate

Why?

• we query by vehicleId
• we sort by createdDate

Without an index → slow queries later.

---

7. Service Responsibilities (Clear Boundaries)

Car Service

• creates cars
• updates car info
• deletes cars

Car Service History Service

• stores service records
• validates input
• never edits car data
• only works with vehicleId

If a car is deleted:

• service history is not automatically deleted
• that decision belongs to business logic (out of scope for now)

---

8. API Endpoints (Explained Simply)

1️⃣ Get Service History for a Car

GET

/vehicles/{vehicleId}/service-history

What it does:

• finds all service records for that car
• returns paginated result
• newest records first

Why pagination? Because a car can have hundreds of records.

Response DTO:

{
  "title": "Oil Change",
  "price": 120,
  "createdDate": "2026-01-10"
}

We don’t return everything — only what the UI needs.

---

2️⃣ Create Service History Record

POST

/vehicles/{vehicleId}/service-history

Rules:

• vehicleId comes from URL

• do NOT accept it from request body

• validate:

  • title not empty
  • price ≥ 0

System sets:

• createdDate
• updatedDate

---

3️⃣ Update Service History Record

PUT

/vehicles/{vehicleId}/service-history/{itemId}

Steps:

1. Find item by itemId
2. Check that vehicleId matches
3. Update fields
4. Update updatedDate

❌ Do not allow moving record to another vehicle

---

4️⃣ Delete Service History Record

DELETE

/vehicles/{vehicleId}/service-history/{itemId}

Steps:

• verify record exists
• verify it belongs to vehicle
• delete it

---

9. Validation Rules (Trainee-Level)

Field	Rule
title	required, max 256
description	optional
price	required, >= 0
vehicleId	required, from route
createdDate	set by system
updatedDate	set by system

---

10. What You Should NOT Do (Common Trainee Mistakes)

❌ Store service history inside car document ❌ Trust client to send vehicleId ❌ Return MongoDB document directly ❌ Forget pagination ❌ Allow editing createdDate ❌ Update item that belongs to another car

Any of these = rework.

---

11. Definition of Done (Crystal Clear)

• Separate MongoDB collection
• Indexed by vehicleId
• CRUD endpoints working
• Pagination implemented
• DTOs used
• Validation in place
• Clean, readable code