=== Kqxs — Kết quả xổ số ===
Contributors:      TEN-DANG-NHAP-WORDPRESS-ORG-CUA-BAN
Tags:              xo so, ket qua xo so, lottery, vietlott, shortcode
Requires at least: 6.0
Tested up to:      6.7
Requires PHP:      7.4
Stable tag:        1.0.0
License:           GPLv2 or later
License URI:       https://www.gnu.org/licenses/gpl-2.0.html

Hiển thị kết quả xổ số ba miền và Vietlott bằng shortcode, dữ liệu lấy từ dịch vụ KQXS.

== Description ==

Kqxs đưa kết quả xổ số vào bài viết, trang hoặc widget bằng shortcode. Bảy
shortcode phủ các nhu cầu thường gặp: kết quả theo miền hoặc theo đài, danh
sách đài quay hôm nay, bảng kết quả trực tiếp tự làm mới, form dò số, các sản
phẩm Vietlott, danh mục đài, và bảng thống kê.

**Những điểm đáng chú ý**

* **API key không bao giờ xuống trình duyệt.** Mọi lệnh gọi ra ngoài đều xuất
  phát từ máy chủ của bạn; trình duyệt chỉ nói chuyện với route REST của chính
  plugin.
* **Đổi được giao diện từ theme.** Chép file từ `public/partials/shortcodes/`
  vào thư mục `kqxs/` trong theme là ghi đè được, không phải sửa plugin.
* **Có cache.** Mỗi shortcode đặt được thời gian cache riêng; khi API tạm thời
  không phản hồi, trang vẫn hiển thị bản đã lưu thay vì để trống.
* **Chỉ nạp CSS/JS ở trang thật sự có shortcode.**

Kết quả xổ số trên site chỉ mang tính tham khảo. Plugin không nhận, không giữ
và không xử lý bất kỳ khoản đặt cược nào.

== External services ==

Plugin này gọi tới dịch vụ bên ngoài. Dưới đây là toàn bộ danh sách, dữ liệu
được gửi đi và thời điểm gửi.

**1. KQXS API — https://api.kqxs.online**

Nguồn dữ liệu xổ số, đồng thời là nơi quản lý tài khoản và gói dịch vụ.

*Gửi đi những gì và khi nào:*

* *Ngay sau khi kích hoạt plugin:* tên miền của site và mã gói `free`, để đăng
  ký một tài khoản miễn phí và nhận API key. Đây là lần gọi tự động duy nhất.
  Tắt nó bằng cách thêm vào `wp-config.php`:
  `add_filter( 'kqxs_auto_register_enabled', '__return_false' );`
* *Khi hiển thị shortcode:* API key, tên miền của site (qua header `Origin`),
  và tham số của shortcode như miền, mã đài, ngày. Không gửi dữ liệu của người
  xem trang.
* *Khi bạn chọn một gói ở trang Tài khoản:* mã gói và API key.
* *Khi đang chờ thanh toán:* mã đơn hàng, để hỏi xem gói đã kích hoạt chưa.

Điều khoản sử dụng: DIEN-URL-DIEU-KHOAN
Chính sách riêng tư: DIEN-URL-CHINH-SACH-RIENG-TU

**2. VietQR — https://vietqr.app**

Chỉ dùng để dựng ảnh mã QR chuyển khoản, và chỉ xuất hiện trong khu quản trị
khi bạn đang có một đơn nâng gói chờ thanh toán.

Ảnh được trình duyệt của quản trị viên tải trực tiếp, nên địa chỉ IP của người
đang xem trang quản trị sẽ đến VietQR. Địa chỉ ảnh chứa mã ngân hàng, số tài
khoản nhận tiền, số tiền và nội dung chuyển khoản. Không có thông tin nào của
người xem site được gửi đi, và trang công khai không bao giờ gọi dịch vụ này.

Điều khoản sử dụng: DIEN-URL-DIEU-KHOAN-VIETQR
Chính sách riêng tư: DIEN-URL-CHINH-SACH-VIETQR

== Installation ==

1. Tải thư mục `kqxs` lên `/wp-content/plugins/`.
2. Kích hoạt plugin trong menu "Plugins" của WordPress.
3. Xong. Plugin tự đăng ký gói Free và lưu API key; vào **Kqxs → Tài khoản**
   để chép mã khách hàng ra chỗ an toàn.

== Frequently Asked Questions ==

= Shortcode nào có sẵn? =

Bảy shortcode. Vào **Kqxs → Shortcode** để xem mô tả đầy đủ và xem thử ngay
trong khu quản trị.

* `[kqxs_results]` — Kết quả theo miền, theo đài hoặc theo ngày.
  Thuộc tính: region, province, date, limit, layout, show_loto
* `[kqxs_today]` — Các đài xổ hôm nay kèm trạng thái.
  Thuộc tính: region, show_status
* `[kqxs_live]` — Kết quả trực tiếp, tự làm mới.
  Thuộc tính: region, date, refresh
* `[kqxs_check]` — Form dò số.
  Thuộc tính: province, date
* `[kqxs_vietlott]` — Mega, Power, Max 3D, Keno.
  Thuộc tính: game
* `[kqxs_provinces]` — Danh mục đài theo miền.
  Thuộc tính: region, layout
* `[kqxs_thongke]` — Lô gan, tần suất, đầu-đuôi, dự đoán.
  Thuộc tính: type, options, region, days

Mọi shortcode đều nhận thêm: title, class, cache, template.

= Tôi có phải tự lấy API key không? =

Không. Kích hoạt plugin xong là có ngay một tài khoản gói Free. Vào
**Kqxs → Tài khoản** để xem gói đang dùng, lượt gọi còn lại và mã khách hàng.

= Mã khách hàng dùng làm gì? =

Đó là cách duy nhất khôi phục quyền truy cập nếu mất API key — máy chủ chỉ
hiện key đúng một lần. Hãy chép nó ra chỗ an toàn.

= API key có bị lộ ra front-end không? =

Không. Mọi lệnh gọi API xuất phát từ máy chủ. Trình duyệt chỉ nói chuyện với
route REST của chính plugin, và không trang nào in key ra HTML.

= Muốn nâng gói thì làm sao? =

Vào **Kqxs → Tài khoản**, chọn gói. Plugin tạo đơn và hiện mã QR chuyển khoản.
Nâng gói **không** cấp API key mới — key đang dùng giữ nguyên, chỉ quyền lợi
thay đổi.

= Theme có đổi được giao diện không? =

Có. Chép file từ `public/partials/shortcodes/` vào thư mục `kqxs/` trong theme.
Ví dụ: `your-theme/kqxs/results-table.php`

= Gỡ plugin thì dữ liệu ra sao? =

Cập nhật plugin không đụng tới dữ liệu. Xoá hẳn plugin thì mọi option của nó
bị dọn sạch, gồm cả API key và mã khách hàng.

== Screenshots ==

1. Kết quả xổ số miền Bắc hiển thị bằng `[kqxs_results]`.
2. Trang dựng shortcode có xem thử trực tiếp.
3. Trang Tài khoản: gói dịch vụ, lịch sử thanh toán, lượt gọi API.

== Changelog ==

= 1.0.0 =
* Phiên bản đầu tiên: 7 shortcode kết quả xổ số, trang cấu hình, trang dựng
  shortcode có xem thử.
* Tự đăng ký gói Free khi kích hoạt; nâng gói và thanh toán ngay trong khu
  quản trị.

== Upgrade Notice ==

= 1.0.0 =
Phiên bản đầu tiên.
