🛠️ Tech Stack Chi tiết — ChienLe Labs¶

Tài liệu này cung cấp cái nhìn sâu sắc về mọi công nghệ, thư viện và hạ tầng đang vận hành hệ thống ChienLe Labs.

🎨 Frontend Stack¶

Hệ thống Frontend được xây dựng trên nền tảng Next.js 15+ với kiến trúc App Router, tập trung vào hiệu năng và trải nghiệm người dùng cao cấp.

⚡ Backend Stack¶

Backend sử dụng FastAPI — một framework Python hiệu năng cao, dựa trên Starlette và Pydantic với khả năng kiểm lỗi kiểu dữ liệu nghiêm ngặt.

🤖 AI Assistant & HTML Processing¶

Đây là phần quan trọng nhất trong việc tạo ra nội dung học tập thông minh. Hệ thống không chỉ gọi API mà còn thực hiện quy trình "vẽ" lại mã HTML (HTML Draw).

Cơ chế Fallback AI¶

Hệ thống sử dụng chiến lược Tháp phòng thủ: 1. Google Gemini 1.5 Flash: Lựa chọn ưu tiên nhờ tốc độ cực nhanh và hỗ trợ tiếng Việt tốt. 2. OpenAI GPT-4o-mini: Tự động kích hoạt khi Gemini gặp lỗi (quota, timeout) để đảm bảo trải nghiệm không bị gián đoạn.

Pipeline Xử lý HTML (AI Sanitization)¶

Được triển khai trong backend/services/ai_service.py, quy trình này đảm bảo mã HTML từ AI luôn an toàn và đẹp:

1. Giai đoạn 1: Bóc tách (Stripping)
   • Loại bỏ các khối code block thừa (```html) mà AI hay tự bọc.
   • Xóa các câu dắt dẫn giải từ LLM (ví dụ: "Dưới đây là nội dung...").
2. Giai đoạn 2: Chuẩn hóa Cấu trúc (BeautifulSoup4)
   • Sử dụng BeautifulSoup để duyệt cây DOM đệ quy.
   • Tự động xóa các thẻ rỗng (<p></p>), các node thừa và chuẩn hóa khoảng trắng.
3. Giai đoạn 3: Thực thi Whitelist & Style
   • Tag Whitelist: Chỉ cho phép các thẻ an toàn (<b>, <ul>, <table>, details...).
   • Class Whitelist: Chỉ giữ lại các class Tailwind hợp lệ (text-center, font-bold...).
   • Clear Attributes: Xóa sạch thuộc tính style, id, onclick để ngăn ngừa XSS và xung đột giao diện.

📦 Quy trình Upload Media (Video/Image)¶

Hệ thống sử dụng cơ chế Direct Upload to S3 để giảm tải cho server backend, kết hợp với bước Finalize để đảm bảo tính toàn vẹn của dữ liệu.

Sơ đồ Tuần tự (Sequence Diagram)¶

sequenceDiagram
    participant FE as Frontend (User/Admin)
    participant BE as Backend (FastAPI)
    participant R2 as Cloudflare R2 (Storage)
    participant DB as Database (PostgreSQL)

    Note over FE, BE: 1. Yêu cầu quyền Upload
    FE->>BE: POST /admin/media/upload-url (filename, type)
    BE-->>FE: 200 OK (Presigned PUT URL, file_key)

    Note over FE, R2: 2. Upload trực tiếp (Direct Upload)
    FE->>R2: HTTP PUT (File Binary) via Presigned URL
    R2-->>FE: 200 OK (Upload Success)

    Note over FE, BE: 3. Hoàn tất (Finalize)
    FE->>BE: POST /admin/media/finalize-upload (file_key)

    Note over BE, R2: 4. Xác thực (Verification)
    BE->>R2: S3 HEAD Request (Verify Exist & Size)
    R2-->>BE: 200 OK (Metadata: size_bytes)

    Note over BE, DB: 5. Lưu trữ Metadata
    BE->>DB: Upsert MediaFile (key, name, size)
    DB-->>BE: Success

    BE-->>FE: 200 OK (Permanent CDN URL)

Tại sao cần bước Finalize?¶

1. Xác thực tồn tại: Backend chỉ lưu thông tin vào DB khi chắc chắn file đã nằm trên R2 thành công.
2. Lấy Metadata chính xác: Thay vì tin vào số liệu từ Frontend, Backend trực tiếp hỏi R2 để lấy size_bytes thực tế.
3. Idempotency: Bước Finalize có thể chạy lại nhiều lần cho cùng một file_key mà không tạo ra bản ghi thừa.

🌟 Trải nghiệm Học thử (Trial Lesson Experience)¶

Tính năng "Học thử" (Sneak Peek) được thiết kế để tăng độ tin tưởng của học viên bằng cách cho phép truy cập một phần nội dung chất lượng cao trước khi mua khóa học.

Cơ chế kỹ thuật¶

1. Flag bài học: Mỗi Lesson trong Database có một thuộc tính is_preview (Boolean).
2. Quyền truy cập: Endpoint Public lấy khóa học sẽ trả về đầy đủ nội dung (HTML/Video) cho các bài giảng có is_preview=True, bất kể học viên đã mua hay chưa.
3. Giao diện:
   • Trang Lộ trình học tập (Roadmap) sẽ hiển thị các bài giảng này với badge "Học thử" hoặc biểu tượng mở khóa.
   • Học viên có thể click vào và xem nội dung video/biểu đồ ngay lập tức.

Lợi ích thiết thực¶

• Học viên: Đánh giá được phong cách giảng dạy và chất lượng hình ảnh/âm thanh mà không tốn chi phí.
• Giảng viên: Marketing gián tiếp khóa học thông qua những bài giảng tâm đắc nhất.

📦 Hạ tầng & Dịch vụ Cloud¶

|---|---|---| | Frontend Hosting | Cloudflare Pages | Tốc độ CDN cực nhanh, tích hợp CI/CD | | Backend Hosting | Northflank | Docker container scaling, quản lý biến môi trường | | Database | Supabase (PostgreSQL) | Managed DB, sao lưu tự động | | Object Storage | Cloudflare R2 | Lưu trữ video/ảnh bài giảng (S3-compatible) | | CDN | Cloudflare R2 Public | Tăng tốc tải tài nguyên tĩnh |