Add internal technical notes document
This commit is contained in:
parent
b5cf91d5f2
commit
d2cdd34541
@ -4,6 +4,9 @@ This file documents all changes made to this project via Claude Code.
|
|||||||
|
|
||||||
## [2026-02-13]
|
## [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
|
||||||
- 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 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
|
- 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
|
||||||
|
|||||||
165
docs/technical-notes-codex.md
Normal file
165
docs/technical-notes-codex.md
Normal file
@ -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://<user>:<pass>@<host>:<port>/<db>`
|
||||||
|
- 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 `:<version>`, `: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`
|
||||||
Loading…
Reference in New Issue
Block a user