diff --git a/docs/changelog-claude.md b/docs/changelog-claude.md index e0f8d27..37ce791 100644 --- a/docs/changelog-claude.md +++ b/docs/changelog-claude.md @@ -4,6 +4,9 @@ This file documents all changes made to this project via Claude Code. ## [2026-02-13] +### Added +- Added internal technical reference document `docs/technical-notes-codex.md` with repository structure, application architecture, processing flow, parser system rules, ticketing/Autotask constraints, feedback attachment notes, deployment/build workflow, and operational attention points + ### Fixed - Fixed Autotask tickets and internal tickets not being linked to missed runs by calling `link_open_internal_tickets_to_run` after creating missed JobRun records in `_ensure_missed_runs_for_job` (both weekly and monthly schedules), ensuring missed runs now receive the same ticket propagation as email-based runs - Fixed checkboxes being automatically re-selected after delete actions on Inbox and Run Checks pages by adding `autocomplete="off"` attribute to all checkboxes, preventing browser from restoring previous checkbox states after page reload diff --git a/docs/technical-notes-codex.md b/docs/technical-notes-codex.md new file mode 100644 index 0000000..a7dbd2a --- /dev/null +++ b/docs/technical-notes-codex.md @@ -0,0 +1,165 @@ +# Technische Notities (intern) + +Laatste update: 2026-02-13 + +## Doel +Interne technische momentopname van de repository `backupchecks` voor snelle onboarding, troubleshooting en wijzigingsimpact. + +## Repository-overzicht +- Applicatie: Flask webapp met SQLAlchemy + Flask-Migrate. +- Runtime: containerized (Docker), deploy via Docker Compose stack. +- Primaire map met broncode: `containers/backupchecks/src`. +- Project bevat daarnaast veel functionele/documentatiebestanden in `docs/` en meerdere TODO-roadmaps op rootniveau. + +## Belangrijkste structuur +- `containers/backupchecks/Dockerfile`: Python 3.12-slim image, `gunicorn` start met `backend.app:create_app()`. +- `containers/backupchecks/requirements.txt`: Flask stack + Postgres driver + reporting libs (`reportlab`, `Markdown`). +- `containers/backupchecks/src/backend/app`: backend domeinlogica, routes, parsers, modellen, migraties. +- `containers/backupchecks/src/templates`: Jinja templates voor auth/main/documentation pagina's. +- `containers/backupchecks/src/static`: CSS, images, favicon. +- `deploy/backupchecks-stack.yml`: compose stack met `backupchecks`, `postgres`, `adminer`. +- `build-and-push.sh`: release/test buildscript met versiebump, tags en docker push. +- `docs/`: functioneel ontwerp, changelog, migraties, API-notities. + +## Applicatie-architectuur (huidige observatie) +- Factory patroon: `create_app()` in `containers/backupchecks/src/backend/app/__init__.py`. +- Blueprints: + - `auth_bp` voor authenticatie. + - `main_bp` voor kernfunctionaliteit. + - `doc_bp` voor interne documentatiepagina's. +- DB-init bij startup: + - `db.create_all()` + - `run_migrations()` +- Achtergrondtaak: + - `start_auto_importer(app)` start automatische mailimport thread. +- Health endpoint: + - `GET /health` geeft `{ "status": "ok" }`. + +## Functionele verwerkingsflow +- Import: + - Mail wordt opgehaald via Microsoft Graph API. +- Parse: + - Parser-selectie via registry + parserimplementaties per leverancier. +- Approve: + - Nieuwe jobs landen eerst in Inbox voor eerste klantkoppeling. +- Auto-process: + - Vervolgmails voor bekende jobs maken automatisch `JobRun` records. +- Monitor: + - Runs verschijnen in Daily Jobs en Run Checks. +- Review: + - Handmatige review verwijdert items uit ongereviewde werklijst. + +## Configuratie en runtime +- Config wordt uit environment opgebouwd in `containers/backupchecks/src/backend/app/config.py`. +- Belangrijke variabelen: + - `APP_SECRET_KEY` + - `APP_ENV` + - `APP_PORT` + - `POSTGRES_DB` + - `POSTGRES_USER` + - `POSTGRES_PASSWORD` + - `DB_HOST` + - `DB_PORT` +- DB URI patroon: + - `postgresql+psycopg2://:@:/` +- Default timezone in config: `Europe/Amsterdam`. + +## Datamodel (globaal) +Bestand: `containers/backupchecks/src/backend/app/models.py` +- Auth/gebruikers: + - `User` met role(s), actieve rol in sessie. +- Systeeminstellingen: + - `SystemSettings` met Graph/mailinstellingen, importinstellingen, UI-timezone, dashboard-policy, sandbox vlag. + - Autotask configuratie en cachevelden zijn aanwezig. +- Logging: + - `AuditLog` (legacy alias `AdminLog`). +- Domein: + - `Customer`, `Job`, `Override` en veel run/ticket-gerelateerde logica in andere modules/routes. + - Kernentiteiten uit systeemkennis: `JobRun`, `MailMessage`, ticket/remark-koppeltabellen, feedback-tabellen. + +## Parserarchitectuur +- Map: `containers/backupchecks/src/backend/app/parsers/` +- Twee lagen: + - `registry.py`: + - matching/documentatie/zichtbaarheid op `/parsers`. + - voorbeelden moeten generiek blijven (geen klantnamen). + - parserbestanden (`veeam.py`, `synology.py`, etc.): + - echte detectie en parsing. + - leveren gestructureerde output: software, type, jobnaam, status, objecten. +- Praktijkregel: + - patronen uitbreiden door toe te voegen, niet te vervangen (backward compatibility). + +## Ticketing en Autotask (kritische regels) +- Twee ticketsporen: + - interne tickets (`tickets`, `ticket_scopes`, `ticket_job_runs`). + - Autotask-ticketgegevens op `job_runs` + synchronisatie met intern ticket. +- Propagatie naar nieuwe runs gebeurt via `link_open_internal_tickets_to_run`. +- Deze propagatie moet worden aangeroepen bij: + - email-gebaseerde runcreatie (importflow), + - gemiste-runs generatie in `routes_run_checks.py`. +- Weergavelogica: + - link-gebaseerd via expliciete JOINs. + - resolved tickets (`resolved_at` gezet) mogen niet meer aan nieuwe runs gekoppeld worden. + - historische links blijven zichtbaar voor audit trail. +- Anti-patterns (niet gebruiken): + - resolved-logica op basis van datumvergelijkingen zoals `resolved_at >= run_date`. + +## UI en UX-notities +- Navbar is fixed-top met dynamische padding-correctie in de main container. +- Status-badges gebruiken semantische kleurcodes (success/warning/error/override/reviewed). +- Ticket-copy knop heeft drievoudige fallback: + - Clipboard API, + - `execCommand('copy')`, + - `prompt()` fallback. + +## Feedbackmodule met screenshots +- Modellen: `FeedbackItem`, `FeedbackVote`, `FeedbackReply`, `FeedbackAttachment`. +- Bijlagen: + - meerdere uploads, typevalidatie, limiet per bestand, opslag in database (BYTEA). +- Delete-strategie: + - soft delete als standaard, + - permanente delete alleen admin en alleen na soft delete. + +## Deployment en operations +- Stackbestand exposeert: + - app op `8080` + - adminer op `8081` +- Postgres persistent volume: + - `/docker/appdata/backupchecks/backupchecks-postgres:/var/lib/postgresql/data` +- In `deploy/backupchecks-stack.yml` staan onderaan ook voorbeeld `.env` variabelen opgenomen. + +## Build/release-flow +Bestand: `build-and-push.sh` +- Bump opties: + - `1` patch, `2` minor, `3` major, `t` test. +- Release-build: + - update `version.txt` + - commit + tag + push + - docker push van `:`, `:dev`, `:latest` +- Test-build: + - alleen `:dev` + - geen commit/tag. +- Services worden ontdekt onder `containers/*` met Dockerfile-per-service. + +## Technische observaties / aandachtspunten +- `README.md` is momenteel leeg; snelle instapinformatie ontbreekt. +- `LICENSE` is momenteel leeg. +- `docs/architecture.md` is momenteel leeg. +- `deploy/backupchecks-stack.yml` bevat hardcoded voorbeeldwaarden (`Changeme`), risico op foutief gebruik zonder secrets-management. +- App voert DB-init + migraties uit tijdens startup; bij grotere schemawijzigingen kan dit opstarttijd/robustness beïnvloeden. +- Er is veel functionaliteit rondom parsering en ticketing; regressierisico bij routewijzigingen is hoog zonder gerichte tests. +- Voor Autotask update-calls moet `description` expliciet behouden blijven bij updates (voorkomt ongewenste NULL-overschrijving). +- Security-hygiëne blijft belangrijk: + - geen klantnamen in parservoorbeelden/broncode, + - geen hardcoded credentials. + +## Snelle referenties +- App entrypoint: `containers/backupchecks/src/backend/app/main.py` +- App factory: `containers/backupchecks/src/backend/app/__init__.py` +- Config: `containers/backupchecks/src/backend/app/config.py` +- Modellen: `containers/backupchecks/src/backend/app/models.py` +- Parsers: `containers/backupchecks/src/backend/app/parsers/registry.py` +- Ticketing utils: `containers/backupchecks/src/backend/app/ticketing_utils.py` +- Run checks routes: `containers/backupchecks/src/backend/app/main/routes_run_checks.py` +- Compose stack: `deploy/backupchecks-stack.yml` +- Buildscript: `build-and-push.sh`