Merge branch 'add/api-mapping-lichhocvien' into 'develop'

add/api-mapping-lichhocvien

See merge request !7

API_Mapping_LichHocVien.md

+# Tài liệu Gắn API: Màn hình "Quản lý Lịch Học Viên"
+
+Tài liệu này mô tả chi tiết việc ánh xạ các thành phần giao diện (UI) trên màn hình "Quản lý Lịch Học Viên" với các RESTful API tương ứng của backend (dự án `trainee-schedule-2`).
+
+---
+
+## 1. Hành vi khi tải trang ban đầu (Initial Page Load)
+
+Khi người dùng (Admin) vừa mở màn hình "Quản lý Lịch Học Viên", Frontend cần gọi đồng thời các API sau để khởi tạo dữ liệu cho các bộ lọc trước.
+
+### 1.1 Lấy dữ liệu cho Dropdown "Tất cả khóa học"
+*   **Method:** `GET`
+*   **Endpoint:** `/api/v1.0/courses`
+*   **Mô tả:** Lấy danh sách toàn bộ các khóa học đang có trong hệ thống để người dùng có thể lọc danh sách học viên theo khóa.
+*   **Query Parameters dự kiến:** 
+    *   Có thể cần cấu hình `pageSize` lớn để lấy tất cả (VD: `?pageSize=1000`) để tránh bị thiếu sót dữ liệu trên dropdown.
+*   **Response mapping:** Trích xuất mảng dữ liệu (data.rows) lấy `id` làm value và `name` làm hiển thị hiển thị trên list.
+
+### 1.2 Lấy dữ liệu cho Dropdown "Tất cả kỳ"
+*   **Method:** `GET`
+*   **Endpoint:** `/api/v1.0/terms`
+*   **Mô tả:** Lấy danh sách các học kỳ (Term) để đưa vào dropdown lọc theo kỳ.
+*   **Query Parameters dự kiến:** Tương tự khóa học, có thể cần lấy không giới hạn số lượng.
+*   **Response mapping:** Trích xuất mảng dữ liệu lấy `id` làm value và giá trị tên kỳ/thời gian làm text hiển thị.
+
+---
+
+## 2. API hiển thị Bảng dữ liệu chính
+
+Đây là API quan trọng nhất, chịu trách nhiệm lấy thông tin chi tiết từng học viên cùng với lịch của họ. Được gọi **SAU KHI** đã xác định được khoảng thời gian (Tuần hiển thị hiện tại) từ thanh điều hướng trên cùng, hoặc khi người dùng thay đổi bộ lọc.
+
+### 2.1 Lấy danh sách học viên và lịch học
+*   **Method:** `GET`
+*   **Endpoint:** `/api/v1.0/students` (hoặc `/api/v1.0/schedules` tùy theo thiết kế nối bảng phía BE)
+    > **Note cho Frontend:** Vui lòng xác nhận lại với Backend xem endpoint hiển thị trên giao diện này gọi vào resource root nào, thông thường sẽ gọi qua `/api/v1.0/students` kèm query params.
+
+*   **Query Parameters bắt buộc:**
+    *   `startDate`: Ngày bắt đầu của tuần (VD: `2026-04-13T00:00:00Z`)
+    *   `endDate`: Ngày kết thúc của tuần (VD: `2026-04-19T23:59:59Z`)
+    *   `page`: Trang hiện tại (Mặc định: 1)
+    *   `pageSize`: Số record một trang (Mặc định: 10 hoặc 20)
+
+*   **Query Parameters tùy chọn (khi dùng Filter/Search):**
+    *   `search` (hoặc `filters[name]`): Dữ liệu từ ô input "Tìm học viên..."
+    *   `filters[courseId]` (hoặc tham số tương đương): Dữ liệu khi chọn Dropdown Khóa học.
+    *   `filters[termId]` (hoặc tham số tương đương): Dữ liệu khi chọn Dropdown Kỳ học.
+
+*   **Cấu trúc hiển thị & Mapping:** 
+    Mỗi hàng (row) dữ liệu trả về cần render ra các cột:
+    1.  **Họ và tên:** `student.name`
+    2.  **Khóa học:** `student.course.name` (hoặc lookup từ mảng danh sách course của học viện)
+    3.  **Kỳ:** `student.term.name`
+    4.  **Các thứ trong tuần (Thứ 2 - CN):** Cần duyệt qua mảng `schedules` của học viên trả về, filter theo ngày để map nội dung ca học vào từng ô tương ứng trong bảng.
+
+---
+
+## 3. Các thao tác tương tác & CRUD
+
+### 3.1 Nút "+ Thêm học viên"
+Khi bấm nút, Frontend sẽ mở ra Modal và sau khi điền thông tin, Submit form sẽ dùng API này:
+*   **Method:** `POST`
+*   **Endpoint:** `/api/v1.0/students`
+*   **Body Request:** Json chứa các trường thông tin quy định trên form (VD: Họ tên, Mã SV, Mã lớp, Mã Khóa học,... theo DTO validations của BE).
+*   **Hành động sau khi thành công (Status HTTP 200):** Tắt modal, hiển thị Toast Notify (Thành công), và **gọi lại API phần 2.1** để refresh lại bảng dữ liệu.
+
+### 3.2 Thanh điều hướng ngày tháng (< Hôm nay >)
+Đây thuần túy là các handle logic phía Frontend sử dụng thư viện xử lý ngày tháng (như `date-fns`, `moment`, `dayjs`). Các nút này **không gắn API riêng.**
+*   **Cơ chế hoạt động:**
+    1. Click mũi tên "<", ">": Tăng giảm tuần hiển thị (+7 ngày / -7 ngày).
+    2. Tính toán lại biến state `startDate` và `endDate`.
+    3. Mọi thay đổi của `startDate` và `endDate` sẽ trigger tự động gọi lại **API mục 2.1** (`GET /api/v1.0/students?...`) với query date mới nhất để lấy data của tuần vừa chọn.