Cổng đại lý phân phối mã kích hoạt FLYER

1. Sản phẩm giải quyết việc gì

FLYER bán gói Premium B2C chủ yếu qua website. Kênh chưa khai thác: người bán lẻ cá nhân — giáo viên, chị em văn phòng, mẹ bỉm — những người có sẵn cộng đồng phụ huynh và muốn thu nhập thêm. Portal này cho họ một cửa hàng hoàn chỉnh: lấy mã kích hoạt FLYER ở giá chiết khấu, bán lại giá lẻ, phần chênh lệch là thu nhập của họ.

Toàn bộ vòng đời chạy tự động trên web: đăng ký đại lý, duyệt hồ sơ, đặt mã, thanh toán VietQR có đối soát tự động, kho mã, hoa hồng, đối soát cuối tuần, đào tạo và sale kit. Phía công ty có trang quản trị riêng.

• Production: agent.flyer.vn (kèm flyer-agent.pages.dev)
• Source: repo Genki91/about.flyer.vn, nhánh claude/flyer-agent-distribution-8grf6x, thư mục flyer-agent/
• Tài khoản demo: demo / flyer123 (đại lý Bạc) · marketing / flyer123 (sửa nội dung) · admin / ZqaZw4UdNNxuV5 (trang Quản trị — dùng nội bộ, sẽ đổi khi chạy thật)

2. Vai trò người dùng

Đại lý mới tự đăng ký sẽ ở trạng thái chờ duyệt: đăng nhập và xem được mọi thứ nhưng chưa đặt mã. Admin nhận email báo mỗi khi có hồ sơ mới.

3. Hai luồng bán hàng chính

3a. Mua sỉ trả trước

1. Đại lý chọn gói theo giá chiết khấu theo hạng (giá lẻ đồng bộ tự động từ bảng giá flyer.vn, cache 10 phút).
2. Thanh toán bằng VietQR: số tiền và nội dung chuyển khoản (dạng FLYERAG <id> <token>) điền sẵn.
3. Webhook ngân hàng (Casso/SePay) báo tiền về, hệ thống khớp nội dung chuyển khoản, xác nhận đơn và phát mã vào kho trong dưới 1 phút.
4. Đại lý gửi mã cho khách, tự ghi nhận đã bán/đã kích hoạt kèm tên khách. Lãi = giá lẻ trừ giá sỉ, đại lý giữ ngay.

3b. Bán hộ (thiết kế cho giáo viên)

1. Đại lý nhập tên phụ huynh, hệ thống tạo QR giá lẻ trỏ về tài khoản công ty. Đại lý gửi QR cho phụ huynh quét.
2. Tiền về công ty, mã phát ra gắn sẵn tên khách, hoa hồng (đúng bằng mức chiết khấu hạng) vào sổ chờ.
3. Mỗi cuối tuần công ty đối soát một lần: admin xem danh sách cần chuyển, quét QR chuyển khoản đã điền đúng số tiền cho từng đại lý, bấm chốt đợt. Đại lý nhận email xác nhận.

Điểm khác biệt giữa hai luồng: mua sỉ cần vốn, lãi về ngay; bán hộ không cần vốn, hoa hồng về cuối tuần. Mã giảm giá (cấp riêng từng đại lý hoặc dùng chung) chỉ áp cho mua sỉ vì bán hộ phải thu đủ giá lẻ.

4. Bậc hạng và lộ trình thu nhập

Trang Chương trình đại lý có bậc thang thu nhập tương tác: chọn gói hay bán, hệ thống tính cần bán bao nhiêu mã mỗi tháng cho từng mốc 5, 10, 15, 20, 30, 50 triệu, đã tính cả việc lên hạng theo sản lượng. Ví dụ gói 12 tháng: 5 triệu cần 13 mã/tháng (hạng Bạc), 50 triệu cần 90 mã/tháng (Kim cương, lãi 560.000đ/mã).

Hiện thăng hạng đặt tay qua admin; tự động thăng hạng theo sản lượng tháng nằm trong phần việc còn lại.

5. Tính năng theo từng trang

Toàn bộ giao diện responsive: trên điện thoại menu thành thanh trên + drawer, bảng dài tự xếp thành thẻ dọc.

6. Ảnh màn hình thực tế

Chụp từ bản đang chạy (dữ liệu demo). Bấm vào ảnh để xem cỡ lớn.

7. Kiến trúc kỹ thuật

• Stack: Next.js 14 (App Router) chạy trên Cloudflare Pages qua next-on-pages, toàn bộ route ở edge runtime. Database là Cloudflare D1 (SQLite serverless), không có server phải vận hành.
• Auth: mật khẩu băm PBKDF2 (WebCrypto), phiên JWT trong httpOnly cookie 7 ngày, middleware chặn toàn bộ trang trừ login/register/webhook/prd.
• Giá: parse trực tiếp HTML bảng giá flyer.vn, ghi cache vào D1, tự bù giá mặc định nếu parse thiếu gói.
• Email: Resend API (báo admin khi có đăng ký, báo đại lý khi chuyển hoa hồng). Chưa cấu hình key thì hệ thống bỏ qua êm, không ảnh hưởng luồng chính.
• Bảng dữ liệu: agents, orders, codes, commissions, discount_codes, price_cache, guides, resources. Schema và migration nằm trong repo (schema.sql, migrations/).
• Deploy: npm run deploy (build next-on-pages rồi wrangler pages deploy). Dev giống production: npm run preview.
• Script vận hành: tạo đại lý, tạo mã giảm giá, đối soát hoa hồng đều có CLI trong scripts/; các thao tác chính cũng làm được trên trang admin.

8. Dữ liệu thật đang có trên production

• Đại lý thật đầu tiên: chị Đinh Thúy Hà (đại lý legacy từ 2020). Đã import 1.008 mã kích hoạt từ file FA1 chính thức (850 gói 1 năm, 50 gói 2 năm, 108 gói 4 năm) vào kho của chị, kèm mã giảm giá riêng HALEGACY (thêm 10%).
• Nội dung Cẩm nang, 5 video đào tạo từ playlist YouTube FLYER và sale kit khởi điểm đã seed sẵn, marketing sửa được ngay.
• Các đơn hàng và hoa hồng hiện tại là dữ liệu demo phục vụ trình bày.

9. Việc còn lại trước khi chạy thật