# Database Schema Changelog

## v1.1.0 - Exam Structure Support
**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).

### 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 }
        >
        ```

### 3. Migration Strategy
*   **Up**: Run standard Drizzle migration.
*   **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`.

## v1.2.0 - Homework Module Tables & FK Name Hardening
**Date:** 2025-12-31  
**Migration ID:** `0002_equal_wolfpack`  
**Author:** Principal Database Architect

### 1. Summary
This release introduces homework-related tables and hardens foreign key names to avoid exceeding MySQL identifier length limits (MySQL 64-char constraint names).

### 2. Changes

#### 2.1 Tables: Homework Domain
*   **Action**: `CREATE TABLE`
*   **Tables**:
    *   `homework_assignments`
    *   `homework_assignment_questions`
    *   `homework_assignment_targets`
    *   `homework_submissions`
    *   `homework_answers`
*   **Reason**: Support assignment lifecycle, targeting, submissions, and per-question grading.

#### 2.2 Foreign Keys: Homework Domain (Name Hardening)
*   **Action**: `ADD FOREIGN KEY` (with short constraint names)
*   **Details**:
    *   `homework_assignments`: `hw_asg_exam_fk`, `hw_asg_creator_fk`
    *   `homework_assignment_questions`: `hw_aq_a_fk`, `hw_aq_q_fk`
    *   `homework_assignment_targets`: `hw_at_a_fk`, `hw_at_s_fk`
    *   `homework_submissions`: `hw_sub_a_fk`, `hw_sub_student_fk`
    *   `homework_answers`: `hw_ans_sub_fk`, `hw_ans_q_fk`
*   **Reason**: Default generated FK names can exceed 64 characters in MySQL and fail during migration.

#### 2.3 Table: `questions_to_knowledge_points`
*   **Action**: `RENAME FOREIGN KEY` (implemented as drop + add)
*   **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 migration is resilient whether the legacy FK names exist or have already been renamed.
*   **Down**: Not provided. Removing homework tables and FKs is destructive and should be handled explicitly per environment.

### 4. Impact Analysis
*   **Performance**: Minimal. New indexes are scoped to common homework access patterns.
*   **Data Integrity**: High. Foreign keys enforce referential integrity for homework workflow.