Nils-Johan Gynther
69bcc3e342
- Add source maps and web renderer build arguments with defaults - Configure Caddy with CSP headers, cache policies, and service worker handling - Defer loading of import screen for performance optimization - Add semantic labels to icons for accessibility - Update web index.html with Swedish language, meta tags, and description - Add robots.txt and lighthouse configuration - Add new planning documents and archive entries
147 lines
6.6 KiB
Markdown
147 lines
6.6 KiB
Markdown
# Plan: Projektanpassad Lighthouse-plan for Flutter-web
|
|
|
|
## Mål
|
|
Höja Lighthouse-resultaten för Flutter-webklienten i detta repo utan att bryta befintlig Docker/Caddy-deploy, med fokus på mätbar förbättring av prestanda, tillgänglighet och grundläggande SEO.
|
|
|
|
## Kontext och nuläge (verifierat i projektet)
|
|
- Flutter-web byggs redan i release-läge i `flutter/Dockerfile` via `flutter build web --release`.
|
|
- Webb klient körs via Caddy i `flutter/Caddyfile` och har redan `encode gzip`.
|
|
- `flutter/web/index.html` är minimal och innehåller redan korrekt viewport utan `user-scalable=no`.
|
|
- `flutter/web/` innehåller idag endast `index.html` (ingen `robots.txt`/`sitemap.xml` i Flutter-mappen).
|
|
- API-basurl injiceras redan korrekt med `--dart-define=API_BASE_URL=/api` via `compose.flutter.yml`.
|
|
|
|
## Problem i befintlig flutter-lighthouse.md som inte passar repo exakt
|
|
- Planen utgår delvis från Nginx/Apache, men projektet använder Caddy för Flutter-spåret.
|
|
- Påståendet om `user-scalable=no` gäller inte nuvarande `flutter/web/index.html`.
|
|
- Påståendet om ogiltig `robots.txt` kan inte verifieras i nuvarande Flutter-webmapp.
|
|
- Förslag om tvingad HTML-renderer är för grovt; bör vara experiment med mätning och rollback-kriterier.
|
|
|
|
## Strategi
|
|
Arbeta i tre iterationer med baseline -> lågriskoptimeringar -> tyngre optimeringar, och låt varje steg vara datadrivet.
|
|
|
|
---
|
|
|
|
## Fas 1: Baseline och mätprotokoll (dag 1)
|
|
1. Skapa en reproducerbar mätbaseline för både lokal container och produktionsdomän.
|
|
2. Kör Lighthouse minst 3 gånger per miljö och ta median för:
|
|
- Performance score
|
|
- LCP
|
|
- TBT
|
|
- INP (om rapporteras)
|
|
- Transfer size / antal requests
|
|
3. Dokumentera nuläge och tröskelvärden före ändringar.
|
|
|
|
### Acceptanskriterier Fas 1
|
|
- Baseline-tabell finns med mätvärden från 3 körningar per miljö.
|
|
- Samma URL, samma nätprofil och samma emulering används konsekvent.
|
|
|
|
---
|
|
|
|
## Fas 2: Lågriskfixar med hög nytta (dag 1-2)
|
|
|
|
### 2.1 Index och metadata (`flutter/web/index.html`)
|
|
- Lägg till `lang="sv"` på `<html>`.
|
|
- Lägg till relevant `meta description` för appens huvudsakliga nytta.
|
|
- Behåll `viewport` som den är (ingen ändring behövs kring zoom-blockering).
|
|
|
|
### 2.2 Caddy-headerhygien (`flutter/Caddyfile`)
|
|
- Behåll `encode gzip`.
|
|
- Lägg till explicita cache-headers för hashade statiska assets (js/wasm/fonts) med lång TTL och immutable.
|
|
- Lägg till kortare/konservativ cache för `index.html` så nya deploys slår igenom snabbt.
|
|
- Lägg till säkerhetsheaders som är kompatibla med Flutter-web (minst grundnivå: `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`).
|
|
|
|
### 2.3 Byggoptimering (`flutter/Dockerfile`)
|
|
- Utvärdera `--no-source-maps` i produktionsbuild för mindre artifact-storlek.
|
|
- Säkerställ att eventuella ändringar inte påverkar felsökning i miljö där sourcemaps behövs.
|
|
|
|
### Acceptanskriterier Fas 2
|
|
- Lighthouse visar förbättring i minst två nyckelmått (t.ex. LCP/TBT).
|
|
- Ingen regress i appstart, routning eller API-proxy `/api/*`.
|
|
- Build pipeline passerar oförändrat i Docker.
|
|
|
|
---
|
|
|
|
## Fas 3: Prestandaexperiment med tydlig rollback (dag 2-4)
|
|
|
|
### 3.1 Rendering-strategi (CanvasKit vs HTML/Skwasm)
|
|
- Kör A/B-test av rendererstrategi i en separat branch/buildvariant.
|
|
- Mät skillnad i initial transfer size, LCP och renderingkvalitet på kritiska vyer.
|
|
- Beslut endast baserat på mätdata + visuell/regressionskontroll.
|
|
|
|
### 3.2 Deferred loading i tunga featureflöden
|
|
- Identifiera kandidater för deferred imports (exempel: import/admin-vyer med hög kodvikt).
|
|
- Introducera gradvis och validera att navigation inte blir ryckig.
|
|
|
|
### 3.3 Bootstrap-laddning
|
|
- Behåll asynkron laddning i `index.html` om mätning visar bäst resultat.
|
|
- Undvik manuella hacks som injicerar canvaskit-script ad hoc utan evidens i mätning.
|
|
|
|
### Acceptanskriterier Fas 3
|
|
- Minst 15-25% förbättring i TBT eller tydlig minskning i JS-exekveringstid jämfört med baseline.
|
|
- Ingen funktionell regress i kärnflöden (login, inventarie, recept, import).
|
|
|
|
---
|
|
|
|
## Fas 4: Tillgänglighet (A11y) med repo-fokus (dag 3-5)
|
|
1. Inventera ikonknappar och actions i Flutter-kod och säkra `tooltip`/`semanticsLabel` där det saknas.
|
|
2. Lägg till/justera `Semantics` för centrala actions (import, spara, ta bort, navigering).
|
|
3. Verifiera tangentbordsnavigering i webbläsare för huvudflöden.
|
|
|
|
### Acceptanskriterier Fas 4
|
|
- Lighthouse Accessibility förbättras mätbart.
|
|
- Inga nya fokusfällor eller förlorad keyboard-navigering introduceras.
|
|
|
|
---
|
|
|
|
## Fas 5: SEO-minimum för app-shell (dag 4-5)
|
|
1. Säkerställ att titel och meta description är korrekta för startsidan.
|
|
2. Besluta om `robots.txt` och `sitemap.xml` ska hanteras i Flutter-web, Caddy eller upstream-domänkonfiguration (inte antagande).
|
|
3. Implementera endast den väg som matchar faktisk domänrouting i drift.
|
|
|
|
### Acceptanskriterier Fas 5
|
|
- Lighthouse SEO får förbättring från baseline.
|
|
- Robots/sitemap-lösning är verifierad mot faktisk driftarkitektur.
|
|
|
|
---
|
|
|
|
## Fas 6: Säkerhet och CSP (dag 5)
|
|
1. Introducera en pragmatisk CSP för Flutter-web i Caddy med minsta nödvändiga undantag.
|
|
2. Testa särskilt att Flutter bootstrap, API-anrop och ev. externa resurser fungerar.
|
|
3. Strama åt policyn iterativt istället för en aggressiv engångspolicy.
|
|
|
|
### Acceptanskriterier Fas 6
|
|
- Säkerhetsheaders levereras korrekt från Flutter-Caddy.
|
|
- Ingen blockerad kärnfunktion pga CSP.
|
|
|
|
---
|
|
|
|
## Prioriterad genomförandeordning
|
|
1. Fas 1 (baseline)
|
|
2. Fas 2 (lågriskfixar)
|
|
3. Re-mätning
|
|
4. Fas 3 (prestandaexperiment)
|
|
5. Fas 4 (tillgänglighet)
|
|
6. Fas 5 (SEO-minimum)
|
|
7. Fas 6 (CSP hardening)
|
|
8. Slutlig Lighthouse-jämförelse och dokumentation
|
|
|
|
## Definition of Done
|
|
- Reproducerbar före/efter-mätning finns dokumenterad.
|
|
- Performance, Accessibility och SEO har förbättrats jämfört med baseline.
|
|
- Inga regressioner i Docker/Caddy-flödet eller appens kärnflöden.
|
|
- Åtgärderna är anpassade till faktisk stack (Flutter + Caddy), inte generiska Nginx-råd.
|
|
|
|
## Konkreta filer som sannolikt berörs vid implementation
|
|
- `flutter/web/index.html`
|
|
- `flutter/Caddyfile`
|
|
- `flutter/Dockerfile`
|
|
- ev. flera Flutter-vyer med knapp-/ikonsemantik under `flutter/lib/**`
|
|
|
|
## Risker och motåtgärder
|
|
- **Risk:** För aggressiv CSP bryter Flutter-bootstrap.
|
|
**Motåtgärd:** Iterativ policy + verifiering efter varje ändring.
|
|
- **Risk:** Rendererbyte förbättrar vikt men försämrar visual fidelity.
|
|
**Motåtgärd:** A/B-test med tydliga rollback-kriterier.
|
|
- **Risk:** Cache-policy gör deploys "stale".
|
|
**Motåtgärd:** Lång cache endast för fingerprintade assets, kort cache för `index.html`.
|