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

212 lines
18 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 — 2026-05-26
> **Historical/imported snapshot only (2026-05-25 cleanup).** This file is
> preserved for audit/history even though its title is future-dated relative
> to 2026-05-25. Do not treat its "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). Akkord-Lauf gegen `HANDOFF-2026-05-25.md`, Tasks A–G durchgezogen, gepusht und gegen Staging verifiziert.
---
## 1. Was tatsächlich landed (Task-für-Task)
Push: 30 Commits, `d1b2183a..fb5736b6 main -> main`. Lefthook pre-push (typecheck) durch. Coolify-Webhook hat NICHT automatisch deployed; alle drei Apps wurden manuell via `GET /api/v1/deploy?uuid=…` neu deployed und sind anschließend `running:healthy`.
### Task A — #20 Magic-Link Invitation / passwordHash nullable
- `1d4e6cbe` feat(auth): allow nullable User.passwordHash and route password-less users to magic-link
- `084af35f` docs(improvement-plan): mark #20 password-hash nullable as landed
Schema-Migration `prisma/migrations/20260525000000_01_user_password_hash_nullable/migration.sql` (`ALTER TABLE "User" ALTER COLUMN "passwordHash" DROP NOT NULL`). AuthService liefert für null-passwordHash-User jetzt `{ requiresMagicLink: true, magicLinkHref: "/forgot-password" }` statt durch den Dummy-Hash zu fallen. API `/v1/auth/login` mirror'd den Guard mit generischem `invalid_credentials` (kein Account-Exists-Leak). i18n-Key `errors.passwordlessAccountUseMagicLink` neu in `en/de auth.json`. Neuer Vitest-Spec `AuthService.passwordless.test.ts` + Anpassungen an `verifyPassword`-Signatur (`string | null` akzeptiert deterministisch `{ valid: false }`). 27/27 Auth-Suiten grün. **Operator-Folgeschritt:** `prisma migrate deploy` gegen Staging-DB (lief lokal nicht; nur Files committed).
### Task B — #27 Password-Policy Login Soft-Banner
- `a1c4532b` feat(auth): add password-policy soft-check banner after login
- `8003c641` docs(improvement-plan): mark #27 password-policy login soft-banner as landed
Login-Action ruft nach erfolgreichem Credential-Verify `validatePassword(plain, { email })` im Non-Throwing-Mode auf; bei `!valid` setzt sie das Session-Flag `passwordPolicyOutdated`. `app.$tenant.tsx`-Loader liest Session + `pwPolicyRemindAfter`-Cookie via neuem `evaluatePasswordPolicyBanner`-Helper und rendert `PasswordPolicyBanner` (Warn-Tone aus existierendem `WarningBanner`-Palette) oberhalb des `<Outlet />`. "Remind me in 7 days" geht an `api.password-policy-remind` Resource-Route, setzt `Set-Cookie: pwPolicyRemindAfter=<ms>; Path=/; Max-Age=604800; SameSite=Lax` und gibt 204 zurück. 18 neue Vitest-Tests (13 banner-decision + 3 AuthService-soft-check + 2 resource-route).
### Task C — #39 Pub/Sub Reconnect-Flush + Testcontainers
- `47c37b88` feat(shared-store): flush L1 caches on redis reconnect
- `f4b290bb` test(shared-store): real-redis testcontainers integration for two-tier cache
- `1f68080f` chore(shared-store): rename unused buildClient role param to \_role
- `deb45ffb` docs(improvement-plan): mark #39 reconnect-flush + testcontainers landed
`SharedStoreAdapter` bekommt `onReconnect(handler): () => void`. `RedisAdapter` lauscht ioredis-`'ready'`-Event, überspringt den initialen Connect-Handshake und fanned subsequente Reconnects in registrierte Handler. `MemoryAdapter` no-op. `createTwoTierCache().subscribe()` registriert debouncten `flushLocal()` (default 1000 ms, konfigurierbar via `reconnectFlushDebounceMs`). Logger-Zeile auf INFO: `"two-tier cache <namespace>: redis reconnected, L1 flushed"`. Neue Opt-in-Test-Suite `two-tier-cache.testcontainers.test.ts` mit drei Szenarien (cross-instance Fan-out, Reconnect-Flush, Peer-L2-Mutation-nach-Reconnect); lief live gegen `redis:7-alpine` (OrbStack), alle drei grün ~4 s. `testcontainers@^10.28.0` als devDep des shared-store-Pakets. Detail-MD-Deviations: zwei Bullets als resolved markiert.
### Task D — #42 Outbox (Stripe-Webhook + CLI + E2E)
- `0bebef90` feat(outbox): migrate stripe webhook to outbox pattern
- `9e40294f` feat(cli): add outbox requeue command for failed and bulk replay
- `a5ac964b` test(outbox): end-to-end integration via real postgres opt-in
- `e5cfaf93` docs(improvement-plan): record #42 stripe migration + cli + e2e
Stripe-Webhook in `apps/api/src/billing/stripe-webhook-route.ts` wrappt `updateTenantSubscriptionProductFromStripe` + `publishOutboxEvent` in ein einziges `prisma.$transaction`. Der frühere `callLegacyEvent`-Direkt-Aufruf lebt jetzt im neuen `apps/worker/src/jobs/legacy-event-receiver.ts`, geschützt durch `withOutboxIdempotency`. Bootstrap registriert den Receiver auf `outbox.notification`. CLI: `toolctrl-cli outbox requeue --event-id=…` (akzeptiert nur FAILED/DONE) und `outbox requeue --type=… --since=…` für Bulk. E2E-Suite `packages/db/src/outbox-e2e.test.ts` lief live gegen lokales Postgres (3/3 grün): Publisher → Dispatcher-Tick → Receiver schreibt Marker-Event, Idempotenz beim zweiten Tick verifiziert. 15 neue CLI-Tests, 9 Receiver-Tests. **Deferred (mit Acceptance-Kriterien in der Detail-MD):** WorkflowEngine-Migration, Mail/Webhook/Notification/Audit-Migrationen aus Web-Actions, Admin-UI `/app/admin/outbox` — jede Domain ein eigener Code-Review-Cycle. Foundation steht; die Folgeschritte sind mechanisch.
> **Superseded status note (2026-05-28):** This archive entry reflects the
> 2026-05-26 handoff state. Later work reconciled the workflow-trigger/outbox
> path and worker bootstrap. Use current `PROGRESS.md` plus
> `docs/ops/worker-queues.md` for live workflow/outbox status.
Latent-Bug dokumentiert: `publishOutboxEvent`-Recovery-Pfad (Unique-Violation → findUnique innerhalb derselben Tx) funktioniert nicht in derselben Transaktion (PG markiert die Tx aborted). In Production ist jeder Publish eine eigene Tx, deshalb harmlos. Nicht gefixt.
### Task E — #76 Coverage-Gates Audit + targeted wins
- `29736f59` chore(coverage): backfill per-module gate entries for untracked packages
- `d0478a73` docs(testing): record 2026-05-25 critical-path coverage baseline
- `9f86f2d1` test(api/auth): graduate apps/api/src/auth coverage gate to 99/92
- `fd7a23cc` test(entitlements): graduate packages/entitlements coverage gate to 96/90
- `3f5ecd15` docs(testing): publish coverage-sprint backlog for #76 follow-up sessions
- `a532c8cb` docs(improvement-plan): #76 baseline + backlog landed; sprint still deferred
- `b1155126` chore(coverage): pin new-entry gates to current achievement levels
`scripts/coverage-targets.json` erweitert auf 50 Einträge (vorher 22 — 28 untracked Packages bekamen konservative Baselines mit sprintTarget 80). 2026-05-25-Baseline mit per-Modul-Tabelle in `docs/testing/coverage-baseline-2026-05-25.md`, sortiert nach kleinstem Gap zu sprintTarget. Zwei Critical-Path-Module von "graduated" auf gebumptes Gate gehoben: `apps/api/src/auth` (99.2 % stmt / 92.2 % br) und `packages/entitlements` (97.0 % / 90.8 %). Backlog-File `docs/testing/coverage-sprint-backlog.md` für die nächste Session — größte Lücken: `apps/web/app/utils/db/tenants.db.server.ts` (2.9 %), `apps/web/app/utils/stripe.server.ts` (3.5 %), `apps/web/app/utils/db/permissions/**` (15.9 %). Coverage-Run-Budget: ~136 s.
In passing entdeckt: `pnpm test` und der Coverage-Gate laufen auf unterschiedlichen Scopes; drei Test-Failures (`apps/api/src/app.test.ts` Stripe-Webhook, `packages/config/src/env-examples.test.ts`, `packages/cli/src/commands/tenant/json-codec.test.ts` Buffer JSON) tauchen nur unter Coverage auf. Documented im Backlog, nicht gefixt.
### Task F — #62 Storybook (Toolbar-Globals + Tailwind v4 + Baselines)
- `76732977` feat(storybook): add locale + theme toolbar globals with i18n decorator
- `24ee3bd9` build(storybook): wire real tailwind v4 + project token css pipeline
- `d370c5a3` chore(storybook): commit lost-pixel baseline snapshots
- `30435fbb` docs(improvement-plan): record #62 toolbar-globals + tailwind + baseline progress
Locale-Toolbar-Global (en/de) verdrahtet via `@storybook/addon-themes` mit react-i18next-Instanz; Translation-Files lazy via `import.meta.glob` aus `apps/web/public/locales/**`. Theme-Switch bleibt am bestehenden `withThemeByClassName`-Decorator (Single Source of Truth). Tailwind-v4-Pipeline lief auf Anhieb sauber: `viteFinal`-Hook lädt `@tailwindcss/vite`, `preview.css` `@import "tailwindcss"` + `@custom-variant dark` — `pnpm --filter @toolctrl/storybook build-storybook` exit 0 in 3 s. 67 Lost-Pixel-Baseline-PNGs (~800 kB) unter `apps/storybook/.lostpixel/baseline/`; Re-Run `visual-regression` 67/67 no-diff. Einmaliges Bootstrap nötig: `node …playwright-core/cli.js install chromium-headless-shell` (system-cache hatte v1217/1169, lost-pixel braucht v1223) — dokumentiert. **Deferred (Acceptance je 1 Zeile in Detail-MD):** Brand- + ui-layer-Toolbar-Globals (keine Stories nutzen sie heute), Coolify static-deploy (`storybook.staging.toolctrl.de`, operator-only), Migration der 21 Demo-Primitive-Stories auf echte Components.
### Task G — Tenant-Snapshot Global-Row Extractor (#44 B7-Limit)
- `e9fe18fc` feat(cli): enumerate globals referenced by tenant-scoped models
- `6e0aafa3` feat(cli): include globals/<Model>.jsonl in tenant snapshots
- `a4cdf6ef` feat(cli): replay globals first on tenant restore with upsert/skip/error modes
- `27cad89d` test(cli): round-trip restore into truly empty pgvector DB
- `fb5736b6` docs(ops): close tenant-snapshot globals design-limit (#44 Task G)
`User` ist der einzige extrahierte Global (38 FK-Spalten aus 31 tenant-scoped Models in `GLOBAL_REFERENCED_MODELS`). Sieben weitere FK-Targets (`Entity`, `EntityGroup`, `Formula`, `Onboarding`, `PromptFlow`, `RowComment`, `WorkflowBlock`) sind als `PLATFORM_CATALOG_GLOBALS` deklariert und bewusst nicht im Snapshot — sie werden per Migration/Setup einmal pro Deployment geseeded. Test `models.test.ts:73-95` parsed jede Schema-FK-Relation und failed CI wenn ein neuer Global nicht explizit in eine der zwei Listen einsortiert wird. Restore-Flag `--globals=upsert|skip|error` (default `upsert`). Anonymizer scrubt `email`, `firstName`, `lastName`, `phone`, `avatar` plus credentials (`passwordHash`, Verify-Token, OAuth-IDs, TOTP-Secrets, MFA-Recovery-Codes). Round-Trip-Integration-Test lief live gegen zwei pgvector-Container (`pgvector/pgvector:pg16` auf 55801/55802), 138 Migrationen applied, 365/365 grün — die 6 vorher-broken Models (TenantUser/TenantIpAddress/UserRole/Event/Log/SupportTicket) restoren clean. Runbook `docs/ops/tenant-snapshot.md` Sektion umbenannt von "Restore prerequisites: global rows are NOT in the snapshot" zu "How globals are handled in restore" mit Mode-Tabelle + Backward-Compat-Hinweis (Pre-Task-G-Snapshots ohne `globals/` werden mit Warning weiterhin akzeptiert).
---
## 2. Deploy + Verifikation
**Push:** `d1b2183a..fb5736b6 main -> main`, 30 Commits. Lefthook pre-push (i18n 0.76 s + typecheck 39.01 s) grün.
**Gitea:** `git ls-remote origin main` → `fb5736b63f81c48fca801b35e18f9cc990d79f25`. HEAD synchron.
**Coolify-Deploy:** Webhook hat NICHT automatisch deployed (alle drei Apps standen noch auf `d1b2183a` mit `is_webhook: false` als jüngste Deployments). Manuell getriggert via `GET /api/v1/deploy?uuid=…` mit Bearer-Token aus `~/.cli-tokens/coolify-token`. Alle drei Deploys reached `status: finished` innerhalb ~3 Minuten. Final-Status alle `running:healthy`:
- `boilerplate-web` (mrf8lj70kmy9hqprx9dd6w7q) — Container `…-045356223784`, Up About a minute (healthy)
- `boilerplate-api` (e109dzc3xzjxi54llfje4tob) — Container `…-045356524191`, Up About a minute (healthy)
- `boilerplate-worker` (k6cibn0rkrrl7izw970ao1l4) — Container `…-045416128858`, Up About a minute (healthy)
> 2026-05-26 status note: this three-app deploy observation is historical.
> Current deploy docs supersede the single `boilerplate-worker` setup with five
> persistent Coolify worker applications: `worker-general`, `worker-mail`,
> `worker-import`, `worker-webhook`, and `worker-plugin`. `worker-mail` owns
> `WORKER_QUEUE_GROUP=mail`; use `docs/ops/worker-queues.md`,
> `docs/worker.md`, and `docs/deployment.md` as the current topology sources.
**Open Frage für Operator:** Warum hat der Gitea-Webhook nicht ausgelöst? Vorherige Deploys (`535`, `536`, `537` vom 2026-05-24 00:31) waren ebenfalls `is_webhook: false`. Coolify-Auto-Deploy-Toggle in der UI prüfen oder Gitea-Webhook-Logs.
**Smoke-Tests (HTTP):**
- `GET https://boiler.saas-ctrl.com/login` → 200, HTML enthält `<title>Anmelden | Boilerplate</title>` + `name="email"` + `name="password"`
- `GET https://boiler.saas-ctrl.com/healthz` → 200
- `GET https://api.boiler.saas-ctrl.com/healthz` → 200
- `GET https://api.boiler.saas-ctrl.com/v1/health` → 200
- `GET https://admin.boiler.saas-ctrl.com/` → 302 (Login-Redirect, erwartet)
- `app.boiler.saas-ctrl.com` — keine Antwort; Subdomain existiert evtl. nicht, alle tenant-Routes laufen unter `boiler.saas-ctrl.com/app/<tenant>`. Nicht weiter verfolgt.
**Smoke-Test (Browser, Playwright):** `boilerplate-staging-admin`-Credentials genutzt, Chromium headless. Login-Form ausgefüllt, submit → keine MFA-Prompt (TOTP-Secret war verfügbar, aber Server fragte nicht) → final URL `https://admin.boiler.saas-ctrl.com/dashboard`, Title `Dashboard | Boilerplate`. Screenshots:
- `/tmp/staging-smoke-01-login.png` (Login-Form, 29 kB)
- `/tmp/staging-smoke-03-dashboard.png` (Admin-Dashboard nach Login, 160 kB)
Hinweis: MFA wurde nicht abgefragt obwohl der Account ein TOTP-Secret hat. Entweder ist MFA für Staging-Admin in der DB nicht aktiviert, oder es gibt einen Remember-Me-State im Browser-Context. Nicht weiter untersucht — Login-Flow ist funktional.
---
## 3. Was deferred wurde + Grund
### Task D — bewusst nicht in dieser Session
- **Admin-UI `/app/admin/outbox`** — Operator-Handoff sagt explizit "Bewusst raus: Design-Entscheidung"
- **WorkflowEngine-Trigger-Migration (Step 6)** — eigene Engine-Semantik, eigener Code-Review-Cycle
- **Mail/Webhook/Notification/Audit-Migration aus Web-Actions (Steps 7-9)** — pro Domain ein Migration-Commit + Receiver-Worker, jeweils mit Playwright-Assertion (Worker-Crash zwischen DB-Commit und Queue-Pop liefert Side-Effect nach Restart). Foundation steht; mechanisch.
> **Superseded status note (2026-05-28):** WorkflowEngine-trigger migration is
> no longer represented solely by this deferred list. Check current progress
> and worker queue docs before treating this archive as actionable work.
### Task E — Coverage-Sprint
Die 2-3-Wochen-Sprint-Arbeit (Steps 4-12 der Detail-MD) ist explizit weiter `deferred-with-backlog`. Größte Lücken zu Critical-Path-Sprintzielen:
- `apps/web/app/utils/db/tenants.db.server.ts` — 92.1 pp Statement-Gap
- `apps/web/app/utils/stripe.server.ts` — 81.5 pp
- `apps/web/app/utils/db/permissions/**` — 74.1 pp
- `apps/api/src/billing` — 12.9 pp Branch-Gap (stmt past)
- `apps/api/src/isolation` — 23.3 pp Branch-Gap (stmt 100 %)
Backlog mit One-Line-Hints in `docs/testing/coverage-sprint-backlog.md`. Drei Test-Failures unter Coverage-Scope (siehe Task-E-Block) sollten zuerst gefixt werden — sonst kann der Gate-Script nicht zu Ende laufen.
### Task F — Storybook
- Brand- + ui-layer-Toolbar-Globals — werden no-op solange keine Story sie nutzt
- Coolify static-deploy für `storybook.staging.toolctrl.de` — Operator-Auth
- Demo-Primitive-Stories → echte Components migrieren — Tailwind-Pipeline ist jetzt da, also unblocked
### Pre-existing Failures (unverändert)
- `apps/web/app/application/ui/uiInventory.test.ts > maps all stable registry surface, action and nav IDs` — vom Operator dokumentiert als "allowed pre-existing"; nicht angefasst
- Drei Coverage-only-Failures siehe oben
> 2026-05-26 status note: this failure list is historical. A later focused run
> of the listed coverage-only suites plus `packages/ai/src/index.test.ts`
> passed (200 tests total), and `PROGRESS.md` now records that those
> coverage-only failures no longer reproduce.
---
## 4. Was als Nächstes ansteht
Geordnet nach Wert × Risiko-niedrig:
1. **`prisma migrate deploy` gegen Staging-DB für Task A.** Schema-Migration `20260525000000_01_user_password_hash_nullable` ist nur committed, nicht angewandt. Bis dahin ist der `passwordHash`-Spalt in Staging weiter NOT NULL, der neue Code arbeitet aber gegen ein nullable-erwartendes Schema. Funktional kein Bruch (alle existierenden User haben einen Hash), aber sauberer wäre apply.
2. **Coolify Gitea-Webhook reparieren.** Auto-Deploy hat in dieser Session nicht ausgelöst. Mögliche Ursachen: Webhook-URL-Drift in Gitea, Auto-Deploy-Toggle in Coolify aus, Webhook-Secret-Mismatch. Bis dahin müssen Deploys manuell getriggert werden.
3. **Outbox-Migrationen schrittweise nachziehen.** Mail/Webhook/Notification/Audit pro Domain ein PR. Acceptance pro PR siehe `docs/improvement-plan/03-scaling-infrastructure/outbox-pattern.md` "Deviations from Plan".
4. **Coverage-Sprint-Backlog abarbeiten.** Eine eigene Session pro Critical-Path-Modul, starten bei `apps/api/src/isolation` (kleinster Branch-Gap, Stmt-Coverage schon 100 %).
5. **Storybook: echte Components statt Demo-Primitives.** Tailwind-Pipeline ist da, Lost-Pixel-Baseline existiert — Migration ist jetzt sicher.
6. **Coolify-Static-Site `storybook.staging.toolctrl.de`** — Operator-Setup.
---
## 5. Misc
- 30 Commits durchgängig mit `Co-Authored-By: Claude Opus 4.7 (1M context)` Trailer.
- Lefthook pre-commit (test-density, eslint-baseline, lint-staged, secrets) lief auf jedem Commit grün.
- Keine generierten Prisma-Client-Files committed; `git status` zeigt vor + nach Push den gleichen Set von 9 modified + 1 untracked unter `packages/db/generated/`.
- Live-Integration-Tests gegen Docker liefen für Task C (Redis), Task D (Postgres), Task G (zwei pgvector-Container).
- `docs/improvement-plan/PROGRESS.md` Row-Aktualisierungen pro Task durchgeführt.
## 6. 2026-05-25 Follow-up Sync
- Generated Prisma client drift from this handoff was committed in `98d42332`
(`chore: sync generated prisma client`); worktree was clean afterward.
- Persistent Coolify worker-group provisioning closed B-014: staging now runs
separate persistent `general`, `mail`, `import`, `webhook`, and `plugin`
worker apps. This supersedes the earlier three-app deploy observation.
#19 Magic-Link Secondary-Flow is marked completed because `toolctrl.email`
jobs no longer require a manual temporary mail worker.
- Operator/checklist docs were bucket-synced: A has 3 open quick wins, B has
7 open medium operator items, C has 3 long-running external items, and D has
8 remaining engineering-polish sprints after D7/D8 closure.
Ende.