Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/archive/handoffs/HANDOFF-2026-05-21.md
T

113 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Handoff — Stand 2026-05-21
> **Historical snapshot only (2026-05-25 cleanup).** This file is preserved
> for audit/history. Do not treat its "start", "push", "deploy" or operator
> instructions as current work. Use `PROGRESS.md`, `OPERATOR-CHECKLIST.md`
> and the latest session notes for live status.
**Vorgänger-Agent:** Claude Opus 4.7 (1M context)
**Letzte aktive Session:** #72 i18n-Extraction (2 Batches) + Worker-Crash-Fix + Lighthouse-CI-Rebuild — 5 Commits gepusht, Staging grün
**Ziel des Handoffs:** Nachfolge-Agent weiß in 5 Minuten wo wir stehen und kann einen der großen Tracks fokussiert aufnehmen.
---
## 0. Start hier (5-Minuten-Onboarding)
**Lies in dieser Reihenfolge:**
1. Dieses Dokument komplett.
2. `HANDOFF-2026-05-20b.md` + `HANDOFF-2026-05-20.md` — archivierter Bucket-A / Operator-Pending-Kontext.
3. `.claude/CLAUDE.md` — React-Router-v7-Konventionen, strikt enforced.
4. `AGENTS.md` im Repo-Root — Workflow + Branch-Strategie.
**Sofort-Sanity-Check (Repo-Root):**
```bash
git log --oneline -6 # HEAD sollte d1b2183a sein (oder neuer)
git status -s # nur packages/db/generated/** churn erwartet
git pull --rebase --autostash # andere Agenten arbeiten ggf. parallel
```
**Dann:** EINEN großen Track aus Section 3 wählen, fokussiert aufnehmen. Nicht mehrere parallel. Bei #38 zwingend eigene saubere Session (siehe Risiko-Hinweis).
---
## 1. Was diese Session bewegt hat (5 Commits auf `main`, gepusht)
`origin/main` = `d1b2183a`. Push-Range dieser Session: `c8b37a89..d1b2183a`.
| Commit | Was |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `35b7483a` | **#72 i18n Batch 1** — 65 hartcodierte JSX-Text-Strings über 42 `apps/web/app`-Dateien auf `ui.autogenerated.*`-Translation-Keys umgestellt (sha1-Suffix, Konvention der bestehenden 1335 Keys). EN-Werte + idiomatische deutsche Übersetzungen in beide `translations.json`. `verify-hardcoded-strings.mjs`-Baselines runter: `jsx-text` 85→18, `user-facing-prop-literal` 73→46, Lock-Test angepasst. |
| `7c36c00c` | **#72 i18n Batch 2** — 20 weitere gate-gezählte Strings über 7 Admin-/Route-Dateien (Tabellen-Header, `Card`/`Breakdown`-Props, 3 interpolierte `aria-label`s mit `{{value0}}`). Baselines: `jsx-text` 18→9, `user-facing-prop-literal` 46→35. |
| `a06c41ff` | **Worker-Crash-Fix** — `ioredis` in `apps/worker/package.json` deklariert. Der Worker bündelt `@toolctrl/shared-store` (importiert `ioredis` direkt) ins `dist/index.js`; `ioredis` war nur transitive Dep → unter pnpms isoliertem Linker nicht im Worker-Image → `ERR_MODULE_NOT_FOUND`, Crash-Loop. |
| `cff48bc4` | **Lighthouse-CI-Rebuild** — Workflow lief auf dem Gitea-Runner nie (kein Browser, kein Server, keine DB). Neu: auditet das deployte Staging (`boiler.saas-ctrl.com`), Gitea-Job installiert Chromium, Trigger = `schedule` (nächtlich) + `workflow_dispatch`. Neue `.lighthouserc.staging.json`. |
| `d1b2183a` | **Lighthouse: nur Performance gegatet** — Produkt-Entscheidung des Operators: B2B-SaaS, SEO irrelevant. `categories:performance` bleibt `error ≥0.95`; `seo` nicht mehr asserted; `accessibility`/`best-practices` → `warn`. Gilt für `.lighthouserc.staging.json` + `.lighthouserc.json`. |
**Verifiziert:** Worker healthy auf Staging, `deploy.yml` grün, `lighthouse.yml` grün (Run 7000). Web/API/Worker laufen alle auf `d1b2183a`.
---
## 2. Wichtige Erkenntnisse / Gotchas dieser Session
- **E-Mail-i18n ist eine Sackgasse, NICHT aufnehmen.** Untersucht: Transaktionsmails (`packages/mail/src/templates-react/transactional/`) sind **bewusst englisch** — `EmailTemplates.ts:20-36` dokumentiert `t`/`locale` als akzeptiert-aber-ignorierte No-ops; volle i18n wurde von der Phase-10-#75-React-Email-Migration explizit als „coordinated cross-cutting rewrite" verschoben. `mail.json` ist verwaistes Legacy. Sequenz-Mails (`packages/email-templates/src/sequences/*`) sind **totes Gerüst** — der Worker-`renderTemplate` ist ein `throw`-Stub (`email-sequence-runtime.ts:92`), `sendMail` fällt geschlossen. → Kein sauberer i18n-Task hier.
- **#73 a11y-Tooling ist inkonsistent.** `.eslintrc.a11y-baseline.json` verweist auf `scripts/verify-a11y-baseline.mjs` — **existiert nicht**. Scope (`apps/web/app/**`) vs. Rationale (`packages/ui` storybook) widersprüchlich. `anchor-is-valid` (3) / `no-noninteractive-tabindex` (1) reproduzieren sich nicht sauber. Vor #73-P2-Arbeit das Tooling klären/reparieren.
- **`no-autofocus` (88) ist KEIN mechanischer Sweep.** `autoFocus` → `useEffect`-Fokus umgeht nur die Lint-Regel, behebt das a11y-Problem nicht. Echte Lösung = 88 Einzelfall-Urteile (`eslint-disable` mit Begründung vs. entfernen).
- **i18n-Audit zählt auskommentierten Code.** `scripts/i18n-audit.mjs` scannt rohen Source inkl. `{/* */}`-Blöcke. Bei Batch 1 waren 16 von 111 „Treffer" in totem Code — bewusst NICHT migriert. Der enforced Gate (`verify-hardcoded-strings.mjs`) überspringt Kommentarzeilen korrekt. Audit-Floor steht bei 46 (30 gate-excluded Seed/Codegen/Legal-Pages + 16 auskommentiert).
---
## 3. Offener Track-Bestand + Empfehlung
Die sauberen Quick-Wins sind erschöpft. Alles Folgende ist substanziell — ein Track pro fokussierter Session.
| # | Track | Aufwand | Hinweis |
| ----------- | -------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **#38** | Shared-Store: Session-Store sync→async | 2-3 Tage | **HÖCHSTES RISIKO. Eigene saubere Session zwingend.** `apiSessionStore` hat synchrone API (`createSession`/`getActiveSession`/`rotateSession`/`revokeSession`), konsumiert von vielen sync Route-Handlern + JWT-signing-flow. Falsch gemacht = Logout-Storm auf Prod. Nur 1/6 Store offen (rate-limits ×2, idempotency, subscription-cache erledigt). |
| **#42** | Outbox completion | ~1 Woche | call-site migrations, admin UI, CLI re-queue, e2e tests. Admin-UI-Teil braucht Browser-Verifikation. |
| **#73** | WCAG P2 | 3-4 Tage | Erst Tooling reparieren (Section 2). Dann `no-autofocus` (88) per Einzelfall-Urteil. `media-has-caption` (2 in `AudioOrVideoPlayer.tsx`) = generische Komponente, vermutlich justified `eslint-disable`. |
| **#53/#55** | Feature-Flag-Builder / AI-Cost-UIs | je 3-5 Tage | UI-Tracks — brauchen Dev-Server/Browser-Verifikation. |
| **#76** | Test-Coverage ratchet | 5-10 Tage | Per-Modul-Gates hochziehen. |
| **#21/#22** | Plugin Phase 1+2 | 2-3 Wochen | Hot-reload, marketplace, sandboxed iframe, 13 hook-points. |
| **F-002** | WASM per-instruction fuel | mehrere Wochen | Wasmtime-Swap oder worker-thread + wall-clock kill. |
**#72 i18n ist abgeschlossen** (darum nicht mehr im Track-Bestand oben): mechanische Extraction, Namespace-Split (`billing`/`crm`/`auth`/`emailMarketing`) und E2E-Locale-Switch sind erledigt — Commits `a3885ed5` + `fa8b0e70` (Stand 2026-05-22 noch lokal, **nicht gepusht**). **Korrektur zum früheren Stand dieses Dokuments:** „Arabisch" war **nie ein geplanter Track**. Es taucht in `10-compliance-polish/i18n-foundation.md` ausschließlich als Beispiel auf — für Plural-Komplexität (6 Plural-Formen) und als RTL-Begründung. `supportedLngs` ist **DE/EN**; RTL existiert nur als Foundation mit 2 Storybook-Smoke-Tests (`dir="rtl"`-Toggle), siehe `10-compliance-polish/VERIFICATION.md`. Keine `ar`-Locale vorschlagen oder bauen.
**Empfehlung:** Als Nächstes **#38** in einer dedizierten, frischen Session. Sorgfältig: erst alle Call-Sites von `apiSessionStore` kartieren, dann async-Migration mit Tests pro Call-Site, kein Big-Bang.
### Offene Lighthouse-Restpunkte (klein, optional)
- Authentifizierte Routen (`/app/*`, `/admin/*`) werden noch nicht auditiert — braucht einen rotierten Staging-Session-Cookie als CI-Secret. Doku-Pfad in `docs/architecture/lighthouse.md` beschrieben.
- Der `Upload Lighthouse artifacts`-Step meldet `No files found .lighthouseci/` (kosmetisch — Reports liegen auf `temporary-public-storage`, Links im Job-Log).
---
## 4. Bucket-A / Operator-Pending (unverändert)
Historical note only: this 2026-05-21 operator-pending snapshot was superseded by `OPERATOR-CHECKLIST.md` and `PROGRESS.md`. In particular, A7/B2/#51 CDN rollout is now parked in backlog rather than active operator work.
**Bekannte pre-existing Test-Brüche** (nicht von dieser Session): `packages/config/src/env-examples.test.ts` (9 uncataloged `PLUGIN_*` keys), `apps/api`-typecheck (3 pre-existing Errors, nicht push-blocking).
---
## 5. Konventionen (unverändert)
- Alle Commits direkt auf `main`. `git pull --rebase --autostash` vor Workflow-Start (Worktree hat permanenten `packages/db/generated/**`-Churn).
- Lefthook pre-commit (test-density / eslint-baseline / secrets / lint-staged) und pre-push (full `pnpm typecheck`, ~50s) sind hart.
- React Router v7: Route-Type-Imports IMMER `./+types/<name>`, nie relativ.
- Niemals `git add -A` — explizite Paths. Achtung: `packages/db/generated/**` niemals mitcommitten.
- `pnpm`, nicht npm. Tests via `npx vitest run <path>`.
- Co-Author-Trailer: `Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>`
- Push deployt auto via Coolify auf Staging. CI-Status prüfbar via Gitea-DB-Query (siehe `docs/improvement-plan/archive/STAGING-ACCESS.md` Section "CI / Gitea-Actions Runner").
- `lighthouse.yml` triggert NICHT mehr auf Push — bei Bedarf via `workflow_dispatch` auslösen (curl-Command in `docs/improvement-plan/archive/STAGING-ACCESS.md`).
---
## 6. Operator-Profil-Notiz
Operator hat klargestellt: **SEO ist für dieses Produkt irrelevant** (B2B-SaaS, keine Search-Discoverability nötig). Keine Meta-Description-/Sitemap-/Structured-Data-Arbeit vorschlagen. Quality-Gates fokussieren auf Performance.
---
**Ende des Handoffs.** Bei Unklarheit fragen, nicht raten.