CICD/docs/db/schema-changelog.md

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:

    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.