203 lines
8.7 KiB
Markdown
203 lines
8.7 KiB
Markdown
# 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.
|
|
|
|
## v1.3.0 - Classes Domain (Teacher Class Management)
|
|
**Date:** 2025-12-31
|
|
**Migration ID:** `0003_petite_newton_destine`
|
|
**Author:** Principal Database Architect
|
|
|
|
### 1. Summary
|
|
This release introduces the core schema for teacher class management: classes, enrollments, and schedules.
|
|
|
|
### 2. Changes
|
|
|
|
#### 2.1 Tables: Classes Domain
|
|
* **Action**: `CREATE TABLE`
|
|
* **Tables**:
|
|
* `classes`
|
|
* `class_enrollments`
|
|
* `class_schedule`
|
|
* **Reason**: Support teacher-owned classes, student enrollment lists, and weekly schedules.
|
|
|
|
#### 2.2 Enum: Enrollment Status
|
|
* **Action**: `ADD ENUM`
|
|
* **Enum**: `class_enrollment_status` = (`active`, `inactive`)
|
|
* **Reason**: Provide a stable status field for filtering active enrollments.
|
|
|
|
#### 2.3 Foreign Keys & Indexes
|
|
* **Action**: `ADD FOREIGN KEY`, `CREATE INDEX`
|
|
* **Key Relationships**:
|
|
* `classes.teacher_id` -> `users.id` (cascade delete)
|
|
* `class_enrollments.class_id` -> `classes.id` (cascade delete)
|
|
* `class_enrollments.student_id` -> `users.id` (cascade delete)
|
|
* `class_schedule.class_id` -> `classes.id` (cascade delete)
|
|
* **Indexes**:
|
|
* `classes_teacher_idx`, `classes_grade_idx`
|
|
* `class_enrollments_class_idx`, `class_enrollments_student_idx`
|
|
* `class_schedule_class_idx`, `class_schedule_class_day_idx`
|
|
|
|
### 3. Migration Strategy
|
|
* **Up**: Run standard Drizzle migration. Ensure `DATABASE_URL` points to the intended schema (e.g., `next_edu`).
|
|
* **Down**: Not provided. Dropping these tables is destructive and should be handled explicitly per environment.
|
|
|
|
### 4. Impact Analysis
|
|
* **Performance**: Indexes align with common query patterns (teacher listing, enrollment filtering, per-class schedule).
|
|
* **Data Integrity**: High. Foreign keys enforce ownership and membership integrity across teacher/classes/students.
|
|
|
|
## v1.4.0 - Classes Domain Enhancements (School Name & Subject Teachers)
|
|
**Date:** 2026-01-07
|
|
**Migration ID:** `0005_add_class_school_subject_teachers`
|
|
**Author:** Frontend/Fullstack Engineering
|
|
|
|
### 1. Summary
|
|
This release extends the Classes domain to support school-level sorting and per-subject teacher assignment defaults.
|
|
|
|
### 2. Changes
|
|
|
|
#### 2.1 Table: `classes`
|
|
* **Action**: `ADD COLUMN`
|
|
* **Field**: `school_name` (varchar(255), nullable)
|
|
* **Reason**: Enable sorting/grouping by school name, then grade, then class name.
|
|
|
|
#### 2.2 Table: `class_subject_teachers`
|
|
* **Action**: `CREATE TABLE`
|
|
* **Primary Key**: (`class_id`, `subject`)
|
|
* **Columns**:
|
|
* `class_id` (varchar(128), FK -> `classes.id`, cascade delete)
|
|
* `subject` (enum: `语文/数学/英语/美术/体育/科学/社会/音乐`)
|
|
* `teacher_id` (varchar(128), FK -> `users.id`, set null on delete)
|
|
* `created_at`, `updated_at`
|
|
* **Reason**: Maintain a stable default “subject list” per class while allowing admin/teacher to assign the actual teacher per subject.
|
|
|
|
### 3. Migration Strategy
|
|
* **Up**: Run standard Drizzle migration.
|
|
* **Down**: Not provided. Dropping assignment history is destructive.
|
|
|
|
### 4. Impact Analysis
|
|
* **Performance**: Minimal. Table is small (8 rows per class) and indexed by class/teacher.
|
|
* **Data Integrity**: High. Composite PK prevents duplicates per class/subject; FKs enforce referential integrity.
|
|
|
|
## v1.4.1 - Classes Domain Enhancements (School/Grade Normalization)
|
|
**Date:** 2026-01-07
|
|
**Migration ID:** `0006_faithful_king_bedlam`
|
|
**Author:** Frontend/Fullstack Engineering
|
|
|
|
### 1. Summary
|
|
This release extends the `classes` table to support normalized school and grade references.
|
|
|
|
### 2. Changes
|
|
|
|
#### 2.1 Table: `classes`
|
|
* **Action**: `ADD COLUMN`
|
|
* **Fields**:
|
|
* `school_id` (varchar(128), nullable)
|
|
* `grade_id` (varchar(128), nullable)
|
|
* **Reason**: Enable filtering and sorting by canonical school/grade entities instead of relying on free-text fields.
|
|
|
|
### 3. Migration Strategy
|
|
* **Up**: Run standard Drizzle migration.
|
|
* **Down**: Not provided. Dropping columns is destructive.
|
|
|
|
### 4. Impact Analysis
|
|
* **Performance**: Minimal. Indexing and joins can be added as usage evolves.
|
|
* **Data Integrity**: Medium. Existing rows remain valid (nullable fields); application-level validation can enforce consistency.
|
|
|
|
## v1.5.0 - Classes Domain Feature (Invitation Code)
|
|
**Date:** 2026-01-08
|
|
**Migration ID:** `0007_add_class_invitation_code`
|
|
**Author:** Frontend/Fullstack Engineering
|
|
|
|
### 1. Summary
|
|
This release introduces a 6-digit invitation code on `classes` to support join-by-code enrollment.
|
|
|
|
### 2. Changes
|
|
|
|
#### 2.1 Table: `classes`
|
|
* **Action**: `ADD COLUMN` + `ADD UNIQUE CONSTRAINT`
|
|
* **Field**: `invitation_code` (varchar(6), nullable, unique)
|
|
* **Reason**: Allow students to enroll into a class using a short code, while ensuring uniqueness across all classes.
|
|
|
|
### 3. Migration Strategy
|
|
* **Up**: Run standard Drizzle migration.
|
|
* **Backfill**: Optional. Existing classes can keep `NULL` or be populated via application-level actions.
|
|
* **Down**: Not provided. Removing a unique constraint/column is destructive.
|
|
|
|
### 4. Impact Analysis
|
|
* **Performance**: Minimal. Uniqueness is enforced via an index.
|
|
* **Data Integrity**: High. Unique constraint prevents code collisions and simplifies server-side enrollment checks.
|