| Method | Path | Mục đích / request / response | Trạng thái |
|---|
| GET/POST | /v3/teacher/exams; GET/PUT/DELETE /v3/teacher/exams/{id}; GET .../{exam_id}/students, /score-report, /analytics/summary | kỳ thi FLYER, thí sinh và điểm theo kỹ năng; backend đọc khi gắn nguồn FLYER | existing |
| POST / GET | /v3/teacher/exams/{exam_id}/sessions, /notify; /v3/learner/exams; /v3/parent/learner/{id}/report; /v3/crm/placement-tests, /{id}/submit-result | không đổi | existing |
| GET/POST | /v3/crm/assessments | lọc school_id, status, class_id, level_id, type, teacher_id, from, to → ListResponse; POST {school_id, name, type, exam_date, class_id | level_id + class_ids[], template_id | components[], total_scale, comment_required, reviewer_staff_id?} → assessment (children[] khi theo trình độ) | new |
| GET/PUT/DELETE | /v3/crm/assessments/{id} | chi tiết kèm counts; PUT chỉ ở draft/returned; DELETE chỉ ở draft; 409 STALE_VERSION | new |
| GET / PUT | /v3/crm/assessments/{id}/grid; PUT /{id}/scores | grid → {assessment, components, rows: [{student, roster_type, score, comment_present, attachment_count, flags}], stats}; scores {rows: [{student_id, component_scores?, attendance_status?, exempt_components?}], mode: grid|paste, overwrite, version}; kiểm tra toàn bộ trước khi ghi; 422 kèm danh sách ô lỗi; Idempotency-Key | new |
| GET/PUT | /v3/crm/assessments/{id}/students/{student_id}; POST/DELETE .../attachments[/{attachment_id}]; GET .../history | điểm, nhận xét, tệp của một học viên; PUT {component_scores, attendance_status, comment, reason? (bắt buộc khi published), notify_adjustment?}; lịch sử điểm | new |
| POST | /v3/crm/assessments/{id}/roster; /link-flyer-exam; /submit; /return; /publish; /archive | roster {add[], remove[], reason} chỉ trước công bố; link-flyer-exam {exam_id, mapping, overwrite} → {filled, unmatched_students[]}; /return {note}; /publish {notify, show_grade} phát sự kiện assessment.published; INVALID_TRANSITION, VALIDATION_INCOMPLETE | new |
| GET / POST | /v3/crm/assessments/{id}/export?format=xlsx; POST /{id}/report-cards | xlsx cả lớp; report-cards {student_ids[] | all} → {job_id} | new |
| GET | /v3/crm/students/{id}/results | các kỳ đã công bố (nhân sự thấy cả nháp với cờ), điểm đầu vào, chứng nhận, chuỗi điểm theo cấu phần | new |
| GET/POST/PUT/DELETE | /v3/crm/assessment-templates[/{id}]; /v3/crm/comment-phrases[/{id}]; GET/POST /v3/crm/grading-rules; /v3/crm/certificate-templates | danh mục cấp trung tâm; xoá mẫu bị chặn khi đang dùng; quy tắc xếp loại theo phiên bản (P2) | new |
| GET/POST | /v3/crm/certificates; POST /{id}/revoke; GET /{id}/file; GET /v3/crm/certificates/verify/{qr_token} | {assessment_id, template_id, student_ids[]} → chứng nhận kèm số hiệu; thu hồi {reason}; verify công khai không cần đăng nhập (P2) | new |
| GET | /v3/parent/learner/{id}/results; /results/{assessment_id} | kết quả đã công bố cho cổng phụ huynh; không có dữ liệu của học viên khác | new |
| GET/PUT | /v3/teacher/school-config | khối assessment_policy: comment_required_default, separate_reviewer, notify_absent, show_grade_default, attachment_limits | extend |
