Merge pull request #39 from Watergirll/main

[Watergirll]

✨ Implement Appointment Management Endpoints: Availability, Creation, and Update

📌 Overview

This PR introduces three new endpoints to enhance the appointment management system for students:

1. GET /api/student/files/{fileId}/available-slots?date=YYYY-MM-DD

Retrieves available appointment slots for a specific date, considering:

• Teaching category's session duration
• Instructor's availability and existing appointments
• Vehicle's availability (if assigned)

Returns:

• Session duration
• List of available time slots

---

2. POST /api/student/files/{fileId}/appointments

Creates a new appointment. Validates:

• File ownership and required assignments (instructor, teaching category)
• Appointment date is in the future
• Time format and logical correctness
• Session duration matches teaching category
• Instructor availability and scheduling conflicts
• Vehicle availability (if assigned)

---

3. PUT /api/student/appointments/update/{appointmentId}

Updates an existing appointment. Includes all validations from the POST endpoint, plus:

• Appointment ownership verification

---

✅ Key Features

• Consistent Validation Logic: Ensures only valid, conflict-free appointments are created or updated.
• Ownership Checks: Validates that the student owns the file and appointment.
• Session Duration Matching: Aligns each appointment's duration with the teaching category’s specified session time.
• Conflict Prevention: Avoids double-booking instructors or vehicles.
• Maintainable Code Structure: Reuses logic and patterns consistent with existing endpoints.

---

🔍 Additional Details

• Error Handling: Provides structured and meaningful error responses.
• Slot Calculation Logic: Dynamically calculates available time slots based on multiple constraints (instructor schedule, existing appointments, vehicle status).
• Scalability: Logic is modular and can support future feature additions (e.g., cancellation rules, appointment reminders).

---

🧪 Testing

• Unit tests for all endpoints, covering:
  • Success cases
  • Validation failures
  • Edge cases (e.g., back-to-back appointments, daylight saving changes)
• Integration tests for:
  • Data interactions
  • Error propagation
  • Security checks (ownership)

---

📎 Notes

• Designed to be extensible (e.g., support for group sessions, instructor overrides)
• All code adheres to current architectural conventions and coding standards

---

Let me know if you'd like an overview of a specific part of the implementation.