nilsjohan/recipe-app
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
69bcc3e3426704773b5ae1bed2abf7f7bffd1e2c
recipe-app/.kilo/plans/1779550355555-hidden-mountain.md
T
Nils-Johan Gynther 69bcc3e342
Test Suite / backend-pr-quick (push) Has been skipped
Details
Test Suite / quick-import-pr-quick (push) Has been skipped
Details
Test Suite / backend-full (push) Successful in 14m6s
Details
Test Suite / flutter-quality (push) Failing after 4m44s
Details
feat(web): improve web build configuration and accessibility 
- 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
2026-05-23 18:04:27 +02:00

6.6 KiB
Raw Blame History

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.
Reference in New Issue View Git Blame Copy Permalink