Backend - Next.js API Routes

my-app/
│
├── app/
│   ├── api/                          ← 🔒 THƯ MỤC BACKEND API
│   │   │
│   │   ├── send-email/
│   │   │   └── route.ts              → URL: /api/send-email
│   │   │
│   │   ├── payment/
│   │   │   ├── create/
│   │   │   │   └── route.ts          → URL: /api/payment/create
│   │   │   └── verify/
│   │   │       └── route.ts          → URL: /api/payment/verify
│   │   │
│   │   ├── reports/
│   │   │   ├── export-pdf/
│   │   │   │   └── route.ts          → URL: /api/reports/export-pdf
│   │   │   └── export-excel/
│   │   │       └── route.ts          → URL: /api/reports/export-excel
│   │   │
│   │   ├── ai/
│   │   │   └── generate/
│   │   │       └── route.ts          → URL: /api/ai/generate
│   │   │
│   │   └── webhooks/
│   │       ├── stripe/
│   │       │   └── route.ts          → URL: /api/webhooks/stripe
│   │       └── zalo/
│   │           └── route.ts          → URL: /api/webhooks/zalo
│   │
│   ├── (pages)/                      ← 🖥️ Các trang frontend
│   │   ├── dashboard/
│   │   └── courses/
│   │
│   └── layout.tsx
│
├── lib/                              ← 🔧 Thư viện dùng chung (phía server)
│   ├── email.ts                      ← Hàm gửi email
│   ├── pdf.ts                        ← Hàm tạo PDF
│   └── auth.ts                       ← Hàm kiểm tra xác thực
│
└── .env.local                        ← 🔑 Biến môi trường (API keys bí mật)

.env.local                            ← File này KHÔNG upload lên GitHub

SENDGRID_API_KEY=SG.xxxxxxxxxxxx      ← Key gửi email
VNPAY_SECRET_KEY=abc123xyz            ← Key thanh toán
OPENAI_API_KEY=sk-xxxxxxxxxxxx        ← Key AI
DATABASE_URL=postgresql://user:pass@... ← Kết nối database
JWT_SECRET=my-super-secret-key        ← Key mã hóa token

"Tạo file .env.local với các biến:
- SENDGRID_API_KEY: key gửi email
- NEXT_PUBLIC_APP_URL: URL của app (https://myapp.com)

Đảm bảo .gitignore đã có .env.local"

"Tích hợp thanh toán VNPay:

1. API tại /api/payment/create:
   Input: { studentId, courseId, amount }
   - Tạo URL thanh toán VNPay (dùng VNPAY_SECRET_KEY từ .env)
   - Lưu đơn hàng vào Firestore với status 'pending'
   - Trả về { paymentUrl } để redirect học viên

2. Webhook tại /api/webhooks/vnpay:
   - Nhận kết quả từ VNPay sau khi học viên thanh toán
   - Xác minh chữ ký bảo mật (tránh giả mạo)
   - Nếu thành công: cập nhật Firestore status 'paid', gửi email xác nhận
   - Nếu thất bại: cập nhật status 'failed', thông báo học viên"

"Tạo API Route tại /api/reports/export-students

Input: { courseId, format: 'excel' | 'pdf' }

Quy trình:
1. Kiểm tra người gọi có quyền admin không (từ Firebase Auth token)
2. Đọc danh sách học viên của courseId từ Firestore
3. Tạo file Excel với các cột:
   STT | Họ tên | Email | Số điện thoại | Ngày đăng ký | Trạng thái | Học phí
4. Trả về file Excel để trình duyệt tải về

Dùng thư viện 'xlsx' để tạo Excel."

"Tạo Webhook tại /api/webhooks/zoom

Zoom gửi POST request khi buổi học kết thúc với data:
{
  event: 'meeting.ended',
  payload: {
    meetingId: '123456789',
    duration: 90,        ← thời lượng buổi học (phút)
    participants: [...]  ← danh sách người tham gia
  }
}

Xử lý:
1. Xác minh request đến từ Zoom (dùng ZOOM_WEBHOOK_SECRET)
2. Tìm buổi học tương ứng trong Firestore qua meetingId
3. Cập nhật attendance: ai đã tham gia, thời gian tham gia
4. Gửi email 'Cảm ơn bạn đã tham gia' cho từng học viên có mặt
5. Gửi thông báo cho giáo viên: danh sách vắng mặt"

"API Route /api/reports/export-students phải:
1. Kiểm tra Firebase Auth token trong header Authorization
2. Xác minh token hợp lệ (dùng Firebase Admin SDK)
3. Lấy role của user từ Firestore
4. Chỉ cho phép tiếp tục nếu role là 'admin' hoặc 'teacher'
5. Nếu không có token hoặc không đủ quyền → trả về lỗi 403"

"API /api/ai/chat:
- Tối đa 20 lần gọi / học viên / ngày
- Nếu vượt → trả về lỗi: 'Bạn đã dùng hết lượt hỏi hôm nay. Quay lại vào ngày mai.'"

"Webhook /api/webhooks/vnpay:
- Xác minh chữ ký HMAC trong request header
- Dùng VNPAY_SECRET_KEY để kiểm tra
- Nếu chữ ký sai → bỏ qua, log warning"

app/api/
│
├── auth/
│   └── sync-user/route.ts            → Đồng bộ Firebase user vào Firestore
│
├── email/
│   ├── enrollment-confirm/route.ts   → Xác nhận đăng ký khóa học
│   ├── payment-reminder/route.ts     → Nhắc đóng học phí
│   ├── certificate/route.ts          → Cấp chứng chỉ
│   └── lesson-reminder/route.ts      → Nhắc buổi học sắp tới
│
├── payment/
│   ├── create/route.ts               → Tạo đơn thanh toán
│   └── verify/route.ts               → Xác minh kết quả thanh toán
│
├── reports/
│   ├── export-students/route.ts      → Xuất danh sách học viên (Excel)
│   ├── export-grades/route.ts        → Xuất bảng điểm (Excel)
│   └── export-certificate/route.ts   → Xuất chứng chỉ (PDF)
│
├── ai/
│   ├── grade-essay/route.ts          → Chấm bài tự luận
│   ├── generate-quiz/route.ts        → Tạo câu hỏi ôn tập
│   └── chat/route.ts                 → Chatbot hỗ trợ học viên
│
└── webhooks/
    ├── vnpay/route.ts                → Nhận kết quả thanh toán VNPay
    ├── zoom/route.ts                 → Nhận sự kiện kết thúc buổi học
    └── zalo/route.ts                 → Nhận tin nhắn từ Zalo OA

"Tạo API Route tại /api/email/enrollment-confirm

Phương thức: POST
Xác thực: Yêu cầu Firebase Auth token (Bearer token trong header)

Input body:
- studentId: string (ID học viên trong Firestore)
- courseId: string (ID khóa học)

Quy trình:
1. Xác minh Firebase token → lấy UID người gọi
2. Kiểm tra UID có phải admin hoặc giáo viên không
3. Đọc thông tin học viên từ Firestore (users/studentId)
4. Đọc thông tin khóa học từ Firestore (courses/courseId)
5. Kiểm tra học viên đã đăng ký khóa này chưa (tránh gửi 2 lần)
6. Gửi email xác nhận qua Resend với nội dung:
   - Chào [tên học viên]
   - Tên khóa học, thời gian bắt đầu
   - Link tham gia lớp học (Zoom/Google Meet)
   - Hướng dẫn chuẩn bị trước buổi học
7. Cập nhật Firestore: enrollments/[studentId_courseId].confirmationEmailSent = true

Trả về:
- Thành công: { success: true }
- Lỗi xác thực: 401 { error: 'Unauthorized' }
- Học viên không tồn tại: 404 { error: 'Student not found' }
- Đã gửi rồi: 400 { error: 'Email already sent' }"