Pivot/OVERDRACHT.md

PIVOT 1.1.0 (meerdere scholen) – overdracht

Dit document vat samen hoe PIVOT in elkaar zit, welke afspraken er in de code gelden en wat er recent bijkwam. Het is bedoeld voor wie verder werkt aan PIVOT (zelf, of samen met een AI-assistent: geef dan dit bestand en de zip van het project mee). Lees ook MEERDERE_SCHOLEN.md (installatie, rollen) en DATABASE.md (tabellen).

⚠️ config.ini en de map geheimen/ bevatten echte wachtwoorden en sleutels. Deel ze niet en zet ze nooit in een chat, ticket of e-mail. Geef een collega een kopie van het project zonder die bestanden en laat hem/haar een eigen config.ini invullen.

---

1. Architectuur in het kort

• Flask-app (app.py) met ±40 blueprints (blueprints/) en de logica in services/; HTML in templates/ (Jinja, base.html + static/global.css).
• Multi-tenant (tenancy.py): één centrale database (Scholen, Gebruikers, rechten, logs, ...) en één database per school (toestellen, leerlingen, ...).
  • huidige_school() = de school van het verzoek; in_school(school) / met_school(fn) voor achtergrondthreads.
  • Instellingen per school = Veld(...) in tenancy.VELDEN (verschijnen vanzelf in 🔌 Koppelingen); lezen met school.get('SLEUTEL') of Config.SLEUTEL (metaclass leest de huidige school).
  • school.cache = per-school geheugen (wordt leeggemaakt bij wijzigingen aan de school).
  • school_singleton(cls, init) = één object per school (gebruikt voor achtergrondtaken met status-dict).
  • google_credentials(scopes, subject) = serviceaccount van de school, gedelegeerd naar subject.
• Database (database.py): execute_query (schooldatabase), central_query (centraal); commit=True geeft het aantal rijen terug. Pools per database (config.ini › [database] › pool_size, standaard 3).
• Rechten (rechten.py): ONDERDELEN = lijst (code, naam, categorie); routes met @recht_vereist('code'), templates met {% if mag('code') %}. Een nieuw onderdeel verschijnt vanzelf in 🔐 Gebruikers & rechten. log(...) schrijft in het logboek.
• Achtergrondtaken: threads gestart in app.py (enkel in het echte proces, niet in de reloader): afwezigheden, 2FA, Skore, GO! Pro (nachtelijk verzamelen), Gmail-handtekeningen (nachtelijk). Taken die maar één keer per dag mogen lopen, "claimen" de dag met een UPDATE ... WHERE (werkt ook met meerdere processen).
• Opstarten: tenancy.ensure_schema() (centrale tabellen) en services/tabelnamen.py (zie §5).

2. Afspraken in de code

• Alles in het Nederlands (namen, meldingen, commentaar).
• Tabellen die een module zelf nodig heeft: CREATE TABLE IF NOT EXISTS in een ensure_tables()/*_ensure() in de service, én dezelfde DDL in sql/school.sql of sql/centraal.sql + sql/installatie_pivot_26-27.sql, én een regel in DATABASE.md. Kolommen die later bijkomen: SHOW COLUMNS + ALTER TABLE in de ensure-functie.
• Tabelnamen met hoofdletters moeten exact kloppen (Linux!); zie §5.
• Templates:
  • {% block main_class %}wide{% endblock %} voor brede tabellen; tabellen met zoeken/sorteren/paginering in de browser (helpers perPagina(sleutel, standaard) en perPaginaKiezer(...) uit base.html).
  • In HTML-attributen (onsubmit="...", onchange, data-...) altijd |tojson|forceescape, anders breekt het attribuut op de aanhalingstekens (bevestigingsvragen werkten daardoor niet meer).
  • Elementen die met het hidden-attribuut verborgen worden: zet [hidden] { display: none !important; } in de pagina-CSS (knopstijlen overschrijven het anders).
• CSV-exports: ; als scheidingsteken en UTF-8 met BOM (Excel). Excel: openpyxl.
• Google-fouten vertalen naar begrijpelijke meldingen (vriendelijk(e) in de services) mét de scope die ontbreekt.

3. Nieuw onderdeel toevoegen (checklist)

1. services/<naam>_service.py (logica, tabellen) en blueprints/<naam>_bp.py (routes).
2. Blueprint registreren in app.py.
3. Recht in rechten.ONDERDELEN (code, naam, categorie).
4. Link in het juiste blok van templates/dashboard.html ({% if mag('code') %}; voeg de code ook toe aan de mag(...)-voorwaarde van het blok).
5. Nieuwe Google-scope? Toevoegen aan de lijst + tabel in services/handleidingen_standaard.py (de handleiding in de database wordt niet automatisch bijgewerkt: zelf aanpassen in 📘 Handleidingen).
6. SQL-bestanden en DATABASE.md bijwerken.

4. Overzicht van recente onderdelen

Onderdeel	Bestanden	Opmerkingen
IP-blokkades / whitelist	ipblokkade_bp.py, services/ipblokkade.py	gewone gebruikers met recht ip_whitelist zien/beheren enkel hun eigen school
Aanmelden	blueprints/auth.py	geen schoolkeuze meer: laatste school → domein → cookie → laagste instellingsnummer; domeinen mogen gedeeld worden door meerdere scholen
GO! Pro + verzameltabel	gopro_bp.py, gopro_service.py, gopro*.html	verzameltabel (centraal), rode lijst, verzonden, nachtelijk verzamelen; periode = lopend schooljaar (1/9–31/8)
Leerlingfacturatie	facturatie_bp.py, facturatie_service.py	Informat Invoice API (GraphQL); scope per toegangsgroep (<GUID>_<installatie>), wordt zelf gezocht
Internaat	internaat_bp.py, internaat_service.py, aanwezigheid_service.py	Internaat WEB API; aanwezigheden per week; Smartschool-check "voornaam achternaam"
Gmail	gmail_delegatie_bp.py, gmail_labels_bp.py, handtekeningen_bp.py, contacten_bp.py, verzendlijsten_bp.py	delegaties (+ overzicht), mails verplaatsen, handtekeningen (functie/telefoon uit Google, nachtelijk), contactlijsten in mailboxen + zichtbaarheid adresboek
Google	google_licenties_bp.py, gedeelde_drives_bp.py	licenties (customerId: domein of klant-ID), gedeelde drives: leden/rechten, "waar is iemand lid van", gebruiker vervangen (zelfde rol)
Smartschool	sgr_groepen_bp.py, sgr_groepen_service.py	subgroepen + leden van een hoofdgroep (standaard "groepen GO-Antwerpen")
Basisonderwijs	basisonderwijs_bp.py, bingel_service.py	blok enkel bij Onderwijsniveau = basis; Bingel-Excel (klas uit Informat-inschrijvingen, klasnummer alfabetisch)
Toestellen	devices.py, inventaris.html, toestellen.html	eigendom: alle leerlingen + filter met/zonder toestel, historie per leerling en per toestel, knoppen uitdelen/inleveren; Alle toestellen: blokkeren/deblokkeren in Google (kolom Toestellen.Geblokkeerd)
Dashboard	dashboard.html	blokken Gmail, Internaat, Basisonderwijs, Leerlingfacturatie, Links (website + Smartschool)

Benodigde Google-scopes (domeinbrede delegatie) staan in 📘 Handleidingen; recent bijgekomen: gmail.modify, gmail.settings.basic, contacts, drive. De bijbehorende API's (Gmail, People, Drive, Enterprise License Manager) moeten aanstaan in het Cloud-project van het serviceaccount.

5. Omgeving en installatie-aandachtspunten

• Windows → Linux: MySQL op Windows bewaart tabelnamen in kleine letters; op Linux (lower_case_table_names = 0) herstelt services/tabelnamen.py dat bij het opstarten en bij 🩺 Testen (enkel voor de tabellen die PIVOT kent; zijn beide versies gevuld, dan enkel een melding in het logboek).
• "1040 Too many connections": (aantal scholen + 1) × pool_size per PIVOT-proces moet onder max_connections van MySQL blijven. Oplossing: SET PERSIST max_connections = 500; of pool_size verlagen.
• Productie: liefst nginx (HTTPS, Let's Encrypt) + gunicorn/waitress i.p.v. de Flask-ontwikkelserver, en de poort van PIVOT enkel intern openzetten. Het logo van Gmail-handtekeningen (/handtekening-logo/...) moet wel publiek bereikbaar zijn (de IP-blokkering slaat die route over).

6. Nog niet getest tegen de echte omgeving / openstaand

Onderstaande onderdelen werden enkel getest met nagebootste antwoorden; bij het eerste echte gebruik goed nakijken:

• Bingel: het veld met de klas in de Informat-inschrijvingen (inschrKlassen); de pagina toont de veldnamen die Informat teruggeeft als iets leeg blijft.
• SGR groepen: formaat van getAllGroupsAndClasses (XML/base64) en de leden per groep.
• Contactlijsten (People API), gedeelde drives (Drive API), handtekeningen (Gmail sendAs).
• Licenties: terugval op de klant-ID als het schooldomein geen primair domein is.
• Leerlingfacturatie: automatisch zoeken van de scope (identityserver).
• Informat-fout "SqlDateTime overflow" bij één school = foute datum in Informat zelf (niet in PIVOT).

7. Verder werken

• Elke wijziging werd telkens als volledige zip van Pivot_1.1.0 aangeleverd (zonder __pycache__).
• Bij een nieuwe vraag aan een AI-assistent: geef dit bestand, DATABASE.md, MEERDERE_SCHOLEN.md en de betrokken bestanden mee (of de hele zip zonder config.ini/geheimen/), en beschrijf wat je wil met een schermafbeelding erbij.