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

153 lines
14 KiB
Markdown

# Handoff — Stand 2026-05-24
> **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:** Bucket-1-Abbau + komplett-neue zentrale Observability/Sentry/Meilisearch/Loki-Infrastruktur. Viele Änderungen in der `toolctrl-labs/infra`-Repo (separates Gitea-Repo, NICHT der Boilerplate).
**Ziel des Handoffs:** Nachfolger weiß in 5 Minuten wo wir stehen und was als Nächstes kommt.
---
## 0. Start hier (5-Minuten-Onboarding)
**Lies in dieser Reihenfolge:**
1. Dieses Dokument komplett.
2. `HANDOFF-2026-05-21.md` für den davor liegenden archivierten Stand (#72-i18n + Lighthouse-CI-Rebuild + Worker-Crash-Fix).
3. **Wichtig: das `toolctrl-labs/infra`-Repo auf Gitea.** Die ganze zentrale Infra (Observability, Sentry, Meilisearch, Loki, WireGuard-Mesh) ist DORT dokumentiert, nicht im Boilerplate. Clone via `git clone https://git.tool-ctrl.de/toolctrl-labs/infra` und lies README.md + STANDARDS.md.
4. `.claude/CLAUDE.md` — React-Router-v7-Konventionen, strikt enforced.
**Sofort-Sanity-Check:**
```bash
git log --oneline -6 # HEAD = fa8b0e70, dahinter 1-2 lokale doc-commits dieser session
git status -s # erwartet: packages/db/generated/** churn + ggf. neue handoff/progress edits
git pull --rebase --autostash # andere Agenten arbeiten ggf. parallel
```
**Lokale unpushed Commits beachten:** Schon zu Session-Start lagen 2 Commits vor (`a3885ed5` Namespace-Split, `fa8b0e70` E2E-Locale-Switch für #72) die noch nicht auf `origin/main` sind. Plus die Doc-Edits dieser Session (PROGRESS.md + neues Handoff). Wenn du pushst, deployt Coolify automatisch — bei Doc-Only-Edits unkritisch, aber bewusst entscheiden.
---
## 1. Was diese Session bewegt hat
### 1.1 Bucket-1-Abbau (Operator-Pending-Items)
| Item | Vorher | Jetzt |
| --------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| #41 Read-Replica | „replica-deploy-pending" | als bewusst zurückgestellt dokumentiert (Single-DB-Fallback aktiv, kein Funktionsverlust) |
| #78 Turnstile | nicht aufgesetzt | live aufgesetzt + per Negativ-Test verifiziert. Sicherheits-Fazit: aktuell nicht zwingend nötig weil keine öffentlichen Landingpages, aber Backend ist live |
| #51 CDN | historical rollout parked | **backlogged** — Origin in Nürnberg + DACH-Audience + Cloudflare-Proxy reicht. Reaktivieren wenn internationale Kunden / große Media / Traffic-Spitzen |
| #56 Stripe-Meter | „stripe-account-setup-pending" | **deferred** — noch keine zahlenden Overage-Kunden |
| B3 (bcrypt-rehash) | nie live getestet | **verifiziert** — Login als `staging-admin@saas-ctrl.com` hat den Hash sauber von bcrypt auf argon2 umgesprungen. Dual-Mode-Code aus #28 funktioniert |
| B5 Disk-Alert | „operator-config-pending" | **erledigt** — Coolify-Discord-Webhook aktiviert, Disk-Trigger an |
| #23 Plugin Phase 3 (Cure53) | „operator-audit-pending" | **deferred** — Budget aktuell nicht da. Konsequenz im PROGRESS-Row notiert: Plugin-System geht NICHT in Produktion bis Audit + Sign-off durch sind |
### 1.2 Zentrale Infrastruktur neu aufgebaut
**Was es vorher gab:** je Projekt eigener Side-Stack (Grafana+Prometheus auf Staging, Sentry auf Staging, Meilisearch auf Staging). Skalierte nicht für mehrere SaaS.
**Was jetzt steht:**
- **WireGuard-Mesh** `10.42.0.0/24` mit `control` als Hub, Peers `homeserver` (10.42.0.2), `boilerplate-staging` (10.42.0.3), `node1`/EX44 (10.42.0.4). IP-Forwarding und FORWARD-Chain auf control eingerichtet. ADR 008 im infra-Repo.
- **Zentrales Grafana + Prometheus** auf `control` unter `https://grafana.saas-ctrl.com`. Scrapt jede Host-Node-Exporter + Docker-Stats-Exporter über das Mesh. Vier Project-Dashboards (Boilerplate, saas-ctrl.com, Homeserver, Hetzner Dedicated EX44). Admin-Pass auf `control:~/.cli-tokens/central-grafana-admin`.
- **Zentrales Sentry** auf `node1`/EX44 unter `https://sentry.saas-ctrl.com`. Self-hosted Sentry-Stack hinter Caddy (TLS via Let's Encrypt). Org `sentry`, Team `boilerplate` mit Projekten `api`/`worker`/`web`. Boilerplate-Coolify-Envs zeigen auf neue DSNs + OTEL-Endpoint. SENTRY_AUTH_TOKEN rotiert in Coolify + Gitea-Secrets. Admin-Pass auf `control:~/.cli-tokens/central-sentry-admin`, DSNs unter `central-sentry-dsns`, Auth-Token unter `central-sentry-auth-token`. **Altes Sentry auf Staging läuft noch** — bewusst stehen gelassen, kann jetzt aber abgebaut werden, frisst ~4 GB RAM.
- **Zentrales Meilisearch** auf `node1`/EX44 auf `10.42.0.4:7700`. Boilerplate-Apps zeigen via Coolify-Env auf den neuen. Alter Container auf Staging gestoppt + entfernt, Volume zur Sicherheit behalten. Master-Key auf `control:~/.cli-tokens/central-meilisearch-master-key`. **Beide Instanzen waren leer beim Switch** — niemand hatte auf Staging je Daten geschrieben die in Meili landen würden.
- **Zentrales Loki + Promtail** auf jedem Host. Loki auf EX44 `10.42.0.4:3100`, Promtail auf allen vier Hosts schickt Container-Logs hin. Als Grafana-Datasource registriert. In Grafana → Explore → Loki auswählen → `{server="..."}`-Queries möglich.
**Wichtige Lesson learned:** Docker port-publishing (`-p 10.42.0.4:7700:7700`) mit UFW + Docker-iptables auf EX44 funktioniert NICHT für Traffic von wg-Peers. Mittel zur Wahl auf EX44 ist `--net=host` plus explizites Binding auf die Mesh-IP. Pattern in infra-Repo dokumentiert.
### 1.3 Infra-Repo `toolctrl-labs/infra` massiv erweitert
**Pushes:** `69636e7`, `6d26a84`, `dcf8ca1`, `174b9a9` auf `main`.
- `README.md` — neue Sektionen: Central observability, WireGuard mesh, Central Sentry, Central Meilisearch, Central logs (Loki). Hosts-Übersicht aktualisiert (node1 hat jetzt Sentry, boilerplate-staging hinzugefügt, control hat zentrale Stacks). DNS-Records für grafana.saas-ctrl.com + sentry.saas-ctrl.com.
- `STANDARDS.md` (neu) — verpflichtende Regeln für jeden SaaS im Estate. 11 Sections: zentrale Sentry-Nutzung, Host-Pflicht (Metrics+Logs), Per-Project-Dashboard, zentrale Meilisearch, Admin-SSO über Authentik, Repos in Gitea, Coolify-Konventionen, Cloudflare, Secrets, Backups, ADR-Norm.
- `decisions/008-central-observability-and-sentry.md` (neu ADR) — begründet zentrale Architektur + WireGuard-Mesh (revisiert ADR 004).
- `runbooks/add-host-to-central-observability.md` (neu) — Schritt-für-Schritt für neuen Host ans Mesh + Exporters + Prometheus-Targets.
---
## 2. Was JETZT als Nächstes zu tun ist
### Sofort sinnvoll, Bucket-1-Restposten:
**B7 — Tenant-Snapshot-Verify** ist der einzige Bucket-1-Punkt der noch echt offen ist und den ein Agent ausführen kann. ABER hat zwei Hürden die vorher gelöst werden müssen:
1. Die `toolctrl-cli` ist nicht im Production-Image — auf Staging müsste der Repo geklont und Dependencies installiert werden, oder ein dediziertes CLI-Image gebaut werden.
2. S3/MinIO ist auf Staging nicht installiert. Entweder ein MinIO-Container dazustellen oder ein lokales Filesystem-Backend für die CLI nutzen (falls supportet).
Empfehlung: MinIO auf Staging hinzufügen ist ein 20-Minuten-Job (analog zum Meilisearch-Pattern auf EX44, Host-Network mit Mesh-IP-Bind), dann CLI aus den Repo-Sources laufen lassen, snapshot+restore round-trippen, Row-Counts vergleichen.
**Worker-Groups-Side-Finding (superseded)** — historical 2026-05-24 note: at that point staging only ran the `general` worker group. This was closed by the 2026-05-25 persistent worker-group provisioning; the current staging topology is five separate Coolify worker services (`general`, `mail`, `import`, `webhook`, `plugin`). See `docs/ops/worker-queues.md` and `docs/improvement-plan/archive/STAGING-ACCESS.md`.
### Bucket 2 — Code fertig, nur Live-Verifikation
| # | Task | Was zu tun |
| --- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| #19 | Magic-Link-Reset | Core flow + MailerSend smoke live-grün: token issued, queued, temporary mail worker completed provider send, consumed, replay rejected. **2026-05-25 addendum:** persistent Coolify worker-group provisioning landed; B-014 resolved and #19 closed. |
| #26 | TOTP-MFA | Erledigt 2026-05-24: MFA-Enroll + TOTP-Challenge + Recovery-Code-Challenge + Cleanup auf Staging grün. |
### Bucket 3 — wartet auf Externe
| # | Task | Was hängt |
| --- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| #23 | Plugin Phase 3 | Cure53-Audit budget-deferred (siehe oben). Wenn Geld frei wird: `scripts/build-plugin-audit-package.sh` + Versand an Cure53 (oder Alternativvendor) |
| #65 | Capacitor Mobile | Native Builds brauchen Mac+Xcode+Android-Studio. App-Store + Play-Store Submission. Apple Dev Account ($99/Jahr) + Google Play Console ($25 einmalig) |
### Bucket 4 — echte Code-Arbeit, die großen Tracks
**Kleine deferrte Follow-ups (je < 1 Tag):**
- #20 Magic-Link-Invitation — `User.passwordHash`-nullable-Migration
- #27 Password-Policy — Login-Soft-Banner
- #39 Pub/Sub Cache — Reconnect-Flush + Testcontainers-Integrationstest
**Großtracks (ein Track pro fokussierter Session):**
- **#38** Shared-Store: Session-Store sync→async — 2-3 Tage, **höchstes Risiko**, eigene saubere Session zwingend
- **#42** Outbox completion — ~1 Woche, Call-Site-Migrationen + Admin-UI + CLI re-queue + E2E
- **#53** Feature-Flag-Builder — Visual Rule-Builder-UI + Affected-Count-Endpoint + Kill-Switch + 4 v1-Callsites
- **#55** AI-Cost Phase 2 — Admin- + Tenant-Web-UIs (Engine fertig)
- **#59** Realtime-Collab — Snapshot/Cleanup-Cron + Presence-Bar-UI + Permission-Helper + Rows-/Workflow-Editor-Integration
- **#21 + #22** Plugin Phase 1+2 — Hot-reload, Marketplace, sandboxed iframe, weitere 13 Hook-Points (NICHT prod-rollen ohne Cure53-Audit)
- **#62** Storybook — Lost-Pixel Visual-Regression, Toolbar-Globals, Tailwind-v4-Pipeline
- **#73** WCAG P2 — `no-autofocus` (88) per Einzelfall-Urteil; `verify-a11y-baseline.mjs` muss vorher repariert/erstellt werden
- **#76** Test-Coverage — Per-Modul-Gates auf 85-95% kritische Pfade hochziehen
- **#17** FileObject-Scan-Columns — von Bucket 1 reklassifiziert als echtes Code-Work: Scan-Spalten am `FileObject`-Model fehlen komplett, plus Scan-Result-Persistenz + User-Notification + Audit-Events sind nicht gebaut. Detail-MD `01-tech-debt-foundation/av-scanner-layer-2.md` ist Wahrheit, der Status-String im PROGRESS war irreführend
### Housekeeping (lose Enden dieser Session)
- **Altes Sentry auf Staging stoppen** — `boilerplate-staging:/opt/sentry-stack/` läuft weiter und frisst ~4 GB RAM, obwohl alle Apps schon zum neuen umgelenkt sind. Wenn Verifizierung gesehen wurde dass das neue stabil ist, alten Stack mit `docker compose down` runterfahren. Volume bewusst behalten falls Rollback nötig.
- **2 unpushed `#72`-Commits** auf Boilerplate (`a3885ed5`, `fa8b0e70`). Beide sind sauber, wurden aber nie gepusht. Wenn du sie weghaben willst, einfach `git push`.
- **PROGRESS.md** hat in dieser Session 3 Doc-Edits bekommen (#41/#51/#23 Status-Deferrals). Auch noch nicht committed/gepusht. Ich committe sie zusammen mit diesem Handoff.
- **Coolify-Env-Duplikate** — Coolify's API erzeugt mit PATCH neue Einträge statt zu updaten. Auf den 3 Boilerplate-Apps liegen ein paar duplizierte Envs (z.B. `SEED_ADMIN_EMAIL`/`SEED_ADMIN_PASSWORD`). Funktional fängt Coolify den letzten Wert ab, kosmetisch unsauber. Bei Gelegenheit über die Coolify-API per DELETE aufräumen.
- **Marketing-VM** ist noch nicht im zentralen Monitoring. Kein SSH-Key registriert. Wenn das in den Mesh soll: Runbook in der `infra`-Repo unter `runbooks/add-host-to-central-observability.md`.
---
## 3. Konventionen (unverändert, aber wichtig)
- Alle Commits direkt auf `main`. `git pull --rebase --autostash` vor Workflow-Start.
- 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. `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.
- **NEU: Wenn etwas Infra-mäßig ist, gehört es ins separate `toolctrl-labs/infra`-Repo, nicht ins Boilerplate.** Boilerplate-Repo ist nur für die SaaS-Codebase.
---
## 4. Operator-Profil-Notiz
- B2B-SaaS, SEO irrelevant (alte Note bleibt gültig)
- Antwortstil: kurz, plain, keine Tabellen-Wände, keine Emojis, keine inline-Code-Formatierung für Dinge die nicht Code sind (Pfade, URLs, Env-Var-Namen als Fließtext). Ein Item nach dem anderen abarbeiten, nicht alle Buckets gleichzeitig dumpen.
---
**Ende des Handoffs.** Bei Unklarheit fragen, nicht raten.