# Tài liệu Cấu trúc Dữ liệu JSON (Game Data Schemas)

Tài liệu này định nghĩa cấu trúc dữ liệu JSON (dưới dạng TypeScript Interfaces) dùng để giao tiếp giữa Frontend (UI) và Backend (Database/API) cho 24 trò chơi trong Novastars Game Library. 

Việc nhóm các game có cấu trúc dữ liệu giống nhau sẽ giúp tối ưu việc thiết kế Database và tái sử dụng mã nguồn.

---

## NHÓM 1: Các Game Trắc nghiệm & Trả lời câu hỏi
**Bao gồm:** Quiz, Survival Quiz, Racing Game, Roleplay Quiz, Time Challenge.

Nhóm này sử dụng chung một `BaseQuestion` interface. Mỗi game có thể mở rộng (extend) cấu trúc này tùy theo nhu cầu.

```typescript
// 1. Cấu trúc câu hỏi chung (Base Question)
interface IBaseQuestion {
  id: string; // Unique ID của câu hỏi
  type: 'multiple_choice' | 'true_false' | 'text_input';
  questionText: string;
  questionMedia?: string; // URL Ảnh/Video (Tùy chọn)
  options: IAnswerOption[];
  explanation?: string; // Giải thích sau khi trả lời
  timeLimit?: number; // Giây (Dùng cho Survival Quiz/Time Challenge)
}

interface IAnswerOption {
  id: string;
  text: string;
  media?: string; 
  isCorrect: boolean; // Đúng hay Sai
}

// 2. Mở rộng cho Roleplay Quiz
interface IRoleplayQuestion extends IBaseQuestion {
  characterName: string; // Tên nhân vật ảo
  characterAvatar: string;
  moodState: 'neutral' | 'happy' | 'angry'; // Biểu cảm
}
```

---

## NHÓM 2: Các Game Ghép nối, Phân loại & Sắp xếp
**Bao gồm:** Drag & Drop Scene, Matching Pairs, Sorting into Group, Sorting into Right Order, Sentence Builder, Odd One Out.

Nhóm này xoay quanh các "Vật thể" (Draggables) và "Đích đến" (Dropzones).

```typescript
// 1. Dành cho Drag & Drop, Sorting into Group
interface ISortingGameData {
  zones: IDropZone[];
  items: IDraggableItem[];
}

interface IDropZone {
  id: string;
  title: string;
  targetType: string; // Ví dụ: "DONG_VAT"
  backgroundImage?: string;
}

interface IDraggableItem {
  id: string;
  content: string; // Text hoặc URL Hình ảnh
  itemType: string; // Phải match với targetType của DropZone
}

// 2. Dành cho Sorting into Right Order & Sentence Builder
interface IOrderGameData {
  items: IOrderedItem[];
}

interface IOrderedItem {
  id: string;
  content: string;
  correctOrder: number; // Vị trí chính xác (1, 2, 3...)
}

// 3. Dành cho Matching Pairs
interface IMatchingGameData {
  leftColumn: IMatchNode[];
  rightColumn: IMatchNode[];
}

interface IMatchNode {
  id: string;
  content: string;
  matchId: string; // ID của Node tương ứng ở cột đối diện
}
```

---

## NHÓM 3: Các Game Nhận diện Không gian (Bảng & Hình ảnh)
**Bao gồm:** Bingo, Crossword Puzzle, Word Search, Find the Differences, Hidden Objects.

Nhóm này thao tác với tọa độ (X, Y) trên lưới hoặc trên ảnh.

```typescript
// 1. Dành cho Crossword & Word Search (Lưới Ma trận)
interface IGridGameData {
  rows: number;
  columns: number;
  matrix: string[][]; // Ma trận chữ cái
  wordsToFind: IWordData[];
}

interface IWordData {
  word: string;
  hint: string;
  startPosition?: { row: number; col: number };
  direction?: 'horizontal' | 'vertical' | 'diagonal'; // Dành cho Crossword
}

// 2. Dành cho Find the Differences & Hidden Objects
interface IImageHotspotGameData {
  imageUrls: string[]; // Mảng 1 hoặc 2 ảnh
  hotspots: IHotspot[];
}

interface IHotspot {
  id: string;
  label?: string; // Tên vật thể (Dùng cho Hidden Objects)
  xPercent: number; // Tọa độ X (Tính theo % để responsive)
  yPercent: number; // Tọa độ Y (Tính theo % để responsive)
  radius: number; // Bán kính vùng chọn hợp lệ
}
```

---

## NHÓM 4: Các Game Nhập vai (Branching Narrative)
**Bao gồm:** Interactive Story.

```typescript
interface IInteractiveStoryData {
  title: string;
  nodes: { [key: string]: IStoryNode }; // Dictionary các Node
}

interface IStoryNode {
  id: string; // VD: "start", "run_away"
  text: string;
  backgroundUrl: string;
  choices?: IStoryChoice[]; // Tùy chọn (Rẽ nhánh)
  ending?: 'good' | 'bad' | 'neutral'; // Nếu có ending thì game over
}

interface IStoryChoice {
  text: string; // Nhãn của nút
  targetNodeId: string; // ID của Node tiếp theo
}
```

---

## NHÓM 5: Các Công cụ Tổ chức Lớp học (Quản trị & Bốc thăm)
**Bao gồm:** Lucky Wheel, Mystery Box, Whack-a-Mole, Catching Game.

```typescript
// 1. Dành cho Vòng Quay & Hộp Quà Bí Ẩn
interface IRandomizerData {
  items: IPrizeItem[];
}

interface IPrizeItem {
  id: string;
  label: string; // Tên giải thưởng hoặc Tên học sinh
  colorCode?: string; // Màu sắc ô (Hex)
  imageUrl?: string;
  weight?: number; // Tỉ lệ/Xác suất xuất hiện (Tùy chọn)
}

// 2. Dành cho Whack-a-Mole & Catching Game (Game Sinh vật/Vật thể rơi)
interface IActionGameData {
  durationSeconds: number; // Thời gian một vòng chơi
  entities: IGameEntity[];
}

interface IGameEntity {
  id: string;
  imageUrl: string;
  type: 'good' | 'bad'; // Good = Điểm cộng, Bad = Điểm trừ
  points: number; // Số điểm cộng/trừ
  spawnRateConfig?: number; // Độ hiếm
}
```

---

> **Lưu ý dành cho Developer:** 
> Tùy thuộc vào Framework (React/Vue/Angular) và Backend (NodeJS/Python/PHP), các biến có thể được đổi thành `snake_case` (VD: `target_type`) hoặc `camelCase` (VD: `targetType`). Hãy chốt Convention toàn hệ thống trước khi parse JSON từ API.