212 lines
18 KiB
Markdown
212 lines
18 KiB
Markdown
# 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.
|