Kỳ Viện — Dự án cờ tướng

Giao diện cổ trang hiện đại: nền mực, son đỏ, vàng đồng, bàn cờ gỗ. Frontend Next.js + React + TypeScript; backend Python/FastAPI; dữ liệu PostgreSQL.

Đối chiếu với yêu cầu

#	Yêu cầu	Đã làm	Kiểm tra bằng
1	Giao diện đăng ký / đăng nhập	Hộp thoại Đăng nhập/Đăng ký; đăng nhập bằng Google (Gmail) qua OAuth 2.0; mật khẩu băm scrypt, cookie HttpOnly; chống dò mật khẩu theo từng tài khoản (một người gõ sai không khóa cả trang)	E2E 01-basics, 05-resilience; pytest
2	Tạo room chơi game	"Tạo phòng mới" → mã 6 ký tự; danh sách phòng đang chờ (chỉ phòng mà chủ phòng còn online, mới nhất trước); mục Phòng của bạn; nút Rời phòng	E2E 01, 02; pytest
3	Mời bạn vào room — trong game, MXH, mã phòng	Trong game: mời theo tên tài khoản, người nhận thấy thông báo (toast có nút Tham gia + huy hiệu trên menu) dù đang ở màn hình nào. MXH: hộp chia sẻ của thiết bị (Zalo, Messenger… trên điện thoại), nút Facebook / Telegram / X / Email, Sao chép lời mời để dán vào Zalo/Messenger; liên kết có ảnh xem trước. Mã phòng / liên kết ?room=MÃ: người chưa có tài khoản mở liên kết → đăng ký → vào thẳng phòng	E2E 02-invite-resume
4	Load bàn cờ + lưu bàn cờ	Lưu vào tài khoản (PostgreSQL), lưu trên trình duyệt (khách), xuất/nạp JSON, xóa ván đã lưu; khi nạp chọn chơi tiếp với máy hoặc hai người. Tải lại trang (F5): ván với máy được tự khôi phục, phòng online được nạp lại từ PostgreSQL (bàn cờ, lượt, lịch sử, chat)	E2E 03-saves-ai, 02-invite-resume
5	Chơi 2 người online qua mạng	WebSocket; máy chủ kiểm tra người chơi, lượt, phiên bản bàn cờ và luật đi; thấy đối thủ trực tuyến/ngoại tuyến; tự kết nối lại (kể cả khi API khởi động lại); mở phòng ở tab thứ hai không làm hai tab đá nhau	E2E 01, 02, 05; pytest
6	Khung chat giữa người chơi (video call)	Chat lưu trong PostgreSQL; video call WebRTC ngay cạnh khung chat (nhận / từ chối / tắt mic / tắt camera); máy không có camera tự chuyển sang gọi thoại và vẫn thấy hình đối phương	E2E 01, 04-call-matrix
7	Chơi với máy	Minimax + alpha-beta, 3 mức. Mức 3 thắng ngẫu nhiên và thắng mức 1 (cả hai màu); nước đi chậm nhất khoảng 0,15 giây	npm run check:ai, E2E 03

Luật cờ được kiểm hai nơi (trình duyệt và máy chủ) và đều cho đúng số nước đi chuẩn của cờ tướng từ thế khai cuộc: 44 / 1 920 / 79 666 / 3 290 240 (npm run check:rules, pytest).

Chạy đầy đủ bằng Docker

Cần Docker Desktop/Engine đang chạy và Docker Compose. Trong thư mục dự án:

cp .env.example .env        # Windows PowerShell: copy .env.example .env

Mở .env, điền POSTGRES_PASSWORD và JWT_SECRET (mỗi giá trị tối thiểu 32 ký tự, dùng chuỗi hex ngẫu nhiên). Tạo hai giá trị khác nhau bằng:

python -c "import secrets; print(secrets.token_hex(32)); print(secrets.token_hex(32))"

Sau đó:

docker compose up --build -d

Mở http://localhost:3000 (đúng localhost, không dùng 127.0.0.1: ALLOWED_ORIGINS mặc định chỉ có http://localhost:3000). PostgreSQL chỉ truy cập trong mạng Docker. Backend tạo schema lần đầu và tự thêm cột mới khi nâng cấp từ bản cũ. Dữ liệu giữ ở volume pgdata qua lần khởi động lại; không chạy docker compose down -v nếu muốn giữ dữ liệu. Web chỉ khởi động sau khi backend báo khỏe (/api/health).

Thử ngay: dùng hai trình duyệt (hoặc một cửa sổ riêng tư), đăng ký hai tài khoản, một người tạo phòng, người kia nhập mã hoặc mở liên kết mời. Một cửa sổ chỉ giữ được một tài khoản.

Next.js chuyển /api/* tới FastAPI (WebSocket đi qua cùng đường: /api/ws/{mã} với vé ngắn hạn dùng một lần lấy từ /api/ws-ticket).

BACKEND_URL, NEXT_PUBLIC_API_URL và NEXT_PUBLIC_SITE_URL được Next.js đọc lúc build, nên compose.yaml truyền chúng vào bước build (build.args). Đổi giá trị thì build lại: docker compose up --build -d.

Chạy phát triển không Docker

Cần Python 3.12+, Node 22.13+ và một PostgreSQL (hoặc SQLite cho thử nhanh).

1. Tạo database và user riêng, ví dụ kyvien.
2. Backend:

   python -m venv .venv && . .venv/bin/activate      # Windows: .venv\Scripts\Activate.ps1
   pip install -r backend/requirements.txt
   export DATABASE_URL=postgresql+psycopg://USER:PASSWORD@localhost:5432/kyvien   # hoặc sqlite:///dev.db
   export JWT_SECRET=$(python -c "import secrets; print(secrets.token_hex(32))")
   export ALLOWED_ORIGINS=http://localhost:3000 COOKIE_SECURE=false
   python -m uvicorn backend.main:app --port 8000 --workers 1
   

   (PowerShell: $env:DATABASE_URL='...'; $env:JWT_SECRET='...'; $env:ALLOWED_ORIGINS='http://localhost:3000'; $env:COOKIE_SECURE='false'.)
3. Frontend:

   corepack pnpm install --frozen-lockfile
   BACKEND_URL=http://127.0.0.1:8000 npx next dev      # PowerShell: $env:BACKEND_URL='http://127.0.0.1:8000'; npx next dev
   

Trong Docker, Dockerfile dùng next build và standalone output. Các script dev/build mặc định trong package dành cho bản Sites/Vinext; dùng dev:next, build:next, start:next khi chạy Next.js tiêu chuẩn.

Mời bạn vào phòng

Trong phòng, bấm Mời bằng hữu:

• Trong game — gõ tên đăng nhập của bạn bè → Gửi lời mời. Người nhận thấy thông báo trong vòng vài giây và bấm Tham gia ngay trên thông báo (hoặc trong mục Phòng chơi).
• Mạng xã hội — Chia sẻ liên kết phòng mở hộp chia sẻ của thiết bị (điện thoại có Zalo, Messenger…); trên máy tính dùng nút Facebook / Telegram / X / Email hoặc Sao chép lời mời rồi dán vào Zalo Web, Messenger… Nút Zalo riêng cần Official Account ID của Zalo nên không có sẵn.
• Mã phòng — gửi mã 6 ký tự; người kia chọn Vào phòng bằng mã. Liên kết https://tên-miền/?room=MÃ làm cùng việc; nếu người mở chưa đăng nhập, sau khi đăng nhập/đăng ký họ được đưa thẳng vào phòng.

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗