# Academic Periods CRUD Build Plan

## Goal

Add full academic period lifecycle management to the settings page and backend, including safe archive and hard-delete behavior, recurrence spillover blockers, and a UI restructuring where `Perioden` becomes the first sub-tab under `Akademischer Kalender`.

## Frontend Design Rules

All UI implementation for this build must follow the project-wide frontend design rules:

→ **[FRONTEND_DESIGN_RULES.md](FRONTEND_DESIGN_RULES.md)**

Key points relevant to this build:
- Syncfusion Material3 components are the default for every UI element
- Use `DialogComponent` for all confirmations — never `window.confirm()`
- Follow the established card structure, button variants, badge colors, and tab patterns
- German strings only in all user-facing text
- No Tailwind classes

## Agreed Rules

### Permissions

- Create: admin or higher
- Edit: admin or higher
- Archive: admin or higher
- Restore: admin or higher
- Hard delete: admin or higher
- Activate: admin or higher
- Editors do not activate periods by default because activation changes global system state

### Lifecycle

- Active: exactly one period at a time
- Inactive: saved period, not currently active
- Archived: retired period, hidden from normal operational selection
- Deleted: physically removed only when delete preconditions are satisfied

### Validation

- `name` is required, trimmed, and unique among non-archived periods
- `startDate` must be less than or equal to `endDate`
- `periodType` must be one of `schuljahr`, `semester`, `trimester`
- Overlaps are disallowed within the same `periodType`
- Overlaps across different `periodType` values are allowed
- Exactly one period may be active at a time

### Archive Rules

- Active periods cannot be archived
- A period cannot be archived if it still has operational dependencies
- Operational dependencies include recurring master events assigned to that period that still generate current or future occurrences

### Restore Rules

- Archived periods can be restored by admin or higher
- Restored periods return as inactive by default

### Hard Delete Rules

- Only archived and inactive periods can be hard-deleted
- Hard delete is blocked if linked events exist
- Hard delete is blocked if linked media exist
- Hard delete is blocked if recurring master events assigned to the period still have current or future scheduling relevance

### Recurrence Spillover Rule

- If a recurring master event belongs to an older period but still creates occurrences in the current or future timeframe, that older period is not eligible for archive or hard delete
- Admin must resolve the recurrence by ending, splitting, or reassigning the series before the period can be retired or deleted

## Build-Oriented Task Plan

### Phase 1: Lock The Contract

Files:

- `server/routes/academic_periods.py`
- `models/models.py`
- `dashboard/src/settings.tsx`

Work:

- Freeze lifecycle rules, validation rules, and blocker rules
- Freeze the settings tab order so `Perioden` comes before `Import & Liste`
- Confirm response shape for new endpoints

Deliverable:

- Stable implementation contract for backend and frontend work

### Phase 2: Extend The Data Model

Files:

- `models/models.py`

Work:

- Add archive lifecycle fields to academic periods
- Recommended fields: `is_archived`, `archived_at`, `archived_by`

Deliverable:

- Academic periods can be retired safely and restored later

### Phase 3: Add The Database Migration

Files:

- `server/alembic.ini`
- `server/alembic/`
- `server/initialize_database.py`

Work:

- Add Alembic migration for archive-related fields and any supporting indexes
- Ensure existing periods default to non-archived

Deliverable:

- Schema upgrade path for current installations

### Phase 4: Expand The Backend API

Files:

- `server/routes/academic_periods.py`

Work:

- Implement full lifecycle endpoints:
  - `GET /api/academic_periods`
  - `GET /api/academic_periods/:id`
  - `POST /api/academic_periods`
  - `PUT /api/academic_periods/:id`
  - `POST /api/academic_periods/:id/activate`
  - `POST /api/academic_periods/:id/archive`
  - `POST /api/academic_periods/:id/restore`
  - `GET /api/academic_periods/:id/usage`
  - `DELETE /api/academic_periods/:id`

Deliverable:

- Academic periods become a fully managed backend resource

### Phase 5: Add Backend Validation And Guardrails

Files:

- `server/routes/academic_periods.py`
- `models/models.py`

Work:

- Enforce required fields, type checks, date checks, overlap checks, and one-active-period behavior
- Block archive and delete when dependency rules fail

Deliverable:

- Backend owns all business-critical safeguards

### Phase 6: Implement Recurrence Spillover Detection

Files:

- `server/routes/academic_periods.py`
- `server/routes/events.py`
- `models/models.py`

Work:

- Detect recurring master events assigned to a period that still generate present or future occurrences
- Treat them as blockers for archive and hard delete

Deliverable:

- Old periods cannot be retired while they still affect the active schedule

### Phase 7: Normalize API Serialization

Files:

- `server/routes/academic_periods.py`
- `server/serializers.py`

Work:

- Return academic period responses in camelCase consistently with the rest of the API

Deliverable:

- Frontend receives normalized API payloads without special-case mapping

### Phase 8: Expand The Frontend API Client

Files:

- `dashboard/src/apiAcademicPeriods.ts`

Work:

- Add frontend client methods for create, update, activate, archive, restore, usage lookup, and hard delete

Deliverable:

- The settings page can manage academic periods through one dedicated API module

### Phase 9: Reorder The Akademischer Kalender Sub-Tabs

Files:

- `dashboard/src/settings.tsx`

Work:

- Move `Perioden` to the first sub-tab
- Move `Import & Liste` to the second sub-tab
- Preserve controlled tab state behavior

Deliverable:

- The settings flow reflects setup before import work

### Phase 10: Replace The Current Period Selector With A Management UI

Files:

- `dashboard/src/settings.tsx`

Work:

- Replace the selector-only period card with a proper management surface
- Show period metadata, active state, archived state, and available actions

Deliverable:

- The periods tab becomes a real administration UI

### Phase 11: Add Create And Edit Flows

Files:

- `dashboard/src/settings.tsx`

Work:

- Add create and edit dialogs or form panels
- Validate input before save and surface backend errors clearly

Deliverable:

- Admins can maintain periods directly in settings

### Phase 12: Add Archive, Restore, And Hard Delete UX

Files:

- `dashboard/src/settings.tsx`

Work:

- Fetch usage or preflight data before destructive actions
- Show exact blockers for linked events, linked media, and recurrence spillover
- Use explicit confirmation dialogs for archive and hard delete

Deliverable:

- Destructive actions are safe and understandable

### Phase 13: Add Archived Visibility Controls

Files:

- `dashboard/src/settings.tsx`

Work:

- Hide archived periods by default or group them behind a toggle

Deliverable:

- Normal operational periods stay easy to manage while retired periods remain accessible

### Phase 14: Add Backend Tests

Files:

- Backend academic period test targets to be identified during implementation

Work:

- Cover create, edit, activate, archive, restore, hard delete, overlap rejection, dependency blockers, and recurrence spillover blockers

Deliverable:

- Lifecycle rules are regression-safe

### Phase 15: Add Frontend Verification

Files:

- `dashboard/src/settings.tsx`
- Frontend test targets to be identified during implementation

Work:

- Verify sub-tab order, CRUD refresh behavior, blocked action messaging, and activation behavior

Deliverable:

- Settings UX remains stable after the management upgrade

### Phase 16: Update Documentation

Files:

- `.github/copilot-instructions.md`
- `README.md`
- `TECH-CHANGELOG.md`

Work:

- Document academic period lifecycle behavior, blocker rules, and updated settings tab order as appropriate

Deliverable:

- Repo guidance stays aligned with implemented behavior

## Suggested Build Sequence

1. Freeze rules and response shape
2. Change the model
3. Add the migration
4. Build backend endpoints
5. Add blocker logic and recurrence checks
6. Expand the frontend API client
7. Reorder sub-tabs
8. Build period management UI
9. Add destructive-action preflight UX
10. Add tests
11. Update documentation

## Recommended Delivery Split

1. Backend foundation
   - Model
   - Migration
   - Routes
   - Validation
   - Blocker logic

2. Frontend management
   - API client
   - Tab reorder
   - Management UI
   - Dialogs
   - Usage messaging

3. Verification and docs
   - Tests
   - Documentation