CICD/docs/architecture/002_exam_structure_migration.md

Database Schema Change Request: Exam Structure Support

1. Table: exams

Change

Add Column: structure

Details

• Type: JSON
• Nullable: TRUE (Default: NULL)

Reason

To support hierarchical exam structures (e.g., Sections/Groups containing Questions). The existing flat exam_questions table only supports a simple list of questions and is insufficient for complex exam layouts (e.g., "Part A: Reading", "Part B: Writing").

Before vs After

Before: exams table only stores metadata (title, description, etc.). Question ordering relies solely on exam_questions.order.

After: exams table includes structure column to store the full tree representation:

[
  { "id": "uuid-1", "type": "group", "title": "Section A", "children": [...] },
  { "id": "uuid-2", "type": "question", "questionId": "q1", "score": 10 }
]

Note: exam_questions table is retained for relational integrity and efficient querying of question usage, but the presentation order/structure is now driven by this new JSON column.

---

2. Table: questions_to_knowledge_points

Change

Rename Foreign Key Constraints

Details

• Rename constraint for question_id to q_kp_qid_fk
• Rename constraint for knowledge_point_id to q_kp_kpid_fk

Reason

The default generated foreign key names (e.g., questions_to_knowledge_points_knowledge_point_id_knowledge_points_id_fk) exceed the MySQL identifier length limit (64 characters), causing migration failures.

Before vs After

Before:

• FK Name: questions_to_knowledge_points_question_id_questions_id_fk (Too long)
• FK Name: questions_to_knowledge_points_knowledge_point_id_knowledge_points_id_fk (Too long)

After:

• FK Name: q_kp_qid_fk
• FK Name: q_kp_kpid_fk