Đồng bộ tỷ lệ dự thi

Mô tả

API cập nhật dữ liệu tỷ lệ dự thi của nhóm HP lên hệ thống ERP.

Endpoint

POST https://ttdt.api.ttithutech.com/api/v1/thong-tin-du-thi/sync-ty-le

Thuộc tính	Giá trị
Method	POST
Authentication	API Key

Headers

Header	Value
Authorization	ApiKey <API_KEY>
Content-Type	application/json

Lấy API Key

Liên hệ Trung tâm QLCNTT HUTECH để được cấp API Key

---

Request Structure

Root Structure

{
  "data": [ ... ] // Array of SyncTyLeItem (tối thiểu 1, tối đa 30 items)
}

SyncTyLeItem Object

Field	Type	Required	Description
nam_hoc_guid	string (GUID)	✅	GUID của năm học
phan_he_guid	string (GUID)	✅	GUID của phân hệ đào tạo
ma_mon_hoc	string	✅	Mã môn học (VD: CMP371)
ten_lop	string	✅	Tên lớp (VD: 22DTHD6)
nhom_hoc	string	✅	Nhóm học (VD: 01)
nhom_thuc_hanh	string	❌	Nhóm thực hành (VD: 001)
to_hop	string	❌	Tổ hợp nhóm
loai_mon_hoc	string	✅	Loại giảng dạy: LT (Lý thuyết), TH (Thực hành)
ma_giang_vien	string	✅	Mã giảng viên (VD: HDM0040890)
si_so_du_thi	number	✅	Sĩ số dự thi (số nguyên >= 0)
ti_le_du_thi	number	✅	Tỷ lệ dự thi (% từ 0 đến 100)

---

Example Request

POST /api/v1/thong-tin-du-thi/sync-ty-le
Authorization: ApiKey <API_KEY>
Content-Type: application/json

{
  "data": [
    {
      "nam_hoc_guid": "b311f19a-6529-4d84-b3ea-d80b2c08c955",
      "phan_he_guid": "6678F0DA-0022-4BCB-A1D9-62BBC8F440A2",
      "ma_mon_hoc": "MET132",
      "ten_lop": "23DOTA1+23DOTD2",
      "nhom_hoc": "22T",
      "nhom_thuc_hanh": "221T",
      "to_hop": "01",
      "loai_mon_hoc": "LT",
      "ma_giang_vien": "HNT0010275",
      "si_so_du_thi": 81,
      "ti_le_du_thi": 52.721
    }
  ]
}

---

Response Structure

Field	Type	Description
list_error	array	Danh sách các items bị lỗi kèm message chi tiết
success	number	Số lượng items đồng bộ thành công
error	number	Số lượng items bị lỗi

Response thành công (HTTP 200)

Trường hợp tất cả items đều hợp lệ và được đồng bộ thành công:

{
  "list_error": [],
  "success": 1,
  "error": 0
}

Response thành công có lỗi một phần (HTTP 200)

Trường hợp một số items bị lỗi validation, các items còn lại vẫn được xử lý:

{
  "list_error": [
    {
      "nam_hoc_guid": "Test",
      "phan_he_guid": "6678F0DA-0022-4BCB-A1D9-62BBC8F440A2",
      "ma_mon_hoc": "",
      "ten_lop": "23DOTA1+23DOTD2",
      "nhom_hoc": "22T",
      "nhom_thuc_hanh": "221T",
      "to_hop": "01",
      "loai_mon_hoc": "LT",
      "ma_giang_vien": "HNT0010275",
      "si_so_du_thi": 81,
      "ti_le_du_thi": 52.721,
      "message": "nam_hoc_guid không hợp lệ, ma_mon_hoc không được để trống"
    }
  ],
  "success": 4,
  "error": 1
}

Response lỗi validation (HTTP 400)

Trường hợp mảng data vượt quá 30 items:

{
  "statusCode": 400,
  "message": ["data must contain no more than 30 elements"],
  "error": "Bad Request"
}

Trường hợp mảng data ít hơn 1 item:

{
  "statusCode": 400,
  "message": ["data must contain at least 1 elements"],
  "error": "Bad Request"
}

---

Lưu ý khi đồng bộ

Quy tắc quan trọng

• Tối thiểu 1 item, tối đa 30 items mỗi request
• Tỷ lệ dự thi (ti_le_du_thi) phải trong khoảng 0-100
• Sĩ số dự thi (si_so_du_thi) phải là số nguyên không âm
• Sử dụng GUID cho nam_hoc_guid và phan_he_guid
• Nếu item có lỗi sẽ được skip và tiếp tục xử lý các items còn lại
• Kết quả trả về list_error chứa các items bị lỗi kèm message chi tiết

---

Xử lý dữ liệu (Business Logic)

Bảng dữ liệu đích

Dữ liệu sẽ được lưu vào bảng: tl_ThongTinDuThi

Các trường dùng để so khớp (Match Fields)

Hệ thống sử dụng 8 trường sau để xác định bản ghi đã tồn tại hay chưa:

STT	Field	Description
1	nam_hoc_guid	GUID của năm học
2	phan_he_guid	GUID của phân hệ (ma_phan_he_guid)
3	ma_mon_hoc	Mã môn học
4	ma_giang_vien	Mã nhân viên/giảng viên (ma_nhan_vien)
5	ten_lop	Mã lớp học (ma_lop_hoc)
6	nhom_hoc	Nhóm học
7	nhom_thuc_hanh	Nhóm thực hành
8	loai_mon_hoc	Loại môn học

Logic xử lý

Action	Điều kiện
INSERT	Không tìm thấy bản ghi khớp với 8 trường trên
UPDATE	Tìm thấy bản ghi khớp VÀ trường ThuLaoGiangDayID là NULL
SKIP	Tìm thấy bản ghi khớp VÀ ThuLaoGiangDayID đã có giá trị

Lưu ý quan trọng

Chỉ những bản ghi có ThuLaoGiangDayID = NULL mới được cập nhật. Điều này đảm bảo rằng các bản ghi đã được tính thù lao sẽ không bị ghi đè bởi dữ liệu đồng bộ mới.