📌 1. GIỚI THIỆU TỔNG QUAN HỆ THỐNG
SimCode OTP Hub là mã nguồn thương mại điện tử chuyên dụng cho mô hình kinh doanh dịch vụ cho thuê SIM nhận mã OTP tự động 24/7. Hệ thống được xây dựng trên nền tảng Laravel 13.x (PHP 8.3+) mới nhất, kết hợp công nghệ Telegram MiniApp tiêu chuẩn cùng giao diện Web Admin Panel quản trị hiện đại.
Khách hàng chỉ cần truy cập Bot Telegram, mở MiniApp là có thể thuê số điện thoại nhận OTP (Zalo, Telegram, WhatsApp, Facebook, TikTok, Shopee, Gmail, v.v...) chỉ với 1-Click mà không cần tải hay cài đặt bất kỳ ứng dụng nào khác.
🏛️ 2. PHÂN TÍCH TINH HOA KIẾN TRÚC MÃ NGUỒN (PROJECT ARCHITECTURE)
Mã nguồn được thiết kế chuẩn mực theo các nguyên tắc lập trình hiện đại nhất (SOLID, Clean Code, DRY), mang đến hiệu năng vượt trội và khả năng mở rộng không giới hạn.
simcode-otp/
├── app/
│ ├── Actions/ <-- TINH HOA: 100% Business Logic tách thành Single Responsibility Actions
│ │ ├── Admin/ <-- Các Action nghiệp vụ Admin (User, Provider, Service, Invoice, Transaction, CronJob)
│ │ ├── MiniApp/ <-- Các Action nghiệp vụ Telegram MiniApp (Auth, Service List, History)
│ │ ├── Order/ <-- Action xử lý thuê SIM, check OTP, thuê lại số, hoàn tiền
│ │ └── Setting/ <-- Action cấu hình Telegram Bot Webhook & Menu Button
│ ├── Console/Commands/ <-- Lệnh Artisan chạy tự động (Check OTP realtime, Auto Expire Invoices)
│ ├── Enums/ <-- Ép kiểu dữ liệu nghiêm ngặt (UserRoleEnum, Status Enums)
│ ├── Http/
│ │ ├── Controllers/ <-- Controllers mỏng nhẹ (Skinny Controllers) chỉ đóng vai trò điều phối
│ │ ├── Middleware/ <-- Middleware CheckIsAdmin, Auth, CSRF Exemption
│ │ └── Requests/ <-- Form Requests Validation riêng biệt cho mọi Endpoint
│ └── Models/ <-- Eloquent Models với Accessors chuẩn (Tự động tải & Proxy Avatar Telegram)
├── bootstrap/app.php <-- Laravel 13 Routing & Middleware Pipeline Cấu hình mới nhất
├── routes/
│ ├── admin.php <-- Routes GET Render View Giao diện Admin
│ ├── api.php <-- Routes AJAX POST API (Admin & MiniApp)
│ ├── console.php <-- Lập lịch Artisan Schedule chạy ngầm từng phút
│ ├── cronjobs.php <-- Webhook CronJob Execution từ bên ngoài
│ └── web.php <-- Direct Routing & Telegram Webhook Catch Fallback
└── public/frontend/ <-- Giao diện Vanilla CSS/JS tối ưu tận răng, không dán nhãn placeholder💎 NỔI BẬT VỀ KỸ THUẬT (TECHNICAL HIGHLIGHTS)
- Chuẩn Khung Framework Laravel 13 & PHP 8.3: Sử dụng các tính năng cao cấp của PHP 8.3:
declare(strict_types=1), Typed Properties, Match Expressions, Enums. Cấu hình Routing & Exceptions hoàn toàn mới trênbootstrap/app.phptheo chuẩn Laravel 13. - Mô Hình Skinny Controller & Fat Action Pattern: Controller không chứa bất kỳ câu lệnh SQL hay logic tính toán nào. Tất cả logic được đóng gói độc lập trong thư mục
app/Actions/, giúp mã nguồn cực kỳ dễ bảo trì và mở rộng. - An Toàn Giao Dịch Ví (Race Condition & Locking Protection): Tất cả các thao tác Trừ tiền thuê SIM, Nạp tiền tự động, và Hoàn tiền đều sử dụng
DB::transaction()kết hợplockForUpdate()trên Model User và Order, ngăn chặn triệt để lỗi người dùng gian lận bấm nhiều lần tiêu quá số dư (Double Spending Bug). - Tự Động Tải & Lưu Trữ Cục Bộ Ảnh Đại Diện Telegram: Hệ thống tự động gọi Telegram API để lấy ảnh đại diện của khách hàng và tải trực tiếp về ổ đĩa server (
/uploads/avatars/tg_{id}.jpg). CSDL lưu trữ đường dẫn tĩnh cục bộ, giúp hình ảnh load tức thì trong 0.01 giây, tránh lỗi CORS/Referrer 404. - Phân Mạch Nhật Ký Giao Dịch Minh Bạch (Transaction Logs): Phân biệt rõ ràng giữa 4 loại giao dịch:
in(Nạp tiền VietQR),out(Thuê SIM OTP),refund(Tự động hoàn tiền đơn hết hạn),add/subtract(Admin cộng/trừ tiền thủ công). - Xử Lý CSRF Token Exception Thông Minh: Cấu hình middleware loại trừ các Endpoint AJAX API
/api/*khỏi rào cản CSRF Token Mismatch, đồng thời giữ nguyên lớp bảo mật Session Auth &is_admin. Tránh hoàn toàn lỗi màn hình đỏ 419 khi treo máy lâu.
🛠️ 3. BẢNG TỔNG HỢP TECH STACK & TÍNH NĂNG
Bảng tổng quan thông số kỹ thuật cốt lõi của dự án SimCode OTP Hub:
| Thành phần | Công nghệ / Thư viện | Mô tả giải pháp |
|---|---|---|
| Core Engine | PHP 8.3+ & Laravel 13.x | Áp dụng chuẩn Strict Types 100%, cấu hình Bootstrap Pipeline hoàn toàn mới. |
| Business Pattern | Single Responsibility Actions | Tách biệt 100% logic kinh doanh ra khỏi Controller, xử lý đa luồng an toàn. |
| Client Interface | Telegram MiniApp SDK | Chạy mượt mà trực tiếp trên Telegram Webview, xác thực tự động qua HMAC-SHA256. |
| Database Layer | MySQL 8.0+ / MariaDB | Áp dụng Pessimistic Locking (lockForUpdate) chống lỗi gian lận số dư. |
| Payment Gateway | VietQR Auto Deposit | Sinh mã QR động theo chuẩn định dạng ngân hàng, Cronjob đối soát cộng tiền trong 3 giây. |
| Security Layer | Session Auth + HMAC-SHA256 | Miễn trừ CSRF cho API nhưng giữ nguyên cơ chế bảo mật Session Auth & IsAdmin Middleware. |
🔥 4. CHỨC NĂNG CHI TIẾT CỦA MÃ NGUỒN
📱 A. Telegram MiniApp Dành Cho Khách Hàng
- Đồng Bộ Tài Khoản 1-Click: Tự động xác thực HMAC-SHA256 từ
initDatacủa Telegram WebApp SDK, đăng ký/đăng nhập tự động không cần nhập mật khẩu. - Thuê SIM & Nhận OTP Tự Động: Chọn Quốc Gia (Việt Nam, Lào, Campuchia, v.v...) và Dịch vụ (Telegram, Zalo, WhatsApp, v.v...). Hệ thống tự động lấy số và chờ mã OTP realtime.
- Chế Độ Hoàn Tiền Tự Động 100% (Auto Refund): Nếu sau 3 phút không có tin nhắn OTP trả về từ nhà mạng, đơn hàng tự động chuyển sang trạng thái "Đã Hoàn Tiền" và cộng lại 100% tiền vào ví khách hàng.
- Chức Năng Thuê Lại Số Cũ (Re-Rent): Cho phép khách hàng yêu cầu lấy lại đúng số điện thoại đã thuê để nhận mã xác thực bổ sung.
- Nạp Tiền VietQR Mã QR Động: Tạo mã QR chuyển khoản VietQR chuẩn định dạng ngân hàng. Tự động cộng tiền ví trong 3 giây khi tiền vào tài khoản.
- Giao Diện Thẻ Card 3 Tầng Tối Ưu Tận Răng:
- Tầng 1: Mã đơn
#ORD_...nổi bật góc trái + Badge trạng thái có Icon rực rỡ góc phải ([✓ Thành Công], [↻ Đã Hoàn Tiền], [⏳ Chờ OTP]). - Tầng 2: Icon dịch vụ + Tên dịch vụ + Số điện thoại nhận OTP màu xanh nổi bật + Giá tiền.
- Tầng 3: Mã OTP nhận về + Nút thao tác nhanh [↻ Thuê Lại Số].
- Tầng 1: Mã đơn
- 100% Responsive: Chống tràn khung, chống rớt chữ trên mọi kích thước màn hình điện thoại.
🛡️ B. Web Admin Panel Quản Trị Dành Cho Chủ Hệ Thống
- Bảng Điều Khiển Tổng Quan (Dashboard): Thống kê tổng số thành viên, số dư ví toàn sàn, tổng doanh thu nạp tiền và tổng đơn thuê SIM.
- Quản Lý Thành Viên (
/users): Xem danh sách thành viên, số dư ví, thông tin tài khoản Telegram. Khóa / Mở khóa tài khoản khách hàng. Modal Cộng / Trừ tiền thủ công với lý do chi tiết. - Quản Lý Hóa Đơn Nạp Tiền (
/invoices): Xem nhật ký nạp VietQR, trạng thái hóa đơn (Chờ chuyển, Thành công, Đã hủy, Hết hạn). - Quản Lý Biến Động Số Dư (
/transactions): Theo dõi toàn bộ lịch sử dòng tiền chảy qua hệ thống minh bạch. - Quản Lý Nhà Cung Cấp SIM (
/providers): Cấu hình API Token của các đối tác SIM (ViOTP, Chothuesimcode, OTPSim, v.v...). - Quản Lý Dịch Vụ (
/services): Import danh sách dịch vụ từ nhà cung cấp và tự động cài đặt tỷ lệ chiết khấu lợi nhuận (Markup Price). - Cấu Hình Bot Telegram (
/settings): Tự động nhận diện domain HTTPS (Ngrok / Domain thật) và tự động thiết lập Webhook & Menu Button cho Bot Telegram chỉ bằng 1 cú nhấp chuột. - Quản Lý CronJobs (
/cronjobs): Nhật ký thực thi các lệnh chạy ngầm tự động.
