US-SYS-01: Thuật toán Kiểm tra Khả dụng (Timeslot Matrix)

Tài liệu kỹ thuật mô tả thuật toán kiểm tra sức chứa (Capacity) bằng Ma trận khung giờ giữa Frontend và Backend khi đặt lịch.

Đây là tài liệu kỹ thuật cốt lõi dùng chung cho luồng Đặt lịch (US-OWN-09). Mục đích để đồng bộ logic xử lý Array giữa team Frontend và team Backend.

1. Mục tiêu (Objective)

• Kiểm tra tính khả dụng của một lịch đặt ngay trên Frontend trước khi gửi Request lên API.
• Cải thiện trải nghiệm người dùng (UX) bằng cách phản hồi tức thì mỗi khi đổi số lượng Pet hoặc giờ đặt.
• Giảm tải cho Backend bằng cách chặn bớt các Request rác khi ca làm việc đã kín chỗ (Fully Booked).

2. Quy ước dữ liệu (Data Conventions)

1. Khung giờ (Timeslot): Toàn bộ Timeline trong một ngày được chia thành một mảng (Array). Mỗi index trong mảng đại diện cho một khung giờ cố định (Ví dụ: 30 phút / 1 slot).
2. Sức chứa (Capacity): Giá trị của phần tử tại mỗi index thể hiện sức chứa của cửa hàng tại khung giờ đó.
3. Mảng BE (Supply Matrix): Mảng do Backend sinh ra, thể hiện sức chứa còn trống.
4. Mảng FE (Demand Matrix): Mảng do Frontend tự dựng, thể hiện sức chứa cần tiêu tốn cho booking hiện tại.

---

3. Nhiệm vụ của Backend (Supply Side)

Khi Frontend gọi API lấy lịch khả dụng của một Dịch vụ trong 1 ngày, Backend phải trả về Mảng BE (Supply Matrix).

1. Tổng hợp Sức chứa tối đa (Max Capacity)

   BE quét US-MER-06 (Ma trận Nhân sự & Kỹ năng) để đếm số lượng nhân viên Active, đang rảnh và có khả năng làm dịch vụ này tại từng khung giờ.

2. Trừ đi Booking đã nhận

   BE trừ đi số lượng Slot đã bị chiếm bởi các Booking ở trạng thái Pending và Confirmed.

3. Trả về Payload (Ví dụ)

   {
     "date": "2024-10-15",
     "slot_duration_minutes": 30,
     "available_capacity": [0, 1, 2, 3, 0, 1, ...]
   }
   

   Ý nghĩa mảng trên: Khung giờ 1 đã đầy (0 chỗ), Khung giờ 2 còn 1 chỗ, Khung giờ 3 còn 2 chỗ…

---

4. Nhiệm vụ của Frontend (Validation Algorithm)

Mỗi khi người dùng tương tác chọn Giờ đặt hoặc đổi Số lượng Pet, Frontend không gọi API mà tự chạy Javascript thuật toán sau:

Bước 1: Tính toán Demand (Giá trị A)

• Lấy thông số Hạn mức tải / 1 Pet từ cấu hình dịch vụ (US-MER-04).
• Công thức: A = (Hạn mức tải của dịch vụ) x (Số lượng pet được chọn)
• Ví dụ: Dịch vụ Tắm chó lớn tốn 2 capacity/bé. Khách đặt 2 bé ➔ A = 4.

Bước 2: Xây dựng Ma trận Booking (Mảng C)

• Khởi tạo mảng C toàn số 0 với độ dài bằng độ dài mảng của BE.
• Dựa vào thời gian bắt đầu và thời lượng dịch vụ, xác định dịch vụ sẽ chiếm dụng những Index nào.
• Fill giá trị A vào các Index đó.
• Ví dụ: Booking 2 tiếng (tương đương 4 slot 30 phút), bắt đầu từ slot số 2. Mảng C có dạng: [0, A, A, A, A, 0, 0...]

Bước 3: Đối chiếu Khả dụng

Thực hiện phép trừ ma trận: Mảng kết quả (D) = Mảng BE - Mảng C

Ví dụ minh hoạ:

  [0, 1, 2, 3, 0, 1] (Mảng BE - Còn trống)
- [0, 0, 2, 2, 0, 1] (Mảng C - Mảng Booking)
--------------------
= [0, 1, 0, 1, 0, 0] (Mảng D - Kết quả sau khi đặt)

Quyết định UI dựa trên Mảng D:

• Quét qua Mảng D, nếu TẤT CẢ các phần tử đều >= 0: Trạng thái Khả dụng 👉 Cho phép đặt (Enable nút Submit).
• Nếu có BẤT KỲ 1 phần tử nào < 0: Trạng thái Quá tải 👉 Báo lỗi, Disable nút Đặt lịch, bôi đỏ các khung giờ bị âm.

---

5. Ràng buộc Xử lý Ngoại lệ (Race Condition)

Vì Mảng BE gửi xuống Frontend là dữ liệu tại thời điểm load trang, việc xung đột (tranh chấp lượt đặt) khi 2 người cùng đặt 1 slot là hoàn toàn có thể xảy ra.

Q quy tắc bắt buộc đối với Backend:

1. Khi FE thực hiện Request gọi API POST /bookings (Tạo Booking thực tế).
2. BE TUYỆT ĐỐI KHÔNG TIN TƯỞNG kết quả check của FE.
3. BE phải chạy lại hàm đối chiếu ma trận này một lần nữa bằng dữ liệu Database real-time.
4. Nếu kết quả ra số âm (Bị khách khác lấy mất slot trong lúc đang chọn), BE trả về HTTP 400 kèm mã lỗi SLOT_UNAVAILABLE.
5. FE nhận lỗi, popup thông báo khách hàng và load lại API lấy available_capacity mới nhất.