HealthLog/docs/audit/2026-04-26-PLAN.md

HealthLog Audit-Plan — Phasen-Übersicht

Datum: 2026-04-26 Audit-Bericht: ~/infra/reports/healthlog-audit-2026-04-26.md Status: Geplant, noch nicht in Execution

Strategische Decisions

1. Onboarding-Redesign: 4-Step-Wizard → 2-Step + Empty-State-Dashboard + Getting-Started-Card.
2. Custom-Measurement-Types: Pragmatic Hardcoding (jetzt #89), Cronometer-Pattern als v1.5+-Roadmap.
3. apiClient-Refactor vor Onboarding-Redesign, damit neues Onboarding nicht denselben Silent-Failure-Bug reproduziert.

---

Phasen-Sequenz (10 Phasen)

#	Phase	Skill	Effort	Issue-Bezug
1	Setup-Notfall + Versions-Sync	gsd:quick	≤4 h	#87 (Pflaster), #88
2	Docker-Image-Pipeline (GHCR-Push + Doc-Konsolidierung)	gsd:plan-phase	~1 d	#88
3	Issue #89 — TBW + Bone Mass hardcoded	gsd:plan-phase	~1 d	#89
4	apiClient-Wrapper + geteilte Zod-Schemas	gsd:research-phase → gsd:plan-phase	2-3 d	#87 (strukturell)
3.5	Onboarding-Redesign (2 Steps, TTFV <60s)	gsd:research-phase → gsd:plan-phase	~2 d	#87 (strukturell)
4.5	Empty-State-Dashboard-Tiles (eine pro Type)	gsd:plan-phase	~1 d	#87, #89
4.6	„Getting Started"-Checklist auf Dashboard	gsd:plan-phase	~4 h	#87
5	Security + Reliability Hardening	gsd:plan-phase	1-2 d	—
6	Test-Coverage-Boost (Auth/Passkey/Withings/pg-boss)	gsd:plan-phase	1-2 d	—
7	UX/i18n/a11y Polish (Residuals aus #73)	gsd:quick	≤4 h	#73 (Residuals)
8	Settings-Page-Splitting (3143 → Sub-Components)	gsd:research-phase → gsd:plan-phase	2-3 d	—

Reihenfolge: 1 → 2 → 3 → 4 (apiClient) → 3.5 (Onboarding nutzt apiClient) → 4.5 → 4.6 → 5 → 6 → 7 → 8.

---

Phase 1 — Setup-Notfall (≤4 h)

Goal: Self-Hoster kann mit git clone && docker compose up -d tatsächlich starten + Issue #87 stoppt zu blocken.

• docker-compose.yml: expose:3000 → ports: "3000:3000" (DX-002)
• docker-compose.yml: POSTGRES_PASSWORD: "${POSTGRES_PASSWORD:?required}" (SEC-003)
• .env.example: localhost:5432 → db:5432 (DX-003)
• package.json: "version": "1.2.0" (DOC-007)
• CLAUDE.md + AGENTS.md: 23 Models statt 21/22 (DOC-001)
• src/app/onboarding/page.tsx: await fetch(...) mit .ok-Check + toast.error() (DX-005 Pflaster)
• README „minutes"-Claim entschärfen (DX-006)

Verification: Frischer Clone + neue VM → cp .env.example .env && set secrets && docker compose up -d → App auf http://localhost:3000 erreichbar in <5 min.

---

Phase 2 — Docker-Image-Pipeline (~1 d)

Goal: Issue #88 vollständig schließen. Pre-built Image auf GHCR. Docs konsolidiert.

• .github/workflows/docker-publish.yml: Multi-Arch (amd64+arm64), Trigger auf Tag-Push + main, GHCR-Push mit GITHUB_TOKEN
• healthlog-docs/getting-started/installation.mdx → Verweis auf self-hosting/docker.mdx statt Duplikat (DX-004)
• Repo-docker-compose.yml vs Docs-docker-compose.yml: eine Variante als Single-Source-of-Truth (Compose verwendet image: aus GHCR; Doc-Snippet wird daraus generiert)
• SECURITY.md + Image-Pull-Instructions
• healthlog-landing prüfen ob „Quick Start" aktualisiert werden muss

---

Phase 3 — Issue #89: TBW + Bone Mass (~1 d)

Goal: User-Anfrage von Manschk3rl beantworten. Blueprint = v1.2-Glucose-Migration.

Touchpoints:

1. prisma/schema.prisma: MeasurementType Enum + 2 neue Werte
2. prisma/migrations/0019_* (additive ALTER TYPE ... ADD VALUE)
3. src/lib/validations/measurement.ts: unitMap, VALUE_RANGES
4. src/lib/format.ts + i18n-Keys (4-6 neue Keys)
5. src/lib/doctor-report-pdf.ts: TYPE_LABEL_KEYS, TYPE_UNIT_KEYS, vitalTypes
6. src/components/measurements/measurement-form.tsx: MEASUREMENT_TYPES Array
7. src/lib/withings/client.ts + sync.ts: Mapping aus Withings body_composition
8. src/app/api/dashboard/widgets/route.ts + DEFAULT_DASHBOARD_LAYOUT: 2 neue Widget-IDs
9. healthlog-docs health-metrics.mdx aktualisieren
10. Optional: /api/ingest/measurements Bearer-Endpoint für n8n (analog /api/ingest/medication)

---

Phase 4 — apiClient-Wrapper (2-3 d)

Goal: Silent-Failure-Pattern strukturell eliminieren. Voraussetzung für 3.5.

• src/lib/api-client.ts: apiClient.{get,post,put,delete}<T>(path, body?, schema?) → Result<T, ApiError>
• Auto-.ok-Check + Toast bei Fehler (mit i18n-Mapping)
• Geteilte Zod-Schemas: Validations-Module in src/lib/validations/ werden client-importable
• Migration: alle ~50 fetch(...)-Aufrufe in src/app/ und src/components/ → apiClient.*
• Tests für apiClient (Mock-Fetch, Error-Mapping, Schema-Validation)

---

Phase 3.5 — Onboarding-Redesign (~2 d)

Goal: TTFV <60s, 90% Completion (statt aktuell ~8% global).

Neuer Flow:

• Step 1: Welcome + Anzeigename (optional) + Einheiten + Größe (optional). Sekundärlink „Skip everything → Dashboard".
• Step 2: Multi-Select-Chips „Was willst du tracken?" (Weight/BP/Pulse/Mood/Glucose/Sleep/Steps/BodyFat/TBW/BoneMass/Medications). Pre-checked Defaults. Speichert in User.dashboardWidgetsJson.
• Routing nach Onboarding: direkt zum Dashboard mit „Getting Started"-Card (s. Phase 4.6).

Entfällt ersatzlos: Targets-Step, Notifications-Teaser-Step, Front-loaded-Med-Wizard.

Permissions deferred: Notifications nur bei „Add medication → Reminder ein", PWA-Install nur bei Day-2-Return-Visit oder nach 3. Eintrag.

---

Phase 4.5 — Empty-State-Dashboard-Tiles (~1 d)

Goal: Mealie/Tandoor/Linear-Pattern. Jede Metric-Tile hat Empty-State mit „Add your first X"-CTA.

• src/components/dashboard/EmptyStateTile.tsx als wiederverwendbare Komponente
• Pro MeasurementType: eigene Empty-State-Card (Icon + Headline + CTA-Button → opens MeasurementForm prefilled)
• Medications analog: Empty-State „Add your first medication" → opens MedicationForm mit Default-Schedule (08:00–09:00 daily)
• Dashboard-Routing: User mit dashboardWidgetsJson ohne Daten sieht Empty-States, nicht leeres Grid

---

Phase 4.6 — „Getting Started"-Checklist (~4 h)

Goal: Linear-Pattern. Persistent dismissible Card auf Dashboard.

• User.gettingStartedDismissedAt: DateTime? (nullable, NULL = noch sichtbar)
• 4 Items mit Live-Status:
  • ☐ Log your first measurement (✓ wenn ≥1 Measurement existiert)
  • ☐ Add a medication (✓ wenn ≥1 Medication existiert)
  • ☐ Set a target value (✓ wenn thresholdsJson non-empty)
  • ☐ Install HealthLog as App (✓ wenn beforeinstallprompt accepted, sonst nur sichtbar bei PWA-fähigen Browsern)
• „Dismiss"-Button → setzt Timestamp, Card verschwindet
• Vollständig durchgeklickt → Card verschwindet automatisch

---

Phase 5 — Security + Reliability Hardening (1-2 d)

• SEC-002: SSRF-IPv4-Parser-Härtung (führende Nullen)
• SEC-004: GitHub-PAT-Logging-Sanitization (Sensitive-Field-Filter)
• SEC-005: AES-256-GCM Key-Rotation-Doc + optional keyVersion
• SEC-006: Custom-Thresholds-Rate-Limit
• PERF-001: N+1 in insights/comprehensive/route.ts:219 per groupBy auflösen
• REL-002: Onboarding-Error-Handling über Pflaster hinaus (via apiClient aus Phase 4)
• REL-003: pg-boss process.on('SIGTERM', ...) für graceful shutdown
• LOG-001: 6× console.log() in src/lib/jobs/reminder-worker.ts → Wide-Event-Annotations
• CI: ESLint+Typecheck continue-on-error: true → blocking

---

Phase 6 — Test-Coverage-Boost (1-2 d)

Coverage 35% → 60% auf kritischen Pfaden.

Top-5-Test-Suites:

1. Session-Validation Roundtrip (src/lib/auth/session.ts)
2. Passkey-Register/Verify-Integration (Attestation-Flow)
3. Notification-Dispatcher Multi-Channel (TELEGRAM/NTFY/WEB_PUSH)
4. pg-boss Reminder-Worker (Queue-Init, Job-Execution, Cron, Retry)
5. Withings-OAuth + Sync (exchangeCode → refresh → fetchMeasurements)

Plus: TEST-006 Custom-Thresholds-Resolution, TEST-007 AI-Provider-SSRF.

---

Phase 7 — UX/i18n/a11y Polish (≤4 h)

Residuals aus Issue #73 + neue Findings:

• I18N-002: Admin-Page Hardcoded „Web Push" / „Bug Report" → t(...)
• I18N-003: medication-card.tsx Intl.DateTimeFormat("en-CA") und toLocaleString("en-US") → useFormatters()
• A11Y-001: phase-config-dialog.tsx Text-Indicator neben Farb-Punkt (WCAG 1.4.1)
• A11Y-002: Admin StatusItem aria-label verifizieren
• UX-002: Admin-Save-Error-UX (Field-Highlight bei Fehler)
• UX-003: Bottom-Nav-Touch-Targets p-2.5 → p-3 (≥44×44 px)

---

Phase 8 — Settings-Page-Splitting (2-3 d)

Goal: 3143 Zeilen → Sub-Components mit klarer Boundary.

• Research-Phase: Sub-Routes (/settings/profile, /settings/notifications, …) vs Sub-Components in einer Page?
• Plan-Phase: Migrationsstrategie ohne URL-Bruch
• Insights-Page (1750 Zeilen) folgt analogem Pattern

---

Issue-Vorschlags-Abdeckung

Issue #87 (Onboarding-Meds verschwinden)

• Pflaster: Phase 1 (.ok-Check + Toast)
• Strukturelle Lösung: Phase 4 (apiClient) + Phase 3.5 (neuer Flow ohne Med-Wizard) + Phase 4.5 (Empty-State-Tiles, Meds direkt sichtbar) + Phase 4.6 (Checklist)

Issue #88 (Setup holprig — 4 Hauptpunkte + 3 Verbesserungsvorschläge)

#88 Punkt	Phase	Status
(a) Bundled compose ≠ docs version	Phase 2 (DOC-005)	abgedeckt
(b) ghcr.io 404 (kein Image gepusht)	Phase 2 (DX-001 GHA-Workflow)	abgedeckt
(c) .env.example localhost:5432 vs Compose db:5432	Phase 1 (DX-003)	abgedeckt
(d) expose:3000 statt ports:3000:3000	Phase 1 (DX-002)	abgedeckt
Vorschlag: GHA für Image-Push (GHCR/Docker Hub)	Phase 2	abgedeckt
Vorschlag: Merge „Getting started > Installation" + „Self-Hosting > Docker"	Phase 2 (DX-004)	abgedeckt
Vorschlag: Same presets across compose+docs+.env.example	Phase 1 + Phase 2	abgedeckt

Issue #89 (TBW + Bone Mass)

• Phase 3 hardcoded mit Withings-Mapping. Optional /api/ingest/measurements für n8n in Phase 3.

Issue #73 (UX-Liste mit 8 Punkten — CLOSED in v1.2)

#73 Punkt	v1.2-Status	Residual?
1. Passkey-Errors unklar	Resolved (Package C, typed errors)	TEST-002 (keine Tests) → Phase 6
2. Number-Formatting (DE 70,5 vs US 70.5)	Resolved (Package B, locale-aware formatters)	I18N-003 in medication-card.tsx → Phase 7
3. Chart-Labels „7P/30P/90P/All"	Resolved (Package A, „7 Pkt"/„7 pts")	—
4. Dashboard nicht real-time	Resolved (invalidateKeys durchgängig)	—
5. GitHub-Setup-Confusion	Resolved (Built-in Feedback in v1.2)	—
6. Built-in Feedback	Done in v1.2	—
7. Admin-Save ohne Error-UX	Partial (Success-Msg ja, Error-Highlight schwach)	UX-002 → Phase 7
8. Blood-Sugar	Done in v1.2	—

Issue #74 (raw locale keys in UI)

Resolved in v1.2.

---

Time-to-First-Value (TTFV) Ziel

Nach Onboarding-Redesign + Empty-State-Pattern:

• Login → Dashboard mit Empty-States: 2 Klicks
• Klick auf „Add your first weight" → Form prefilled „now" → Submit: 30 Sek
• TTFV-Ziel: <60 Sekunden (Branchenvergleich: führende Health-Apps 30-90s)

Anti-Patterns explizit vermieden

• Permissions-Cold-Prompt (Notifications/PWA) auf Day 1
• Front-loaded Targets vor erster Messung
• Multi-Step-Wizard mit identischem Skip-Button
• fetch() ohne .ok-Check (apiClient löst strukturell)
• Mega-Page-Pattern (Phase 8 löst Settings 3143 Z.)
• Custom-Measurement-Types vorzeitig (40-60h Wartung/Jahr für 50% Feature-Loss)