# Quizzman Tarot Engine – Gieo Bài Rider–Waite Bằng Fisher–Yates & CSPRNG
**Canonical:** https://wiki.quizzman.com/wiki/quizzman-tarot-engine
**Author:** System  |  **Published:** 2026-07-27  |  **Updated:** 2026-07-31
**Tags:** Chiêm tinh, Công nghệ, Quizzman Lab, Tarot, Về Quizzman

> Quizzman Tarot Engine gieo bài Rider–Waite–Smith bằng Fisher–Yates và CSPRNG, kèm luận giải NLP theo lĩnh vực trên Quizzman Lab.

# Quizzman Tarot Engine – Gieo Bài Rider–Waite Bằng Fisher–Yates & CSPRNG
Tarot không chỉ là “rút bài ngẫu nhiên rồi đọc nghĩa”. Khi đưa lên môi trường số, câu hỏi then chốt là: **hoán vị có đều không**, **nguồn ngẫu nhiên có đoán được không**, và **luận giải có gắn ngữ cảnh lĩnh vực không**.
**Quizzman Tarot Engine** là lớp gieo bài Rider–Waite–Smith (RWS) của Quizzman Lab: chuẩn hoá 78 lá, xáo bằng **Fisher–Yates** với **CSPRNG**, rút xuôi/đảo, rồi soạn luận giải NLP theo domain (tình yêu, sự nghiệp, tài chính, sức khỏe, tinh thần) bằng tiếng Việt, English hoặc 繁中.
Trải nghiệm: [https://lab.quizzman.com/tarot](https://lab.quizzman.com/tarot)
## Quizzman Tarot Là Gì?
Quizzman Tarot gồm ba lớp:
**Deck data** — 78 lá RWS (Major + Minor) dưới dạng JSON chuẩn hoá, kèm enrichment từ khóa, nguyên tố, archetype và trọng số xác suất.
**Shuffle & Draw Engine** — tạo session bộ bài đã xáo, rút 1 hoặc 3 lá với orientation upright/reversed.
**Interpret layer** — chấm điểm theo domain, kết hợp lá, và sinh bài luận giải dạng article (overview, story, analysis, advice, timeline, yes/no).
Khác với trang “bói bài” chỉ random rồi ghép câu mẫu thô, engine tách rõ **ngẫu nhiên công bằng** và **luận giải có cấu trúc**.
## Bộ Bài Rider–Waite–Smith
Engine dùng truyền thống **Rider–Waite–Smith (1909)**: cả Ẩn chính và Ẩn phụ đều có minh họa cảnh — dễ luận giải hơn bộ Marseille kiểu pip.
**22 Major Arcana** — hành trình The Fool → The World
**56 Minor Arcana** — Wands, Cups, Swords, Pentacles × Ace–10 + Court
Dữ liệu gốc tham chiếu dataset mã nguồn mở; Quizzman bổ sung lớp enrichment (tên Việt, domain interpretation, probabilityWeight) rồi build thành `cards.json` phục vụ API.
## Thuật Toán Gieo: Fisher–Yates + CSPRNG
### Fisher–Yates (Knuth shuffle)
Đây là thuật toán chuẩn để tạo **hoán vị đều** của N phần tử trong O(N):
Bắt đầu với bộ 78 lá (ID 0…77).
Với `i` từ 77 xuống 1, chọn `j` nguyên đều trong khoảng `[0, i]`.
Đổi chỗ `deck[i]` và `deck[j]`.
Rút `k` lá đầu của bộ đã xáo; mỗi lá có thể **reversed** theo xác suất cấu hình (Lab mặc định khoảng 45%).
Khi RNG đều, mỗi thứ tự bài có xác suất bằng nhau — không thiên lệch vị trí “lá đẹp” về cuối bộ.
### CSPRNG thay cho Math.random()
Nhiều công cụ web dùng `Math.random()`. Đó là PRNG thường: đủ cho UI, nhưng **không** phải nguồn mật mã; nếu lộ trạng thái có thể dự đoán dãy tiếp theo.
Quizzman Tarot mặc định:
**Không seed** → `crypto.randomInt` / entropy hệ thống (CSPRNG) cho phiên sản xuất.
**Có seed** → hash SHA-256 + Mulberry32 để **tái lập** kết quả khi kiểm thử hoặc audit.
Nhờ đó, phiên thật khó đoán; phiên test vẫn lặp lại được khi cần.
### Orientation xuôi / đảo
Sau khi có thứ tự lá, engine gán orientation:
`upright` — nghĩa xuôi theo keywords/domain
`reversed` — đảo nghĩa / reversalEffects, ảnh hưởng scorer
UI Lab lật bài animation rồi gửi `{ id, orientation }` sang interpret.
## Kiến Trúc Triển Khai
```
Người dùng (lab.quizzman.com/tarot)
│
▼
Quizzman Lab gateway (:14000)
• SSO tùy chọn (Quizzman ID)
• Forward X-User-* / X-Guest-ID + IP/UA
│
▼
tarot-engine (:14003)
• Cards repository
• Shuffle / draw session
• Interpret NLP
• Quota + ghi lịch sử
│
▼
PostgreSQL qm_tarot
• tarot_readings
• tarot_guests (fingerprint thiết bị)
```
### Thành phần chính
| Thành phần | Vai trò |
|------------|---------|
| Frontend Lab | QMF shell, chọn lĩnh vực, flip card, hiện luận giải |
| Gateway | Proxy `/api/tool-module/tarot`, gắn identity & client meta |
| tarot-engine | REST API deck + interpret + quota |
| PostgreSQL `qm_tarot` | Lịch sử trải bài và guest fingerprint |
### API tiêu biểu
`POST /v1/deck/new` — tạo bộ đã xáo (`seed` tùy chọn)
`POST /v1/deck/:id/draw` — rút `count` lá
`GET /v1/quota` — số lượt còn lại
`POST /v1/interpret` — luận giải theo `domain` + `lang` + `cards`
Qua Lab: tiền tố `/api/tool-module/tarot`.
## Quota & Lịch Sử
Để chống crawl/bot và giữ trải nghiệm công bằng:
**Khách:** 1 lần (lifetime) — `guestId` lưu trên trình duyệt + fingerprint IP/UA phía server
**User free:** 1 lần / ngày (múi giờ Asia/Ho_Chi_Minh)
**Pro trở lên:** từ 3 lần / ngày trở lên theo tier
Mỗi lần interpret thành công được ghi vào `tarot_readings` (domain, lá, summary, UA, browser/OS/device…)
UI chỉ hiện **số lượt còn** và nút nâng cấp — không phô email.
## Luận Giải NLP Theo Domain
Interpret không dừng ở “liệt kê keyword”. Engine:
Resolve metadata từng lá theo orientation
Score theo `probabilityWeight` và domain
Ghép combination / conflict
Sinh narrative: overview, story & journey, phân tích từng lá, lời khuyên, timeline, yes/no
Ngôn ngữ luận giải: **vi** · **en** · **zht** (phồn thể).
## Vị Trí Trong Hệ Sinh Thái Quizzman
| Sản phẩm | Quan hệ |
|----------|---------|
| [Quizzman Lab](https://wiki.quizzman.com/wiki/quizzman-lab) | Host UI `/tarot` và gateway API |
| [I-Ching Engine](https://wiki.quizzman.com/wiki/quizzman-i-ching-engine) | Họ “gieo” deterministic / có kiểm soát RNG khác truyền thống |
| Quizzman ID / Payments | SSO tier Pro+ mở thêm lượt |
## Quizzman Tarot Không Phải Là Gì?
Không thay thế tư vấn tâm lý hoặc quyết định pháp lý / y tế
Không phải LLM “bịa” nghĩa lá không nguồn
Không dùng `Math.random()` cho phiên gieo sản xuất
Không phải marketplace bán bộ bài vật lý
Đây là **engine gieo + luận giải có cấu trúc** trên Lab.
## Đối Tượng
Người muốn gieo RWS online với quy trình rõ ràng
Người học Tarot cần thấy xuôi/đảo và domain
Lập trình viên / R&D quan tâm Fisher–Yates + CSPRNG trên bộ 78 lá
User Quizzman Pro cần nhiều lượt hơn mỗi ngày
## Kết Luận
**Quizzman Tarot Engine** đưa Tarot Rider–Waite lên hạ tầng Lab với ba trụ cột: **dữ liệu 78 lá chuẩn hoá**, **xáo Fisher–Yates + CSPRNG**, và **luận giải NLP theo lĩnh vực**. Mỗi lần gieo có thể kiểm soát quota và lưu lịch sử — minh bạch hơn các trang random thuần túy.
Bắt đầu tại [https://lab.quizzman.com/tarot](https://lab.quizzman.com/tarot).