# Tài Liệu Đặc Tả & Hướng Dẫn Triển Khai Hệ Thống GDHub --- ## 1. Giới Thiệu Dự Án (Project Overview) **GDHub (Game Design & Level Suite Portal)** là cổng điều phối trung tâm chuyên biệt dành cho đội ngũ Thiết kế Game (Game Designers), Quản trị viên (Admins) và Chuyên viên Phân tích Dữ liệu Game (Game Analysts). Hệ thống cung cấp không gian làm việc số thống nhất nhằm: - Tập hợp và quản lý danh mục toàn bộ các công cụ biên tập màn chơi (Level Editors), công cụ cân bằng game (Balancing Tools) và trình mô phỏng (Simulators). - Kiểm soát truy cập và phân quyền chi tiết (User-Tool Access Control) theo từng tài khoản chuyên trách. - Cung cấp cơ chế đăng nhập một lần (Single Sign-On - SSO) an toàn cho các công cụ con độc lập (Sub-tools) thông qua cơ chế vé ủy quyền dùng một lần (One-time Ticket). - Đảm bảo trải nghiệm người dùng cao cấp với giao diện hiện đại, hỗ trợ chế độ nền Sáng/Tối (Light/Dark Mode), công cụ đọc tài liệu kỹ thuật trực tiếp và hiệu ứng tương tác 3D. --- ## 2. Kiến Trúc Hệ Thống (System Architecture) Hệ thống được thiết kế theo mô hình tách biệt rõ ràng giữa Client và Server (Decoupled Client-Server Architecture): ``` ┌────────────────────────────────────────┐ │ GDHub Portal (Client) │ │ - Single Page Application (SPA) │ │ - Dynamic Glassmorphic Interface │ │ - Client-side Session State │ └───────────────────┬────────────────────┘ │ RESTful API / JSON (JWT Protected) │ ┌───────────────────▼────────────────────┐ │ GDHub Server (Backend) │ │ - Auth & Access Control Service │ │ - Single Sign-On (SSO) Ticket Issuer │ │ - Tool Registry Engine │ └───────────────────┬────────────────────┘ │ Dual-Driver Database Layer │ ┌───────────────────▼────────────────────┐ │ Database Storage Engine │ │ - SQLite (Môi trường phát triển) │ │ - PostgreSQL (Môi trường Production) │ └────────────────────────────────────────┘ ``` ### 2.1. Phân Tầng Ứng Dụng 1. **Tầng Giao Diện Người Dùng (Frontend Portal)**: - Xây dựng dưới dạng Single Page Application (SPA) tối ưu tốc độ tải trang. - Cơ chế kiểm soát phiên khởi động thông minh (Zero-flash Boot Mechanism) ngăn chặn hiện tượng nhấp nháy giao diện khi tải lại trang. - Tương tác với backend thông qua HTTP REST API chuẩn hóa. 2. **Tầng Máy Chủ Dịch Vụ (Backend Core)**: - Đóng vai trò máy chủ trung tâm xác thực người dùng và cấp phát mã truy cập JWT. - Xử lý phân quyền danh mục công cụ động, không phụ thuộc vào việc cấu hình cứng trên frontend. - Quản lý vòng đời vé đăng nhập một lần (SSO Tickets) với thời gian hết hạn cực ngắn (60 giây) và cơ chế tự hủy sau một lần xác thực. 3. **Tầng Cơ Sở Dữ Liệu (Database Layer)**: - Thiết kế lược đồ quan hệ chuẩn hóa (4 bảng dữ liệu cốt lõi: Tài khoản người dùng, Danh mục công cụ, Bảng ánh xạ phân quyền, Bảng lưu trữ vé SSO). - Tương thích song song hai hệ thống cơ sở dữ liệu: SQLite cho môi trường phát triển cục bộ (Zero-config) và PostgreSQL cho môi trường triển khai thực tế (Production). --- ## 3. Luồng Hoạt Động & Cơ Chế Bảo Mật (Core Workflows & Security) ### 3.1. Quy Trình Xác Thực Người Dùng (Authentication Lifecycle) ``` [Người Dùng] ────(1) Nhập Email & Mật khẩu────► [GDHub Portal] │ (2) Gửi yêu cầu đăng nhập │ ▼ [GDHub Backend API] │ (3) Xác thực bcrypt hash & Trạng thái Active │ (4) Trả về JWT Token + Thông tin User │ ▼ [Người Dùng] ◄───(5) Mở khóa Portal Workspace ── [GDHub Portal] ``` - **Mã hóa mật khẩu**: Sử dụng giải thuật băm một chiều `bcrypt` với độ phức tạp cao, ngăn ngừa nguy cơ rò rỉ dữ liệu. - **Quản lý Phiên làm việc**: Token JWT được lưu trữ an toàn. Người dùng có tùy chọn duy trì đăng nhập (Persistent Session) hoặc chỉ lưu trong phiên làm việc hiện tại của trình duyệt. - **Xác thực trạng thái khởi động**: Trình duyệt kiểm tra tính hợp lệ của token với máy chủ trước khi dỡ bỏ màn hình khởi tạo (Splash Screen). ### 3.2. Quy Trình Cấp Quyền & Truy Cập Công Cụ (User-Tool Access Control) - **Nguyên tắc Phân quyền (Whitelist Approach)**: - Tài khoản Quản trị viên (`ADMIN`): Có toàn quyền truy cập, chỉnh sửa, thêm/xóa công cụ và phân phối quyền cho người dùng khác. - Tài khoản Người dùng thông thường: Chỉ nhìn thấy và tương tác được với những công cụ đã được Quản trị viên cấp phép rõ ràng trong bảng danh mục quyền. - **Đồng bộ hóa tức thì (Real-time Sync)**: Mọi thay đổi về quyền trên bảng điều khiển Admin sẽ được phản hồi và cập nhật ngay lập tức mà không cần người dùng phải đăng xuất. ### 3.3. Cơ Chế Đăng Nhập Một Lần Cho Sub-Tools (SSO Launch Flow) Để đảm bảo các công cụ làm việc độc lập (Sub-tools) không bị truy cập trái phép qua đường dẫn trực tiếp, quy trình xác thực vé được thực hiện: ``` [GDHub Portal] ───(1) Yêu cầu cấp SSO Ticket (kèm Tool ID & JWT)───► [GDHub Backend] │ │ │◄──(2) Trả về SSO Ticket (Chuỗi ngẫu nhiên bảo mật 60s)─────────────┘ │ (3) Chuyển hướng kèm Ticket sang Sub-Tool │ ▼ [Sub-Tool Editor] ───(4) Gửi Ticket về Backend kiểm tra────────────► [GDHub Backend] │ │ │◄──(5) Phản hồi Hợp lệ & Đánh dấu Ticket đã sử dụng (Consumed)──────┘ │ (6) Cho phép Game Designer sử dụng Editor ``` --- ## 4. Các Chức Năng Chính Của Hệ Thống ### 4.1. Dành Cho Game Designers & Analysts - **Bảng Tổng Quan Công Cụ (Tool Catalog)**: Giao diện trực quan phân loại các editor theo nhóm chức năng (Grid Puzzle, 3D & Sorting, Word & Text, AI & Utils). - **Tìm Kiếm & Lọc Nhanh**: Tìm kiếm công cụ theo tên, thẻ mô tả hoặc phím tắt nhanh trên bàn phím. - **Tùy Biến Chế Độ Xem**: Hỗ trợ linh hoạt chuyển đổi giữa dạng lưới (Grid View) và dạng danh sách (List View). - **Yêu Thích & Ghim Công Cụ**: Đánh dấu các editor thường xuyên sử dụng lên vị trí ưu tiên. - **Trình Đọc Tài Liệu Tích Hợp (Doc Reader)**: Xem trực tiếp các tài liệu đặc tả kỹ thuật, chuẩn phân loại dữ liệu game và hướng dẫn tích hợp ngay trên màn hình mà không cần tải về thủ công. ### 4.2. Dành Cho Quản Trị Viên (Administrators) - **Quản Lý Người Dùng**: Tạo mới tài khoản, kích hoạt/vô hiệu hóa tài khoản, đặt lại mật khẩu và chuyển đổi quyền Admin. - **Cấp Phát Quyền Truy Cập (Tool Permissions)**: Bảng ma trận trực quan cho phép tick chọn công cụ được phép sử dụng cho từng nhân sự. - **Đăng Ký Công Cụ Mới (Tool Registry)**: Đăng ký thêm các Level Editor hoặc dịch vụ mới vào hệ thống trực tiếp qua giao diện quản trị mà không cần lập trình hay sửa đổi mã nguồn. - **Sao Lưu & Phục Hồi Dữ Liệu**: Xuất/nhập cấu hình danh mục công cụ phục vụ công tác backup định kỳ. --- ## 5. Hướng Dẫn Triển Khai Hệ Thống (Deployment & Operations) ### 5.1. Yêu Cầu Môi Trường (System Prerequisites) - **Node.js**: Phiên bản 20.x trở lên (Khuyến nghị phiên bản 22.x LTS để tận dụng bộ điều khiển cơ sở dữ liệu tích hợp). - **Trình quản lý gói**: `npm` hoặc `yarn`. - **Cơ sở dữ liệu**: - _Môi trường phát triển_: Sử dụng cơ sở dữ liệu nhúng sẵn có, không cần cài đặt phần mềm bổ sung. - _Môi trường Production_: Máy chủ cơ sở dữ liệu PostgreSQL 14+. --- ### 5.2. Các Bước Triển Khai Phía Máy Chủ (Backend Deployment) #### Bước 1: Khởi tạo thư viện phụ thuộc Tiến hành cài đặt toàn bộ các gói thư viện cần thiết cho máy chủ dịch vụ. #### Bước 2: Thiết lập Biến Môi Trường (Environment Variables) Tạo tệp cấu hình môi trường dựa trên bản mẫu với các thông số bắt buộc: - `PORT`: Cổng mạng lắng nghe dịch vụ (Mặc định: 4000). - `NODE_ENV`: Chế độ môi trường (`development` hoặc `production`). - `JWT_SECRET`: Chuỗi khóa bí mật dùng để ký và xác thực token JWT (Bắt buộc dùng chuỗi ngẫu nhiên dài trên 32 ký tự đối với production). - `JWT_EXPIRES_IN`: Thời hạn sống của mã token (Ví dụ: `7d`). - `DATABASE_URL`: Đường dẫn kết nối PostgreSQL (Nếu để trống, hệ thống sẽ tự động chuyển sang cơ chế cơ sở dữ liệu nhúng cục bộ). - `CORS_ORIGIN`: Danh sách các tên miền frontend được phép gửi yêu cầu tới máy chủ (Ví dụ: `https://gdhub.yourdomain.com`). - `ADMIN_INITIAL_PASSWORD`: Mật khẩu khởi tạo cho tài khoản quản trị viên tối cao. #### Bước 3: Khởi tạo và Đồng bộ Lược đồ Dữ liệu (Database Migration & Seeding) - Thực thi tác vụ tạo cấu trúc bảng (`Migration`) để thiết lập các bảng quan hệ. - Thực thi tác vụ nạp dữ liệu khởi nguyên (`Seeding`) để tạo sẵn tài khoản quản trị viên mặc định và danh mục các công cụ biên tập cốt lõi. #### Bước 4: Khởi chạy Dịch vụ Backend - Sử dụng các trình quản lý tiến trình nền (Process Manager như `pm2`) hoặc đóng gói dưới dạng Container (Docker) để duy trì hoạt động 24/7 và tự động khởi động lại khi có sự cố. --- ### 5.3. Các Bước Triển Khai Phía Giao Diện (Frontend Deployment) #### Bước 1: Cài đặt và Đóng gói (Build Process) - Cài đặt các gói phụ thuộc giao diện. - Thực thi tiến trình đóng gói tĩnh (Static Assets Compilation) để tối ưu hóa mã nguồn, nén CSS và tối giản hóa các tệp kịch bản giao diện thành bộ tệp tĩnh tối ưu. #### Bước 2: Cấu hình Máy chủ Phân phối Tĩnh (Web Server / CDN Hosting) - Phân phối các tệp tĩnh lên máy chủ web (Nginx / Apache / Caddy) hoặc các nền tảng đám mây chuyên dụng (Vercel / Cloudflare Pages / Render / AWS S3 + CloudFront). - Cấu hình điều hướng Single Page Application (Rewrite Rule): Mọi yêu cầu truy cập không trỏ trực tiếp tới tệp tĩnh cần được chuyển hướng về trang gốc để frontend tự xử lý định tuyến. - Cấu hình bộ chuyển tiếp ngược (Reverse Proxy): Thiết lập chuyển tiếp các yêu cầu có tiền tố đường dẫn API về cụm máy chủ Backend. --- ### 5.4. Kiểm Tra Sau Triển Khai (Post-Deployment Verification) Sau khi hoàn tất quá trình thiết lập, thực hiện các bước kiểm tra tiêu chuẩn: 1. **Kiểm tra trạng thái máy chủ (Health Check)**: - Gửi yêu cầu kiểm tra tới cổng API trạng thái của máy chủ để xác nhận trạng thái hoạt động tốt và loại driver cơ sở dữ liệu đang liên kết. 2. **Kiểm tra đăng nhập Quản trị viên**: - Sử dụng tài khoản quản trị khởi tạo để truy cập vào hệ thống. - Xác nhận menu Admin Control Panel hiển thị đầy đủ các mục: Người dùng, Danh mục công cụ, Phân quyền. 3. **Kiểm tra phân quyền tài khoản thành viên**: - Đăng nhập với tài khoản thành viên thông thường. - Xác minh các công cụ không được phân quyền sẽ không xuất hiện trên giao diện. 4. **Kiểm tra liên kết công cụ con (Sub-tool SSO Launch)**: - Nhấn mở một công cụ biên tập game bất kỳ từ danh sách. - Xác nhận vé SSO được tạo, đính kèm vào đường dẫn và công cụ con nhận diện thành công quyền truy cập mà không yêu cầu đăng nhập lại. --- ## 6. Kế Hoạch Vận Hành & Bảo Trì (Operations & Maintenance) - **Sao lưu Cơ sở dữ liệu (Database Backup)**: - Thiết lập lịch sao lưu tự động định kỳ hàng ngày (Daily Automated Dump) đối với cơ sở dữ liệu Production. - **Giám sát Hiệu năng & Nhật ký Lỗi (Logging & Monitoring)**: - Thu thập nhật ký truy cập (Access Logs) và nhật ký lỗi (Error Logs) của máy chủ để phát hiện sớm các lượt yêu cầu bất thường hoặc lỗi xác thực vé SSO. - **Thu hồi Quyền & Khóa Tài khoản**: - Khi có sự thay đổi nhân sự trong studio, Quản trị viên cần thực hiện vô hiệu hóa tài khoản ngay trên Admin Panel để tự động hủy bỏ mọi phiên làm việc và quyền truy cập công cụ liên quan.