APMATHS — Kiến trúc hệ thống và dữ liệu

Cập nhật: 2026-10-11. Phân biệt phần đang có và phần dự kiến.

1. Các repository / website

apmaths.io.vn được dự định là tên miền chính chạy qua Cloudflare Pages. Việc chuyển hướng từ apmaths.github.io chưa được thực hiện theo tài liệu này.

2. Supabase

Hai project APMATHS hoạt động độc lập cả database lẫn Auth. Không tạo tài khoản dùng chung hoặc tự động đồng bộ dữ liệu học tập. Người học mua lớp bạn trực tiếp dạy ở base 1; mua/học lớp của giáo viên ngoài ở base 2. Bộ thi thử công khai thu hút lưu lượng truy cập là nội dung của base 1 (đề tĩnh có thể chạy không cần Supabase). Chi tiết xem Đợt 3 — hai Supabase.

Không kết nối chéo dữ liệu sinh viên PTITHCM sang APMATHS thương mại. Khi cần tái sử dụng công cụ, ưu tiên tái sử dụng mã nguồn/thiết kế theo quyền hợp lệ, không sao chép dữ liệu cá nhân hay đề bảo mật.

Trạng thái cơ sở dữ liệu APMATHS hiện tại

Đã có question_banks, subjects, chapters, topics, clos, questions, question_options, essay_questions, practice_configs, practice_packages, practice_draws, exam_attempts, profiles và nhiều bảng nghiệp vụ AI-CLO. Các tên dưới đây chỉ là đề xuất, chưa tạo.

Dữ liệu grade_*, kpi_* vẫn tồn tại trong Supabase APMATHS dù mã frontend tương ứng đã gỡ khỏi repository Private. Không xóa bảng/Edge Function/bucket trước khi sao lưu, xác minh phụ thuộc và có yêu cầu rõ.

3. Phân lớp dữ liệu dự kiến

• GitHub + Jekyll: nội dung bài học, bản dịch, danh mục chương trình phổ thông (khung), metadata SEO và liên kết toán học; trang công khai tạo tĩnh.
• Supabase 1: AI-CLO hiện tại và thi thử công khai; đã bổ sung 4 bảng riêng cho khóa học/gói học/ghi danh/đơn hàng và UI /courses/apmaths/, nhưng chưa có cổng thanh toán hay tích hợp cấp quyền cho AI-CLO runtime.
• Supabase 2: đã triển khai hệ thống tài khoản/lớp/giáo viên, câu hỏi và đề thi có server grading, gói miễn phí và bảng quyền theo workspace; /platform/ và /platform/exams/ nằm trên PR #4. Admin đầu tiên đã cấp quyền, Auth URL và E2E browser chưa nghiệm thu. Thanh toán và gói Pro chưa mở.
• Các thực thể có thể bổ sung sau: base 1 — khóa/lớp do bạn dạy, enrollment, entitlement và payment order; base 2 — profiles, teacher_applications, workspaces, workspace_members, classes, class_enrollments, sau đó mới ngân hàng/đề/kết quả/entitlement. Thiết kế trước khi tạo DDL.
• Tái sử dụng bảng questions, question_banks, practice_* hiện có sau khi rà quan hệ/permission; tránh tạo schema trùng khi chưa cần.

Quy tắc định danh

• Một bài có lesson_id ổn định, slug/URL và bản dịch VI/EN liên kết qua ID.
• Một bài có thể nằm trong nhiều chương trình/lộ trình, không nhân bản nội dung.
• Câu hỏi có quyền sở hữu/nguồn, trạng thái duyệt, phạm vi công khai/riêng tư, độ khó, chủ đề.
• Không phát đáp án bảo mật qua API công khai trước thời điểm được phép; phân quyền tại backend/RLS, không chỉ ẩn nút.

4. Tài nguyên ảnh và tệp — hoãn ngoài phạm vi đợt 3

• Chưa tích hợp Cloudinary, R2 hoặc dịch vụ media khác; chưa di chuyển ảnh/âm thanh, chưa mở uploader hay tạo bảng media mới.
• Học liệu công khai hiện có tiếp tục dùng tài nguyên đang hoạt động; công thức mới ưu tiên LaTeX/MathJax để hạn chế ảnh.
• Chỉ quay lại thiết kế kho tệp/đường dẫn media khi hai Supabase, Auth và RLS đã ổn định.
• Không đụng bucket hoặc nội dung đang phục vụ công cụ cũ.

5. Ranh giới bảo mật và thu phí

• Học liệu công khai không phụ thuộc vào phiên đăng nhập.
• AI, chấm điểm trả phí, phân quyền gói: dùng Edge Functions hoặc backend kiểm tra token + entitlement + rate limits.
• Giao dịch có đơn hàng, trạng thái và webhook/xác nhận backend; frontend không có quyền tự gán paid.
• Không chuyển dữ liệu cá nhân giữa hai Supabase APMATHS độc lập mặc định; kiểm soát đúng chủ sở hữu lớp/giáo viên trước khi trả kết quả.
• Duy trì audit/migration có thể quay lui; ưu tiên triển khai từng đợt.

6. Công cụ trong GitHub Private

Đã gỡ bản sao Công bố điểm và KPI CB2 khỏi APMatHS/apmaths.io.vn (thư mục frontend, Edge Function và SQL liên quan). Bản AI-CLO PTITHCM tiếp tục tồn tại ở repository độc lập. Các công cụ toán khác của APMATHS vẫn giữ nguyên.