# Database Seeding Strategy

**Status**: Implemented  
**Script Location**: [`scripts/seed.ts`](../../scripts/seed.ts)  
**Command**: `npm run db:seed`

---

## 1. Overview
The seed script is designed to populate the database with a **representative set of data** that covers all core business scenarios. It serves two purposes:
1.  **Development**: Provides a consistent baseline for developers.
2.  **Validation**: Verifies complex schema relationships (e.g., recursive trees, JSON structures).

## 2. Seed Data Topology

### 2.1 Identity & Access Management (IAM)
We strictly follow the RBAC model defined in `docs/architecture/001_database_schema_design.md`.

*   **Roles**:
    *   `admin`: System Administrator.
    *   `teacher`: Academic Instructor.
    *   `student`: Learner.
    *   `grade_head`: Head of Grade Year (Demonstrates multi-role capability).
*   **Users**:
    *   `admin@next-edu.com` (Role: Admin)
    *   `math@next-edu.com` (Role: Teacher + Grade Head)
    *   `alice@next-edu.com` (Role: Student)

### 2.2 Knowledge Graph
Generates a hierarchical structure to test recursive queries (`parentId`).
*   **Math** (Level 0)
    *   └── **Algebra** (Level 1)
        *   └── **Linear Equations** (Level 2)

### 2.3 Question Bank
Includes rich content and nested structures.
1.  **Simple Single Choice**: "What is 2 + 2?"
2.  **Composite Question (Reading Comprehension)**:
    *   **Parent**: A reading passage.
    *   **Child 1**: Single Choice question about the passage.
    *   **Child 2**: Open-ended text question.

### 2.4 Exams
Demonstrates the new **JSON Structure** field (`exams.structure`).
*   **Title**: "Algebra Mid-Term 2025"
*   **Structure**:
    ```json
    [
      {
        "type": "group",
        "title": "Part 1: Basics",
        "children": [{ "type": "question", "questionId": "...", "score": 10 }]
      },
      {
        "type": "group",
        "title": "Part 2: Reading",
        "children": [{ "type": "question", "questionId": "...", "score": 20 }]
      }
    ]
    ```

## 3. How to Run

### Prerequisites
Ensure your `.env` file contains a valid `DATABASE_URL`.

### Execution
Run the following command in the project root:

```bash
npm run db:seed
```

### Reset Behavior
**WARNING**: The script currently performs a **TRUNCATE** on all core tables before seeding. This ensures a clean state but will **WIPE EXISTING DATA**.