substitution manual mode

[Dasa122]

add a button for manual mode so you need to be able to select a teacher and a manual lesson time

[coderabbitai]

Coding Plan

Summary

• Extend the substitution table with an optional periodId column for storing time information directly (manual mode), following the movedLesson precedent
• Modify API schemas to accept either lessonIds (linked mode) or periodId (manual mode), with appropriate validation
• Add a checkbox toggle in the substitution dialog using the established conditional-field pattern from announcements-dialog.tsx
• Update conflict detection to check both linked-lesson periods and direct periodId references

Design Choices

Design Choice 1: What does "select a teacher" mean in manual mode?

Options Considered:

1. Select only the substitute teacher (who is covering the period)
2. Select both missing teacher and substitute teacher

Chosen Option: 1

Rationale: Manual mode is for ad-hoc coverage entries where there's no specific missing teacher—just "Teacher X is covering period Y on date Z."

Design Choice 2: Should manual substitutions be associated with a cohort/class?

Options Considered:

1. No cohort association—manual substitutions only show date, period, teacher, comment
2. Add an optional cohort selection field for manual mode

Chosen Option: 1

Rationale: Keep manual mode simple per the ticket scope. Manual substitutions display without cohort/subject/classroom info, with a "Manual" indicator to distinguish them.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Backend Schema and API Updates

Extend the database schema to support storing period information directly on substitutions (for manual mode), then update the API handlers to accept and validate manual-mode payloads.

Task 1: Add periodId Column to Substitution Table

Add a nullable foreign key column to store the period reference for manual substitutions.

• Create a new Drizzle migration in apps/chronos/src/database/migrations/ adding period_id column to the substitution table with FK reference to period.id
• Update the substitution table definition in apps/chronos/src/database/schema/timetable.ts to include the new periodId column as a nullable text field with foreign key reference
• Add a comment documenting that periodId is used for manual substitutions (when no lessons are linked)

Task 2: Update Substitution API Schemas

Modify the Zod validation schemas to support both linked mode (lessonIds required) and manual mode (periodId required).

• Update createSchema in apps/chronos/src/routes/timetable/substitution.ts to make lessonIds optional and add periodId as optional string
• Add validation logic: either lessonIds (min 1) OR periodId must be provided, but not both empty
• In manual mode, substituter should be required (not nullable) since there's no "cancelled" concept without lessons
• Update updateSchema similarly to allow modifying periodId

Task 3: Update Create/Update Handlers

Modify the route handlers to process manual substitutions correctly.

• In the createSubstitution handler, detect manual mode (periodId present, lessonIds empty/absent)
• For manual mode: store periodId directly on substitution record, skip lesson MTM insertions
• For linked mode: existing behavior unchanged
• Apply same logic to updateSubstitution handler
• Update checkTeacherSubstitutionConflict to also check the direct periodId on substitution records when detecting conflicts

Task 4: Update Response Enrichment

Ensure the API response includes period information for manual substitutions.

• In getAllSubstitutions, when a substitution has periodId but no linked lessons, fetch and include the period data in the response
• Add the period object to the response shape for manual substitutions (same structure as lesson period: id, period number, startTime, endTime)
• Update allSubstitutionsResponseSchema to reflect that lessons may be empty and period may be present at the substitution level

🤖 Prompt for AI agents

Implement backend schema and API changes to support a new "manual mode" for
substitutions, where period info is stored directly on the substitution record
instead of being derived from linked lessons.

**1. Database Schema (`apps/chronos/src/database/schema/timetable.ts`)**
- Add a nullable `periodId` text column to the `substitution` table definition
with a foreign key reference to `period.id`
- Add a code comment noting that `periodId` is used for manual substitutions
(when no lessons are linked)

**2. Drizzle Migration (`apps/chronos/src/database/migrations/`)**
- Create a new migration file that adds the `period_id` column to the
`substitution` table with the appropriate FK constraint to `period.id`

**3. API Schemas (`apps/chronos/src/routes/timetable/substitution.ts`)**
- Update `createSchema`: make `lessonIds` optional, add `periodId` as an
optional string, and add a refinement/superRefine ensuring either `lessonIds`
(min 1) or `periodId` is provided (but not both absent); in manual mode
(`periodId` present), `substituter` must be non-nullable
- Update `updateSchema` similarly to allow modifying `periodId`

**4. Route Handlers (`apps/chronos/src/routes/timetable/substitution.ts`)**
- In `createSubstitution`: detect manual mode when `periodId` is present and
`lessonIds` is empty/absent; for manual mode, store `periodId` on the
substitution record and skip all `substitutionLessonMTM` insertions; for linked
mode, preserve existing behavior
- Apply the same branching logic to `updateSubstitution`
- In `checkTeacherSubstitutionConflict`: extend conflict detection to also check
for conflicts against substitution records that have a direct `periodId` (not
just those derived from linked lessons)

**5. Response Enrichment (`getAllSubstitutions`)**
- When a substitution has `periodId` but no linked lessons, fetch and include
the period data in the response (id, period number, startTime, endTime)
- Update `allSubstitutionsResponseSchema` to reflect that `lessons` may be empty
and a top-level `period` field may be present on the substitution object

Phase 2: Frontend Dialog Modifications

Add a mode toggle to the substitution dialog and implement the conditional field rendering for manual mode.

Task 1: Add Manual Mode State and Toggle

Implement the mode switching UI using established patterns.

• In apps/iris/src/components/admin/substitution-dialog.tsx, add a useState boolean for isManualMode (default false)
• Add a Checkbox toggle control following the pattern from announcements-dialog.tsx
• When toggling modes, reset the form fields that are mode-specific (lessonIds, substituter for linked; periodId for manual)
• Disable mode switching when editing an existing substitution (mode determined by whether item has lessonIds or periodId)

Task 2: Add Period Fetching and Selection

Implement period selection for manual mode using the established Combobox pattern.

• Fetch periods using queryKeys.timetable.periods and api.timetable.periods.getAll.$get() (pattern from TimetableView)
• Add a Combobox for period selection, displayed only in manual mode
• Format period options as "Period N (HH:MM–HH:MM)" following the moved-lesson-dialog.tsx pattern
• Store the selected period ID in the form state

Task 3: Implement Conditional Field Rendering

Show different field sets based on the selected mode.

• Wrap the existing "missing teacher" combobox, lesson checkboxes, and substitute teacher combobox in a conditional block {!isManualMode && (...)}
• Add a manual mode field section {isManualMode && (...)} containing: date picker (shared), period combobox, substitute teacher combobox (required, no "cancelled" option)
• Update form validation: in manual mode, require date + periodId + substituter; in linked mode, existing validation
• The comment field remains visible in both modes

Task 4: Update Form Submission

Handle manual mode payloads in the submit handler.

• Modify the handleSave callback to construct the appropriate payload based on mode
• Manual mode payload: { date, periodId, substituter, comment } (no lessonIds)
• Linked mode payload: existing structure with lessonIds
• Update the parent component's mutation calls if payload shape detection is needed

🤖 Prompt for AI agents

Modify the substitution dialog in
`apps/iris/src/components/admin/substitution-dialog.tsx` to support a "manual
mode" toggle, with conditional field rendering and updated form submission.

**1. Manual Mode State and Toggle**
- Add a `useState<boolean>` named `isManualMode` defaulting to `false`
- Add a `Checkbox` toggle control following the pattern from
`announcements-dialog.tsx`
- On mode toggle, reset mode-specific form fields: clear `lessonIds` and
`substituter` when switching to manual; clear `periodId` when switching to
linked
- When editing an existing substitution, disable the mode toggle and derive the
initial mode from whether the item has `lessonIds` or `periodId`

**2. Period Fetching and Selection**
- Fetch periods using `queryKeys.timetable.periods` and
`api.timetable.periods.getAll.$get()`, following the pattern used in
TimetableView
- Add a `Combobox` for period selection, visible only when `isManualMode` is
true
- Format period options as `"Period N (HH:MM–HH:MM)"` following the
`moved-lesson-dialog.tsx` pattern
- Store the selected period ID in the form state

**3. Conditional Field Rendering**
- Wrap the existing "missing teacher" combobox, lesson checkboxes, and
substitute teacher combobox in `{!isManualMode && (...)}`
- Add a `{isManualMode && (...)}` section containing: the period combobox and a
substitute teacher combobox (required, no "cancelled" option)
- The date picker and comment field remain visible in both modes
- Update form validation: in manual mode require `date`, `periodId`, and
`substituter`; in linked mode use existing validation rules

**4. Form Submission (`handleSave`)**
- Branch the payload construction based on `isManualMode`
- Manual mode payload: `{ date, periodId, substituter, comment }` (omit
`lessonIds`)
- Linked mode payload: existing structure including `lessonIds`
- Update parent component mutation calls if payload shape detection is required

Phase 3: Frontend Display Updates

Update the substitution display components to properly render manual substitutions.

Task 1: Update Admin Substitutions Table

Show manual substitutions distinctly in the admin management view.

• In apps/iris/src/routes/_private/admin/timetable/substitutions.tsx, detect manual substitutions (empty lessons array, periodId present)
• For manual entries, display period info in the "Affected Lessons" column (e.g., "Manual: Period 3") with a distinctive badge
• Show "—" or similar in the "Cohorts" column for manual substitutions
• Ensure edit/delete actions work correctly for manual substitutions

Task 2: Update Public Substitutions Display

Handle manual substitutions in the public-facing view.

• In apps/iris/src/components/subs.tsx, add handling for substitutions with no lessons
• For manual substitutions, render a row showing: period time, substitute teacher, comment, with a "Manual" badge in place of subject/cohort
• Consider grouping manual substitutions separately or at the end of each date's section

Task 3: Add i18n Translation Keys

Add the necessary translation keys for new UI elements.

• Add keys to apps/iris/public/locales/en/translation.json under the substitution.* namespace: manualMode, manualModeDescription, selectPeriod, periodPlaceholder, manualBadge
• Add corresponding Hungarian translations to apps/iris/public/locales/hu/translation.json

🤖 Prompt for AI agents

Update the frontend display components to correctly render manual substitutions
(those with no linked lessons but a direct `periodId`), and add the required
i18n translation keys.

**1. Admin Substitutions Table
(`apps/iris/src/routes/_private/admin/timetable/substitutions.tsx`)**
- Detect manual substitutions by checking for an empty `lessons` array and a
present `periodId`
- In the "Affected Lessons" column, display period info (e.g., `"Manual: Period
3"`) with a distinctive badge for manual entries
- In the "Cohorts" column, show `"—"` or equivalent placeholder for manual
substitutions
- Verify that existing edit and delete actions function correctly for manual
substitution records

**2. Public Substitutions Display (`apps/iris/src/components/subs.tsx`)**
- Add a branch to handle substitutions with no linked lessons
- For manual substitutions, render a row with: period time, substitute teacher,
comment, and a `"Manual"` badge in place of subject/cohort info
- Consider grouping manual substitutions separately or appending them at the end
of each date's section

**3. i18n Translation Keys**
- In `apps/iris/public/locales/en/translation.json`, add the following keys
under the `substitution.*` namespace: `manualMode`, `manualModeDescription`,
`selectPeriod`, `periodPlaceholder`, `manualBadge`
- Add the corresponding Hungarian translations to
`apps/iris/public/locales/hu/translation.json`

Research

This is a full-stack feature spanning the chronos backend (Bun/Hono/Drizzle) and iris frontend (React/TanStack). Substitutions are currently stored in a substitution table linked to timetable lesson rows via a many-to-many join (substitutionLessonMTM). Time information is derived from linked lessons' periodId references. The movedLesson table provides a precedent for storing period references directly (startingPeriod FK to period). The frontend substitution dialog uses TanStack Form with conditional field rendering patterns established in announcements-dialog.tsx (checkbox-toggled field groups).

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement backend schema and API changes to support a new "manual mode" for
substitutions, where period info is stored directly on the substitution record
instead of being derived from linked lessons.

**1. Database Schema (`apps/chronos/src/database/schema/timetable.ts`)**
- Add a nullable `periodId` text column to the `substitution` table definition
with a foreign key reference to `period.id`
- Add a code comment noting that `periodId` is used for manual substitutions
(when no lessons are linked)

**2. Drizzle Migration (`apps/chronos/src/database/migrations/`)**
- Create a new migration file that adds the `period_id` column to the
`substitution` table with the appropriate FK constraint to `period.id`

**3. API Schemas (`apps/chronos/src/routes/timetable/substitution.ts`)**
- Update `createSchema`: make `lessonIds` optional, add `periodId` as an
optional string, and add a refinement/superRefine ensuring either `lessonIds`
(min 1) or `periodId` is provided (but not both absent); in manual mode
(`periodId` present), `substituter` must be non-nullable
- Update `updateSchema` similarly to allow modifying `periodId`

**4. Route Handlers (`apps/chronos/src/routes/timetable/substitution.ts`)**
- In `createSubstitution`: detect manual mode when `periodId` is present and
`lessonIds` is empty/absent; for manual mode, store `periodId` on the
substitution record and skip all `substitutionLessonMTM` insertions; for linked
mode, preserve existing behavior
- Apply the same branching logic to `updateSubstitution`
- In `checkTeacherSubstitutionConflict`: extend conflict detection to also check
for conflicts against substitution records that have a direct `periodId` (not
just those derived from linked lessons)

**5. Response Enrichment (`getAllSubstitutions`)**
- When a substitution has `periodId` but no linked lessons, fetch and include
the period data in the response (id, period number, startTime, endTime)
- Update `allSubstitutionsResponseSchema` to reflect that `lessons` may be empty
and a top-level `period` field may be present on the substitution object
===============================================================================

Task: 2

Modify the substitution dialog in
`apps/iris/src/components/admin/substitution-dialog.tsx` to support a "manual
mode" toggle, with conditional field rendering and updated form submission.

**1. Manual Mode State and Toggle**
- Add a `useState<boolean>` named `isManualMode` defaulting to `false`
- Add a `Checkbox` toggle control following the pattern from
`announcements-dialog.tsx`
- On mode toggle, reset mode-specific form fields: clear `lessonIds` and
`substituter` when switching to manual; clear `periodId` when switching to
linked
- When editing an existing substitution, disable the mode toggle and derive the
initial mode from whether the item has `lessonIds` or `periodId`

**2. Period Fetching and Selection**
- Fetch periods using `queryKeys.timetable.periods` and
`api.timetable.periods.getAll.$get()`, following the pattern used in
TimetableView
- Add a `Combobox` for period selection, visible only when `isManualMode` is
true
- Format period options as `"Period N (HH:MM–HH:MM)"` following the
`moved-lesson-dialog.tsx` pattern
- Store the selected period ID in the form state

**3. Conditional Field Rendering**
- Wrap the existing "missing teacher" combobox, lesson checkboxes, and
substitute teacher combobox in `{!isManualMode && (...)}`
- Add a `{isManualMode && (...)}` section containing: the period combobox and a
substitute teacher combobox (required, no "cancelled" option)
- The date picker and comment field remain visible in both modes
- Update form validation: in manual mode require `date`, `periodId`, and
`substituter`; in linked mode use existing validation rules

**4. Form Submission (`handleSave`)**
- Branch the payload construction based on `isManualMode`
- Manual mode payload: `{ date, periodId, substituter, comment }` (omit
`lessonIds`)
- Linked mode payload: existing structure including `lessonIds`
- Update parent component mutation calls if payload shape detection is required
===============================================================================

Task: 3

Update the frontend display components to correctly render manual substitutions
(those with no linked lessons but a direct `periodId`), and add the required
i18n translation keys.

**1. Admin Substitutions Table
(`apps/iris/src/routes/_private/admin/timetable/substitutions.tsx`)**
- Detect manual substitutions by checking for an empty `lessons` array and a
present `periodId`
- In the "Affected Lessons" column, display period info (e.g., `"Manual: Period
3"`) with a distinctive badge for manual entries
- In the "Cohorts" column, show `"—"` or equivalent placeholder for manual
substitutions
- Verify that existing edit and delete actions function correctly for manual
substitution records

**2. Public Substitutions Display (`apps/iris/src/components/subs.tsx`)**
- Add a branch to handle substitutions with no linked lessons
- For manual substitutions, render a row with: period time, substitute teacher,
comment, and a `"Manual"` badge in place of subject/cohort info
- Consider grouping manual substitutions separately or appending them at the end
of each date's section

**3. i18n Translation Keys**
- In `apps/iris/public/locales/en/translation.json`, add the following keys
under the `substitution.*` namespace: `manualMode`, `manualModeDescription`,
`selectPeriod`, `periodPlaceholder`, `manualBadge`
- Add the corresponding Hungarian translations to
`apps/iris/public/locales/hu/translation.json`

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!