Tài liệu — PrizeX

Tổng quan

PrizeX là gì

PrizeX là nền tảng phần thưởng, trò chơi và chợ thương mại viết bằng PHP: đấu giá, xổ số, hộp bí ẩn, một cụm trò chơi arcade, cửa hàng thương mại điện tử đa người bán và nền kinh tế ví/xu — tất cả trong một ứng dụng tự triển khai. Sản phẩm đi kèm kiến trúc plugin/theme, một trang quản trị và 38 plugin cổng thanh toán bao phủ thẻ, ví điện tử, tiền mã hóa cùng các đơn vị xử lý khu vực, cộng thêm 3 phương thức thanh toán thủ công do phần lõi tạo sẵn.

Không có chuyện bị SaaS trói chân: bạn cài trên hosting của mình, sở hữu cơ sở dữ liệu và nhận cập nhật trọn đời theo giấy phép. Mọi mảng nghiệp vụ (đấu giá, xổ số, hộp bí ẩn, trò chơi, cửa hàng) đều bật tắt độc lập được từ trang quản trị — một bản cài mới có thể chạy như sản phẩm chỉ một mảng duy nhất, hoặc chạy trọn bộ.

Kiến trúc

Vận hành bằng plugin & theme

Mã nguồn lõi không bao giờ phụ thuộc cứng vào một plugin nào. Mọi mảng nghiệp vụ, cổng thanh toán và hình thức đăng nhập mạng xã hội đều là một plugin nằm trong plugins/, có thể bật, tắt hoặc xóa mà không làm hỏng phần còn lại của website.

Dữ liệu

MySQL / MariaDB, mysqli thuần

Tiền tố bảng tbl_, không dùng ORM, phần lớn là prepared statement. Mỗi plugin tự sở hữu và tự nâng cấp các bảng của mình qua trình cài đặt db_delta() mang tính idempotent.

Yêu cầu hệ thống

Chạy trên nền gì

PrizeX chạy được trên hosting chia sẻ thông thường hoặc VPS — không cần cấu hình máy chủ đặc biệt nào ngoài một máy chủ web có bật rewrite.

Môi trường chạy

PHP 7.4+

Cần extension GD & cURL

Cơ sở dữ liệu

MySQL / MariaDB

Cần MariaDB cho các migration*

Thư viện phụ thuộc

Composer

Trình quản lý gói PHP

Máy chủ web

Apache / LiteSpeed

Hỗ trợ nginx qua file cấu hình mẫu

* Một số file trong database/migrations/ dùng phần mở rộng ADD COLUMN IF NOT EXISTS vốn chỉ có ở MariaDB. MySQL 8.0/8.4 thuần sẽ từ chối cú pháp này — hãy dùng MariaDB cho cơ sở dữ liệu, ở cả môi trường phát triển lẫn môi trường chạy thật.

Cài đặt

Đưa một bản cài mới vào hoạt động

Không có trình hướng dẫn cài đặt cho bản cài mới — bạn nhập thẳng lược đồ cơ sở dữ liệu rồi cấu hình file môi trường.

Cài các thư viện PHP:
composer install
Sao chép file môi trường mẫu rồi điền thông tin đăng nhập cơ sở dữ liệu của bạn:
cp .env.example .env
Nhập database/production.sql vào cơ sở dữ liệu mà bạn khai trong .env — bước này tạo ra toàn bộ lược đồ.
Thay tài khoản quản trị được tạo sẵn (xem lưu ý bên dưới), rồi đăng nhập tại /admin/.

Đừng đăng nhập bằng tài khoản được tạo sẵn. database/production.sql đi kèm một dòng tbl_admin (admin@wowcodes.in) có mã băm mật khẩu giống hệt nhau trên mọi bản cài. Hãy xóa dòng đó và chèn tài khoản của riêng bạn trước khi lên sóng:

php -r "echo password_hash('your-password', PASSWORD_BCRYPT), \"\n\";"

DELETE FROM tbl_admin;
INSERT INTO tbl_admin (username, email, password, image, status, permission_settings)
VALUES ('yourname', 'you@example.com', '<hash from the command above>', '', 1, 1);

Khi phát triển ở máy cục bộ, máy chủ PHP tích hợp chạy được mà không cần Apache: php -S localhost:8000 router.php — lưu ý rằng máy chủ này bỏ qua hoàn toàn .htaccess, nên router.php phải cài đặt lại thủ công đúng bộ quy tắc định tuyến ấy (xem Thiết lập máy chủ web).

Cấu hình

Biến môi trường

Mọi thiết lập riêng theo từng môi trường đều nằm trong .env, được nạp qua vlucas/phpdotenv. Sao chép .env.example thành .env (đã được git bỏ qua) và điền giá trị thật cho từng môi trường — ít nhất là thông tin đăng nhập cơ sở dữ liệu, trước khi nhập lược đồ.

Những thiết lập áp dụng cho toàn site mà không phụ thuộc môi trường (tên ứng dụng, đơn vị tiền tệ, plugin đang bật, theme đang dùng và công tắc bật tắt từng mảng nghiệp vụ) nằm trong cơ sở dữ liệu, ở bảng tbl_settings, và được quản lý từ trang quản trị chứ không phải trong file.

Triển khai

Thiết lập máy chủ web

Các quy tắc định tuyến và bảo mật — URL thân thiện, chặn truy cập trực tiếp vào .env/connection.php/file log, và ngăn nội dung tải lên chạy như mã PHP — được khai báo trong những file .htaccess nằm rải rác khắp dự án. Apache và LiteSpeed/OpenLiteSpeed đọc thẳng được các file này.

Với nginx, hãy dùng nginx.conf.example: file này tái hiện đúng từng quy tắc kể trên dưới dạng một khối server{} của nginx — bạn chỉ cần chỉnh server_name, root và socket PHP-FPM cho khớp môi trường của mình.

Hãy giữ ba file này đồng bộ với nhau. .htaccess (môi trường chạy thật), router.php (máy chủ dev php -S cục bộ) và nginx.conf.example (nginx) mỗi file tự cài đặt lại cùng một bộ quy tắc định tuyến một cách độc lập. Thêm một route URL thân thiện mới nghĩa là phải cập nhật cả ba.

Khái niệm cốt lõi

Kiến trúc xử lý yêu cầu

Mọi trang phía giao diện cửa hàng (index.php, item.php, …) đều khởi động qua includes/header.php, theo thứ tự sau:

Định vị địa lý & ngôn ngữ→ connection.php→ themes.php→ hooks.php→ plugins.php→ routes.php→ menus.php→ assets.php→ plugins_load()

connection.php khởi tạo phiên làm việc, kết nối qua mysqli bằng thông tin đăng nhập trong .env, nạp tbl_settings vào những hằng số như APP_NAME và CURRENCY, rồi đăng nhập người dùng hiện tại kèm một dòng vân tay thiết bị. plugins_load() khởi động mọi plugin đang bật và kích hoạt hook plugins_loaded — đây chính là thời điểm ta biết được tập hợp thật sự các mảng nghiệp vụ đang bật, và đó là lý do ngay sau đó header.php kiểm tra lại các cờ thiết lập cũ (shop, multivendor, auction, lottery) đối chiếu với trạng thái plugin thực sự đang bật.

Trang quản trị không lặp lại quy trình khởi động này — admin/includes/connection.php đặt cấu hình phiên/lỗi riêng cho khu vực quản trị rồi include chính file includes/connection.php ở thư mục gốc.

Khái niệm cốt lõi

Hệ thống plugin

Một plugin là plugins/<slug>/plugin.php — phần metadata nằm trong comment đầu file, được đọc mà không cần thực thi file — cộng thêm một plugin.json tùy chọn chứa thông tin catalog đầy đủ hơn. Danh sách plugin đang bật được lưu dưới dạng mảng JSON trong tbl_settings.active_plugins.

Mỗi plugin sở hữu bảng của riêng mình — mỗi plugin tự khai báo file includes/schema.php của nó, được gọi lúc kích hoạt, dùng hàm hỗ trợ db_delta() mang tính idempotent (CREATE TABLE IF NOT EXISTS + ALTER TABLE ADD COLUMN chỉ thêm chứ không sửa). Một plugin không bao giờ động vào bảng của plugin khác.
Các registry được nạp trước — add_admin_page, add_route, add_cron_job, add_api_route và register_module đều được định nghĩa trước khi bất kỳ plugin nào được nạp, nên những lời gọi ở cấp cao nhất của một plugin không bao giờ gây lỗi chí mạng, kể cả khi plugin đó rốt cuộc không được bật.
Gỡ bỏ sạch sẽ — xóa một plugin sẽ chạy file uninstall.php của nó rồi bỏ luôn thư mục plugin; không thứ gì bên ngoài plugins/<slug>/ được phép require cứng các file của nó, nhờ vậy phần còn lại của website vẫn chạy bình thường khi plugin đã biến mất.

Khái niệm cốt lõi

Hệ thống theme

Một theme nằm tại assets/themes/<slug>/ — gồm manifest.php, theme.css, functions.php cho các hook của theme và thư mục components/ tùy chọn. Theme đang dùng được lưu trong tbl_settings.active_theme, với editorial là bản dự phòng nếu chưa đặt gì.

Việc tìm component diễn ra lần lượt theo thứ tự: thư mục components/ của chính theme đang dùng, rồi tới thư mục component mà một plugin khai báo qua register_module(), cuối cùng là thư mục components/ dùng chung ở gốc. Trên thực tế, bản mặc định dùng chung chỉ tồn tại một lần trong components/, và bất kỳ theme nào — hoặc plugin mảng nghiệp vụ đang bật — đều có thể ghi đè một đường dẫn component cụ thể bằng bản sao của riêng nó.

Khái niệm cốt lõi

Cơ sở dữ liệu

Tiền tố bảng tbl_, mysqli thuần, phần lớn là prepared statement. Các file SQL, xếp theo mức độ ưu tiên:

database/core-schema.sql — chỉ gồm các bảng lõi, được bảo trì thủ công; bảng của các mảng nghiệp vụ/plugin được cố ý để ra ngoài.
database/production.sql — sinh tự động (lược đồ lõi + trình cài đặt riêng của từng plugin, dump ra từ một cơ sở dữ liệu trắng). Đây chính là file bạn nhập khi cài mới.
database/sandbox.sql — bộ dữ liệu demo/khởi tạo dành cho phát triển cục bộ.
database/migration.sql — script nâng cấp hợp nhất, mang tính idempotent, dành cho các bản cài đã chạy sẵn.
database/migrations/<slug>/up.sql (+ down.sql ở những chỗ đảo ngược được) — mỗi migration một file riêng.

Những gì có sẵn

Mô-đun

Mọi mô-đun đều nằm trong cùng một bản cài và được bật tắt độc lập từ trang quản trị.

Đấu giá

Đấu giá trực tiếp với cổng dành cho người bán theo mô hình đa người bán và bộ máy tính hoa hồng. Plugin lõi: plugins/auction.

auction-anti-snipeauction-autobidderauction-buy-nowauction-notify-meauction-premiumauction-shippingauction-unlock

Xổ số

Quay thưởng theo vé, với lịch quay, giải thưởng và thông báo người trúng đều cấu hình được. Plugin lõi: plugins/lottery.

lottery-live-tickerlottery-print-ticket

Hộp bí ẩn

Kho giải thưởng cấu hình được kèm hiệu ứng mở hộp — người dùng mua một hộp và thấy ngay mình trúng gì. Plugin: plugins/mystery-box.

Trò chơi & phần thưởng

Một cụm trò chơi arcade nằm trong games/ cùng các plugin tương tác/kiếm thưởng:

2048bamboo-fortuneclick-speedemoji-funhex-burstodd-one-outword-search

earn-gamesearn-daily-bonusearn-offerwallsearn-watch-earn

Cửa hàng & chợ thương mại

Lớp thương mại điện tử đa người bán kèm bộ công cụ khuyến mãi và trưng bày hàng hóa. Plugin lõi: plugins/shop, plugins/multivendor.

couponsgift-cardsshop-abandoned-cartshop-b2bshop-flash-salesshop-merchandisingshop-opsshop-shippingdigital-assetsesim-store

Ví, xu & đầu tư

Một chiếc ví dùng chung cho toàn nền tảng, xuyên suốt mọi mô-đun.

finance-coin-pricingfinance-exchange-ratesfinance-tax-settingswallet-transferinvestwithdrawals

Giới thiệu & phần thưởng

referralsreferrals-multilevel

Xác thực, tin cậy & tuân thủ

google-loginfacebook-loginapple-loginemail-otprecaptchafraud-preventionrolesmembershipuser-impersonation

Tiện ích

blogcachetawk-chatinsightsmanual-gateway-buildermobile-app-settings

Nền tảng

Trang quản trị

Trang quản trị nằm trong admin/ và không lặp lại quy trình khởi động của giao diện cửa hàng — nó đặt cấu hình phiên/lỗi riêng cho khu vực quản trị, rồi include chính file includes/connection.php ở thư mục gốc. Các trang được đăng ký qua add_admin_page(), hàm này lo luôn mục trong sidebar, việc chặn theo quyền hạn, CSRF và khung xác thực; những thao tác JSON chỉ dành cho quản trị thì đăng ký qua add_admin_ajax() và được điều phối qua admin/ajax.php?action=<slug>.

Danh mục & nội dung

Sản phẩm, banner, trang, menu, blog.

Thanh toán

Quản lý cổng tự động & thủ công, duyệt thanh toán thủ công, xuất dữ liệu chi trả.

Người dùng & người bán

Nhóm người dùng, vai trò, thông tin người bán, đăng nhập thay người dùng.

Báo cáo & nhật ký

Xuất dữ liệu giao dịch/đơn hàng/người dùng, nhật ký cron, theo dõi lỗi, nhật ký hoạt động quản trị.

Tiếp thị

Chiến dịch email, mẫu email, bản tin, thông báo đẩy, nhật ký thông báo.

Plugin, theme & SEO

Bật/tắt plugin và theme, thiết lập SEO cho từng trang, thiết lập cho toàn site.

Nền tảng

Theme giao diện cửa hàng

Năm theme đi kèm trong assets/themes/, đổi được cho từng bản cài ngay trong trang quản trị. Mỗi theme giữ bản sao riêng của các component dùng chung trong thư mục components/ của chính nó.

Classic

Giao diện đơn giản, hiện đại với thẻ nền trắng và bóng đổ nhẹ — lựa chọn an toàn, linh hoạt cho gần như mọi kiểu cửa hàng.

Editorial

Giao diện sạch sẽ theo phong cách tạp chí với tông giấy ấm và kiểu chữ sắc nét, cho một mặt tiền chỉn chu và đáng tin cậy.

Theme mặc định dùng để dự phòng

Casino

Theme tối màu mạnh mẽ, sang trọng với điểm nhấn vàng kim — thiết kế để tạo cảm giác hứng khởi và cao cấp.

Bazaar

Giao diện ấm áp, trang trí đậm nét lấy cảm hứng từ những khu chợ truyền thống, có hỗ trợ ngôn ngữ viết từ phải sang trái.

Halloween

Giao diện theo mùa vừa rùng rợn vừa vui nhộn — nền tím thẫm cùng những điểm nhấn cam bí ngô rực sáng.

Nền tảng

Cổng thanh toán

38 cổng tự động đều thuộc về plugin — mỗi cổng nằm trong thư mục plugins/gateway-<slug>/ riêng và tự đăng ký với phần lõi qua add_payment_gateway(). Bật một cổng lên là nó chạy được ngay; không có chỗ nào trong bộ điều phối thanh toán (payment_processor.php) bị gắn cứng vào một cổng cụ thể.

Thẻ & đơn vị xử lý toàn cầu

2CheckoutAmazon PayAuthorize.NetBlueSnapCheckout.comMollieNMIPayPalPayeerSkrillStripeVenmoWise

Đơn vị xử lý khu vực & nội địa

AamarpayBkashCashfreeCashmaalFlutterwaveGoCardlessInstamojoInTouchMercado PagoMidtransM-PesaNagadOpenPixPaystackPaytmPayURazorpaySSLCommerz

Tiền mã hóa

BinanceBlockchain.comCoinbase CommerceCoinGateCoinPaymentsMoonPayNOWPayments

Thủ công (theo hướng dẫn / mã QR)

UPIBank TransferPayTM QR

3 phương thức thủ công là những dòng gateway_type = 'manual' do phần lõi tạo sẵn, không có mã init/verify nào để cấu hình — chúng chỉ hiển thị hướng dẫn thanh toán hoặc một mã QR. Plugin manual-gateway-builder cho phép quản trị viên thêm những phương thức thanh toán thủ công tùy chỉnh khác mà không cần đụng tới code.

Một vài cổng (Stripe, Razorpay, Midtrans, Venmo) còn đăng ký thêm hook render cho những luồng thanh toán cần JS phía trình duyệt — chẳng hạn đoạn khởi tạo Stripe Checkout, hoặc SDK Razorpay/Midtrans/Braintree cần một mã đơn hàng hay token được tạo trước ở phía máy chủ. Mọi cổng còn lại chạy được mà không cần đấu nối thêm gì vào phần lõi.

Nền tảng

Lớp API & AJAX

api/v1/ — REST API xác thực bằng JWT, dành cho ứng dụng di động và các bên tích hợp bên ngoài. api/v1/middleware/*.php kiểm tra header Authorization: Bearer <token>. Plugin tự thêm endpoint của mình qua add_api_route().
ajax/ — lớp AJAX nội bộ xác thực bằng cookie phiên, phục vụ chính phần JS của giao diện cửa hàng (giỏ hàng, mã giảm giá, thông báo). Không có tầng token — nó dựa vào phiên PHP do connection.php thiết lập.
Thư mục api/ rời ở cấp gốc — các endpoint linh tinh không đánh phiên bản như geo_location.php, exchange-rate.php và offerwall_postback.php.

Nền tảng

Ứng dụng di động

mobile/ là một dự án Capacitor + Ionic riêng biệt — một lớp bọc WebView quanh chính website đang chạy, không phải SPA độc lập và cũng không đơn thuần là bên tiêu thụ api/v1. File capacitor.config.ts của nó trỏ server.url về tên miền của bạn. Dự án này có package.json riêng và không được build từ thư mục gốc của dự án chính:

cd mobile
npm run sync
npm run open:ios
npm run open:android

Vận hành

Cập nhật & migration

Hãy sao lưu một bản trước khi chạy database/migration.sql hay bất kỳ file database/migrations/<slug>/up.sql nào lên cơ sở dữ liệu đang chạy thật:

mysqldump --single-transaction -u<user> -p<pass> <db> > pre-deploy-$(date +%Y%m%d-%H%M%S).sql

Phần lớn migration đều đi kèm một file down.sql tương ứng để đảo ngược đúng thay đổi đó. Một số ít migration biến đổi dữ liệu sẵn có chứ không chỉ thêm cấu trúc thì lại kèm một down.sql giải thích vì sao nó không làm gì cả — với những trường hợp đó, nếu cần quay lui thì hãy phục hồi từ bản dump lấy trước lúc triển khai.

Vận hành

Lưu ý bảo mật

Hãy đổi thông tin đăng nhập quản trị được tạo sẵn ngay sau khi nhập dữ liệu (xem Cài đặt).
.env, connection.php và các file log bị chặn truy cập HTTP trực tiếp bởi những quy tắc .htaccess / nginx đi kèm — đừng gỡ các quy tắc đó.
Nội dung tải lên được phục vụ theo cách ngăn nó chạy như mã PHP, và điều này được cưỡng chế ở tầng cấu hình máy chủ web chứ không phải ở tầng ứng dụng.
Thông tin xác thực của cổng thanh toán được cấu hình riêng cho từng cổng trong trang quản trị và lưu ở phía máy chủ — không bao giờ lộ ra giao diện cửa hàng.

Vận hành

Kiểm thử

Không có bộ test PHPUnit. composer test chạy bin/run-probes.php, script này gom mọi file probe_*.php nằm trong includes/_probes/ và trong thư mục _probes/ của từng plugin, chạy mỗi file như một tiến trình CLI riêng rồi kiểm tra mã thoát của nó.

composer test                              # run every probe
php plugins/<slug>/_probes/probe_*.php     # run a single probe directly
php bin/run-probes.php --all               # also run destructive probes (skipped by default)

Trợ giúp

Câu hỏi thường gặp

Không. Đấu giá, xổ số, hộp bí ẩn, trò chơi và cửa hàng/chợ thương mại đều là những plugin độc lập — bạn chỉ bật thứ mà việc kinh doanh của mình cần, rồi bật thêm về sau mà không phải cài lại.

Được. Xóa một plugin sẽ chạy trình gỡ cài đặt của chính nó và chỉ xóa những bảng cùng file của riêng nó — phần chức năng lõi của website được thiết kế để không bao giờ phụ thuộc vào sự có mặt của một plugin cụ thể.

MariaDB. Một số file migration dùng cú pháp SQL chỉ MariaDB mới hiểu, còn MySQL 8 thuần thì từ chối — hãy dùng MariaDB ở cả môi trường phát triển lẫn môi trường chạy thật.

38 plugin cổng tự động (thẻ, ví điện tử, tiền mã hóa và các đơn vị xử lý khu vực) cộng thêm 3 phương thức thủ công — UPI, Bank Transfer và PayTM QR — do lược đồ lõi tạo sẵn. Plugin Manual Gateway Builder cho phép bạn thêm những phương thức thủ công khác mà không cần viết code.

Trợ giúp

Hỗ trợ & tài nguyên

Vẫn còn vướng, hoặc cần thứ mà trang này chưa nói tới?

Hỗ trợ

Mở một yêu cầu hỗ trợ để được giúp về cài đặt hoặc cấu hình.

Trò chuyện trực tiếp với đội ngũ WowCodes.

Liên hệ

Câu hỏi chung hoặc phát triển theo yêu cầu.

Tài liệu PrizeX

PrizeX là gì

Chạy trên nền gì

Đưa một bản cài mới vào hoạt động

Biến môi trường

Thiết lập máy chủ web

Kiến trúc xử lý yêu cầu

Hệ thống plugin

Hệ thống theme

Cơ sở dữ liệu

Mô-đun

Đấu giá

Xổ số

Hộp bí ẩn

Trò chơi & phần thưởng

Cửa hàng & chợ thương mại

Ví, xu & đầu tư

Giới thiệu & phần thưởng

Xác thực, tin cậy & tuân thủ

Tiện ích

Trang quản trị

Theme giao diện cửa hàng

Cổng thanh toán

Lớp API & AJAX

Ứng dụng di động

Cập nhật & migration

Lưu ý bảo mật

Kiểm thử

Câu hỏi thường gặp

Hỗ trợ & tài nguyên