Module Update

docs/db/schema-changelog.md

@@ -0,0 +1,39 @@
+# Database Schema Changelog
+
+## v1.1.0 - Exam Structure & Performance Optimization
+**Date:** 2025-12-29  
+**Migration ID:** `0001_flawless_texas_twister`  
+**Author:** Principal Database Architect
+
+### 1. Summary
+This release introduces support for hierarchical exam structures (Sectioning/Grouping) and optimizes database constraint naming for better compatibility with MySQL environments.
+
+### 2. Changes
+
+#### 2.1 Table: `exams`
+*   **Action**: `ADD COLUMN`
+*   **Field**: `structure` (JSON)
+*   **Reason**: To support nested exam layouts (e.g., "Part I: Listening", "Section A").
+    *   *Architecture Note*: This JSON field is strictly for **Presentation Layer** ordering and grouping. The `exam_questions` table remains the **Source of Truth** for relational integrity and scoring logic.
+    *   **Schema Definition**:
+        ```typescript
+        type ExamStructure = Array<
+           | { type: 'group', title: string, children: ExamStructure }
+           | { type: 'question', questionId: string, score: number }
+        >
+        ```
+
+#### 2.2 Table: `questions_to_knowledge_points`
+*   **Action**: `RENAME FOREIGN KEY`
+*   **Details**:
+    *   Old: `questions_to_knowledge_points_question_id_questions_id_fk` -> New: `q_kp_qid_fk`
+    *   Old: `questions_to_knowledge_points_knowledge_point_id_knowledge_points_id_fk` -> New: `q_kp_kpid_fk`
+*   **Reason**: Previous names exceeded MySQL's 64-character identifier limit, causing potential migration failures in production environments.
+
+### 3. Migration Strategy
+*   **Up**: Run standard Drizzle migration. The script includes `ALTER TABLE ... DROP FOREIGN KEY` followed by `ADD CONSTRAINT`.
+*   **Down**: Revert `structure` column. Note that FK names can be kept short as they are implementation details.
+
+### 4. Impact Analysis
+*   **Performance**: Negligible. JSON parsing is done client-side or at application layer.
+*   **Data Integrity**: High. Existing data is unaffected. New `structure` field defaults to `NULL`.

docs/db/seed-data.md

@@ -0,0 +1,75 @@
+# 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**.