roosterwijs/README.md

# Roosterwijs

Modulair, flexibel roostersysteem voor het speciaal onderwijs (uil-logo: een
uil staat voor wijsheid → *Roosterwijs*). Zie `PLAN.md` voor de visie en de
fasering, en `DEPLOY.md` voor draaien op een test-/productieserver.

Status: **Fase 0–4** klaar. Fase 0 (plugin-framework), Fase 1 (personen,
groepen, subgroepen, functies), Fase 2 (schooljaarkalender + roosterblokken),
Fase 3 (afwezigheid, uitzonderingen, effectief weekrooster) en Fase 4
(**conflictdetectie**: dubbele inzet van begeleider/leerling en locatiebotsingen).

Het Rooster-scherm is een **weekweergave met drag-and-drop** (muis én touch) en
een **touch-vriendelijk** ontwerp; vrije dagen, afwezigheid en uitzonderingen
worden automatisch verwerkt. Het Rooster heeft tabs **Weekrooster / Conflicten /
Schooljaar / Instellingen** (tijdsloten, activiteiten en locaties beheer je daar,
en het schooljaar + de kalender voer je in onder de Schooljaar-tab, zodat het menu
rustiger is). De zijbalk groepeert items onder inklapbare submenu's (Personen,
Groepen) en heeft onderaan een subtiel **Instellingen**-blok met Gebruikers en
Modulebeheer.

Er zijn twee rooster-schermen: **Rooster** (alleen-lezen weergave, om te bekijken
en af te drukken) en **Roostermaker** (de aanpasser met drag-and-drop, tabs en
conflictdetectie). In de Roostermaker open je een blok met een **klik** om het te
bewerken (vak, locatie, doelgroep, begeleiders, opmerking) of te **kopiëren** naar
andere tijden/dagen. De tab **Indeling** verdeelt een hoofdgroep (of leerplein)
kolomsgewijs in subgroepen, met per subgroep de vakken en de verantwoordelijke(n),
en je kunt er direct subgroepen toevoegen. Beide schermen hebben een **scope-filter** (alles / per klas /
per leerplein / per leerling / per personeel); de module **Printen/Exporteren**
voegt — als die aanstaat — een subtiele **Afdrukken**-knop toe die het (gefilterde)
weekrooster printvriendelijk afdrukt of als PDF bewaart.

Optionele module **Multi-user & toegang**: een **Gebruikers**-scherm (onder
Instellingen, alleen voor beheerders) om inloggers te beheren — gebruikersnaam,
wachtwoord, rol (beheerder/medewerker/ouder/leerling), koppeling aan een persoon,
en actief/beheerder-status.

Optionele module **Leerplein**: koppelt subgroepen aan groepen en bundelt
groepen, subgroepen én losse leerlingen onder een overkoepelend leerplein.
Optionele module **Stage**: interne en externe stages van leerlingen — beide met
een begeleider, een interne stage ook met een ruimte. Beide modules zijn aan/uit
te zetten via Modulebeheer.

**Fase 5 (recent)**: vaste tijden zijn per groep aan te passen (een tijdslot
zonder groep = algemene tijd, met groep = afwijkende tijd). Personeel en
leerlingen hebben gescheiden invoerschermen. Bij personeel koppel je direct
functie(s), stamgroep/plein en de vakken die ze kunnen geven; een leerkracht
krijgt de theorievakken automatisch. Bij een leerling leg je groep en
geboortedatum vast.

## Wat er nu staat

- **Backend** (`backend/`) — Django + Django REST Framework.
  - `plugins/` — het plugin-framework: een moduleregister, opslag van de
    aan/uit-status per module en een beheer-API.
  - `core/` — de kern (altijd actief). **Fase 1**: modellen Persoon, Groep en
    Subgroep met een volledige CRUD-API. Roosterblokken en kalender volgen in
    fase 2.
  - `modules/printing/` en `modules/accounts/` — twee voorbeeldmodules die
    zich bij opstarten aanmelden bij het register.
- **Frontend** (`frontend/`) — React (Vite). Zijbalk met Roosterwijs-logo die
  alleen menu's toont van ingeschakelde modules, beheerschermen voor
  **Personen**, **Groepen** en **Subgroepen**, en een scherm **Modulebeheer**.

## Hoe modulariteit werkt (het verkoopargument)

1. Een module is een gewone Django-app met een `apps.py` die in `ready()` een
   `ModuleSpec` registreert (naam, beschrijving, versie, afhankelijkheden en
   menu-items).
2. Het register weet wélke modules bestaan; de database onthoudt of ze **aan**
   staan. Een beheerder schakelt ze per school in/uit via Modulebeheer.
3. Uitgeschakelde modules leveren geen menu's of schermen — de kern blijft
   overal gelijk, modules zijn los bij te schakelen.

Een nieuwe module toevoegen = nieuwe app maken, één regel in
`MODULE_APPS` (in `backend/config/settings.py`), klaar.

## Starten

### Backend (Django, poort 8000)

```bash
cd backend
pip install -r requirements.txt
python manage.py migrate
python manage.py createsuperuser   # optioneel, voor /admin/
python manage.py runserver
```

API-eindpunten:
- `GET  /api/modules/` — alle modules met status.
- `POST /api/modules/<key>/state/` — body `{"enabled": true|false}`.
- `GET  /api/info/` — korte systeem-/gezondheidsinfo.
- CRUD-endpoints (telkens met `PATCH`/`DELETE` op `/<id>/`):
  `/api/personen/` (filter `?rol=leerling`), `/api/groepen/`,
  `/api/subgroepen/`, `/api/functies/`, `/api/schooljaren/`,
  `/api/kalenderdagen/` (filter `?schooljaar=<id>`), `/api/tijdsloten/`,
  `/api/activiteiten/`, `/api/locaties/`, `/api/roosterblokken/`
  (filters `?schooljaar=`, `?groep=`, `?subgroep=`, `?leerling=`),
  `/api/afwezigheden/` (filters `?persoon=`, `?van=`, `?tot=`),
  `/api/blok-uitzonderingen/` (filters `?roosterblok=`, `?schooljaar=`, `?van=`, `?tot=`).
- `GET /api/conflicten/?schooljaar=<id>` — roosterconflicten (dubbele inzet,
  locatiebotsing, onderbezetting).
- Module Leerplein: `/api/leerpleinen/`, `/api/subgroep-groep-koppelingen/`.
- Module Stage: `/api/stages/` (filters `?type=intern|extern`, `?leerling=<id>`).
- Tijdsloten kennen een optionele `groep` (per-groep tijden); personen hebben
  `stamgroep`, `vakken` en `geboortedatum`; activiteiten een `theorievak`-vlag.
- `/admin/` — Django-admin (personen, groepen, subgroepen en modulestatus).

> Draait SQLite niet op je projectmap (bv. op een netwerkschijf)? Zet dan
> `ROOSTER_DB_PATH` naar een lokaal pad, of pas `DATABASES` aan.

### Frontend (React, poort 5173)

```bash
cd frontend
npm install
npm run dev
```

De dev-server stuurt `/api` automatisch door naar de backend op poort 8000.
Open daarna http://localhost:5173 en ga naar **Modulebeheer** om modules
aan/uit te zetten.

## Volgende stap (Fase 5 & 6)

De losse modules verder uitbouwen: **Printen/Exporteren** (roosters als PDF) en
**Multi-user & toegang** verfijnen (leerling-/ouder-/collega-rollen). Eventueel de
conflictdetectie datum-specifiek maken (rekening houdend met afwezigheid per dag).