APMATHS — Lộ trình và quy tắc thực hiện

Cập nhật: 2026-10-13. PR #4 đã merge vào main, nhưng Cloudflare Production và trình duyệt thật chưa nghiệm thu đầy đủ. Đọc chốt phiên và checklist lần sau trước khi tiếp tục. Chỉ thực hiện thay đổi code/hệ thống theo đợt được chấp thuận.

A. Hiện trạng đã xác nhận

• Tạo repository Private APMatHS/apmaths.io.vn, sao chép mã nguồn từ APMatHS/apmaths.github.io.
• Đối chiếu 657/657 tệp nguồn trùng SHA tại thời điểm sao chép; không chuyển toàn bộ lịch sử commit.
• Gỡ 38 tệp bản sao Công bố điểm/KPI CB2 khỏi repository Private mới; gỡ hai thẻ công cụ khỏi /tools/ trên repository Private.
• AI-CLO PTITHCM có bản Công bố điểm/KPI CB2 độc lập tại APMatHS/ai-clo-ptithcm.github.io và Supabase rraooqedkpyhokattwdz.
• Supabase 1 yhfburffwzvcayjadskr phục vụ AI-CLO cá nhân; Supabase 2 mhgsvxsjrzaeafvifydu phục vụ giáo viên ngoài. Hai project đã có migration phục vụ đợt 3–4, không đồng bộ Auth.
• Thống nhất APMATHS học toán đại học trước, phổ thông dựng khung, có chủ đề xuyên cấp, luyện tập freemium.
• Thống nhất nguyên tắc giữ miền cũ /ai-clo/, /tools/ khi chuyển website chính.

Đợt 0 — Đổi giao diện (triển khai trên nhánh riêng)

• Hệ thống màu, khoảng cách và chế độ sáng/tối có lưu lựa chọn.
• Trang chủ, NAV, footer mới và layout responsive.
• Đồng bộ giao diện bài đọc và danh mục Tools; giữ nguyên công cụ con.
• Build Jekyll và xem preview Cloudflare Pages; giao diện đã được người dùng duyệt ở mức trực quan.
• Hoàn tất kiểm thử chức năng, độ rộng màn hình và truy cập bàn phím trên bản production/preview.
• PR #1 đã merge vào main (11/10/2026).

Xem docs/00-THIET-KE-GIAO-DIEN.md.

B. Lộ trình và trạng thái thực tế

Đợt 1 — Nền tảng website

• Kết nối Cloudflare Pages từ repo Private và build Jekyll thành công; giữ nguyên cách triển khai.
• Tạo bản đề xuất các cổng Học Toán /courses/, Luyện tập /practice/, AI-CLO /ai-clo/ trên nhánh riêng, chờ kiểm thử/duyệt.
• Quy hoạch NAV: Học Toán (phổ thông/đại học/chủ đề), Luyện tập, Công cụ, Khám phá, Blog, AI-CLO. Giữ Tools chưa chỉnh chức năng.
• Thiết kế metadata và đường dẫn VI/EN; không phá URL cũ.
• Thiết kế bộ khung Toán 1–12, tránh phụ thuộc chặt vào một bộ SGK.

Đợt 2 — Học phần đại học mẫu

• Chuẩn hóa Đại số tuyến tính: chương, bài, tiên quyết, ví dụ, bài tập, công cụ liên quan.
• Rà soát nội dung hiện có, tránh trùng bài/đường dẫn.
• Xây dựng chủ đề xuyên cấp và mối liên kết tri thức.

Đợt 3B–3F — Schema đã triển khai; code đã merge PR #4

• 3B / Base 2: tạo tài khoản [email protected], xác minh email, cấp đúng quyền platform_admin; UI đăng ký, duyệt giáo viên trong /platform/.
• 3C / Base 2: tạo/sửa/lưu trữ lớp, mã mời, danh sách học sinh, rời lớp và xóa khỏi lớp; SQL RLS test rollback PASS.
• 3D / Base 2: ngân hàng câu hỏi riêng, đề lớp, publish/attempt/server-side grading; UI /platform/exams/, kiểm tra phân quyền teacher A/B và bảo mật đáp án PASS trong SQL.
• 3E / Base 1 + Jekyll tĩnh: chuyển bộ thi thử Guest 24 câu (Đại số tuyến tính) từ PR #3 vào /practice/try/ tại nhánh hiện hành. Đáp án ví dụ công khai, điểm demo tính trên trình duyệt không lưu.
• 3F / Base 1: bổ sung 4 bảng thương mại và migration v2 liên kết trang khóa học tới subjects hiện có, ràng buộc không công bố khóa chưa gắn môn/cấm đổi liên kết sau công bố. Đã kiểm tra 2 môn và 1 membership giữ nguyên. Sinh viên thấy Khóa học của tôi trên màn hình môn AI-CLO; Admin/GV vẫn dùng Môn học cũ. Trang /courses/apmaths/ chỉ giới thiệu và quản lý nháp.
• Theo dõi migration thực tế trong hai thư mục supabase/migrations/ (base 2), supabase-personal/migrations/ (base 1). Không UPDATE/DELETE môn hoặc học viên AI-CLO đang dùng.
• Cấu hình Auth Site URL/Email Redirect/CAPTCHA, thử E2E browser thật và kiểm thử tải trước khi public.
• Hoàn thiện mô-đun CLO, import đề, giám sát thi nâng cao; không khẳng định đã hoàn thành toàn bộ AI-CLO cho giáo viên ngoài.

Đợt 4 — Nền tảng gói dịch vụ, chưa thu phí

• Base 2: tạo platform_service_plans, platform_workspace_subscriptions, platform_usage_events; cấp gói free tự động cho workspace giáo viên được duyệt.
• Base 1: bảng gói học, đơn hàng và quyền ghi danh tồn tại, nhưng chưa nối tới gateway hay runtime khóa quyền AI-CLO.
• Chốt nhà cung cấp thanh toán, báo giá, webhook xác thực, đối soát và cấp quyền sau thanh toán.
• Giới hạn theo gói/AI, bảo vệ trẻ vị thành niên, chính sách quyền riêng tư và hậu kiểm chi phí.
• Cloudinary/media tạm hoãn, không có uploader hay storage migration.

Đợt 5 — Website, SEO và chuyển tên miền

• Chỉ trong repo Private mới: stage site.url=https://apmaths.io.vn, điều chỉnh canonical/meta robots cho trang quản lý, xây sitemap Jekyll và robots.txt đúng site.url.
• Thêm liên kết giữa /courses/, /courses/apmaths/, /ai-clo/, /platform/ và /practice/try/.
• Chủ website xác nhận đã kết nối tên miền apmaths.io.vn với Cloudflare Pages.
• PR #4 đã merge vào main (squash commit e1f337b7).
• Chưa nghiệm thu: deployment Cloudflare Production, SSL, canonical, sitemap, CSS/JS trên các đường dẫn thực tế và thiết bị di động.
• Chỉ sau nghiệm thu mới tính phương án redirect URL nội dung cũ; giữ nguyên mọi trang con apmaths.github.io/ai-clo/ và apmaths.github.io/tools/.
• PR #4 không sửa repository GitHub Pages cũ và không thiết lập redirect. Chủ website thực hiện kết nối tên miền trên Cloudflare.

Xem Báo cáo tiến độ Đợt 3B–5 và chốt phiên sau merge PR #4.

C. Quy tắc sửa đổi

1. Trước khi sửa: kiểm tra repository/branch/commit và xác định chức năng đang hoạt động.
2. Chia theo đợt nhỏ; làm xong phải kiểm thử và cập nhật Markdown tiến độ.
3. Không “vá” bằng CSS/JS phiên bản chồng chéo nếu có thể sửa đúng file chức năng.
4. Mỗi lần thay đổi Supabase URL, Auth/RLS, secrets, domain và redirect cần kiểm tra phạm vi và xác nhận rõ. Hai migration scope đã được chấp thuận triển khai trong cuộc trao đổi 12/10/2026; không coi đây là quyền xóa dữ liệu hoặc tự mở dịch vụ thanh toán.
5. Không xóa dữ liệu/bảng/bucket ở Supabase khi chưa backup + kiểm tra phụ thuộc + xác nhận.
6. Không tự động chuyển chức năng nội bộ PTITHCM sang sản phẩm trả phí APMATHS.
7. Khi thay layout, bảo vệ các đường dẫn legacy và nội dung đang được liên kết từ bên ngoài.

D. Bản đề xuất cấu trúc website + AI-CLO (11/10/2026)

• Nhánh: feature/learning-practice-ai-clo-hubs (không tự merge).
• Đã có 3 cổng rõ mục đích: /courses/ (nội dung), /practice/ (lối vào luyện tập), /ai-clo/ (giới thiệu hệ thống).
• Các URL thực thi không đổi: /ai-clo/practice/, /ai-clo/app.html, /tools/ cùng trang con.
• Phổ thông mới là khung lớp 1–12; không dựng trang trống hoặc liên kết không tồn tại; các trang đại học theo năm giữ nguyên.
• Chưa triển khai bản dịch nội dung, thanh toán, tài khoản mới, lược đồ Supabase hoặc đổi canonical/DNS.
• Cần xem Preview và nghiệm thu trước khi merge. Xem docs/05-CAU-TRUC-WEB-AI-CLO.md.