Track HiveGrid Cloud planning reference
This commit is contained in:
1 parent
b3d5ea6764
commit
e341c5938a
5784 files changed
+1104929
-3
No files matched your search
@@ -0,0 +1,305 @@
|
||||
# Phase 03 — Verification Report (Skalierungs-Infrastruktur)
|
||||
|
||||
> **Historical verification snapshot:** this report reviewed the original
|
||||
> 2026-05-16 plans before implementation. It is retained for audit context,
|
||||
> not live task status. Current truth for #42 workflow outbox, #45 worker
|
||||
> topology, and #51/A7/B2 CDN backlog lives in `PROGRESS.md`,
|
||||
> `OPERATOR-CHECKLIST.md`, `docs/architecture/outbox-pattern.md`,
|
||||
> `docs/ops/worker-queues.md`, and `docs/ops/asset-cdn.md`.
|
||||
|
||||
**Verifier:** Opus 4.7 (1M context), READ-ONLY
|
||||
**Geprüfte Dateien (13):** README.md + 12 Task-Detail-MDs
|
||||
**Datum:** 2026-05-16
|
||||
**Gesamt-Verdikt:** **GO mit kleinen Auflagen.** Die Phase ist inhaltlich exzellent strukturiert, technisch fundiert und konsistent mit den User-Wünschen. Vor Start sollten ein paar punktuelle Schwächen (siehe Section „Mandatory Fix vor Start") adressiert werden. Die meisten Findings sind aber Nuancen/Wünsche, kein Showstopper.
|
||||
|
||||
---
|
||||
|
||||
## 1. Template-Konformität
|
||||
|
||||
| Datei | Frontmatter | Problem | Depends on | Blocks | Approach | Steps | Tests | Acceptance | Rollback | Security | Subagents | Staging | Deviations | Progress | Lessons |
|
||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
||||
| shared-store-package.md | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||
| shared-store-migration.md | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||
| pubsub-cache-invalidation.md | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||
| pgbouncer.md | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||
| read-write-split.md | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||
| outbox-pattern.md | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||
| worker-queues.md | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||
| streaming-exports.md | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||
| job-priority.md | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||
| backup-cli.md | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||
| tenant-snapshot.md | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||
| asset-cdn.md | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||
|
||||
**Befund:** Alle 12 Detail-MDs erfüllen die 15 Pflicht-Sections in der durch `DETAIL-MD-TEMPLATE.md` vorgegebenen Reihenfolge. README.md beinhaltet die Übersicht inkl. Done-Definition + ist konsistent mit `00-execution-order.md`.
|
||||
|
||||
---
|
||||
|
||||
## 2. Dependencies-Konsistenz
|
||||
|
||||
### Innerhalb der Phase
|
||||
|
||||
| Erwartete Reihenfolge | Im File deklariert | OK? |
|
||||
|---|---|---|
|
||||
| shared-store-package → shared-store-migration | ✓ Migration depends on Package | ✓ |
|
||||
| shared-store-migration → pubsub-cache-invalidation | ✓ Pub/Sub depends on Migration + Package | ✓ |
|
||||
| pgbouncer → read-write-split | ✓ R/W depends on PgBouncer | ✓ |
|
||||
| read-write-split → outbox-pattern | ✓ Outbox depends on R/W (publishOutboxEvent läuft auf prismaWrite) | ✓ |
|
||||
| worker-queues → streaming-exports | ✓ Streaming-Exports depends on Worker-Queues (worker-import-Pool) | ✓ |
|
||||
| outbox-pattern → job-priority | ✓ Dispatcher nutzt BullMQ-Priority | ✓ |
|
||||
| backup-cli → tenant-snapshot | ✓ Tenant-Snapshot reuses Backup-CLI-Infra | ✓ |
|
||||
|
||||
**Alle Sub-Dependencies innerhalb Phase 03 sind sauber deklariert und zirkuläre Dependencies sind ausgeschlossen** (verifiziert durch manuelle Topo-Sort).
|
||||
|
||||
### Phase-02-Dependencies (Sentry/Metrics)
|
||||
|
||||
| Datei | Phase-02-Dependency genannt? |
|
||||
|---|---|
|
||||
| shared-store-package.md | sentry-wiring-api-worker.md, logging-migration.md ✓ |
|
||||
| shared-store-migration.md | logging-migration.md ✓ |
|
||||
| pubsub-cache-invalidation.md | sentry-wiring-web.md ✓ |
|
||||
| pgbouncer.md | metrics-grafana.md ✓ |
|
||||
| read-write-split.md | metrics-grafana.md ✓ |
|
||||
| outbox-pattern.md | sentry-wiring-api-worker.md ✓ |
|
||||
| worker-queues.md | sentry-wiring-api-worker.md, metrics-grafana.md ✓ |
|
||||
| streaming-exports.md | metrics-grafana.md ✓ |
|
||||
| job-priority.md | metrics-grafana.md ✓ |
|
||||
| backup-cli.md | dep-updates.md, sentry-selfhost-setup.md ✓ |
|
||||
| tenant-snapshot.md | supabase-removal.md, shared-store-package.md ✓ |
|
||||
| asset-cdn.md | dep-updates.md, performance-quickwins.md ✓ |
|
||||
|
||||
**Verdikt:** Jede Datei deklariert mindestens eine Phase-02-Dependency wenn relevant. Konsistent mit User-Wunsch „Sentry/Metrics für Skalierungs-Monitoring".
|
||||
|
||||
**Minor Finding:** `shared-store-migration.md` deklariert keine direkte Phase-02-Dependency außer logging-migration.md. Streng genommen wäre `sentry-wiring-*` auch hier sinnvoll, weil bei Rate-Limit-Migration produktive Probleme schnell sichtbar werden müssen. Praktisch transitiv abgedeckt über `shared-store-package.md`. **Kein Blocker.**
|
||||
|
||||
---
|
||||
|
||||
## 3. Implementation-Steps-Qualität
|
||||
|
||||
### Prisma `$extends` für R/W-Split
|
||||
|
||||
**Verdikt:** Technisch korrekt. Das in `read-write-split.md` skizzierte Pattern entspricht dem offiziellen Prisma-Pattern aus den 5.x-Docs. `client.read` / `client.write` via `$extends({ client: { get read() {...}, get write() {...} }})` ist sauberer Idiom. Type-Safety bleibt erhalten weil beide Clients dieselbe schema-generierte Type-Signatur haben.
|
||||
|
||||
**Kritisches Detail (kein Finding, eher Hinweis):** Der Code im Approach (Zeile 51-58) returnt `prismaWrite.$extends({...})`. Damit ist `prisma` selbst = der extended Write-Client. Aufrufer die nur `prisma.user.findMany()` machen (ohne `.read` / `.write`), landen auf Write-Client. Das ist by-design und konsistent mit der Konvention „Default = sicher = Write". Der ausführende Agent sollte das beim Migrieren beachten — explizit dokumentiert in Steps 4-9.
|
||||
|
||||
### PgBouncer transaction-mode + DIRECT_URL
|
||||
|
||||
**Verdikt:** Korrekt. Prisma-Spezifika sind vollständig erfasst:
|
||||
- `pgbouncer=true` in DATABASE_URL disabled prepared-statements (kritisch für transaction-mode) ✓
|
||||
- `directUrl` in `schema.prisma`-Datasource für Migrations ✓
|
||||
- `connection_limit=10` reduziert Prisma-internen Pool ✓
|
||||
- `server_reset_query = DISCARD ALL` für Cross-Tenant-Safety ✓
|
||||
|
||||
**Minor:** Die Detail-MD erwähnt nicht explizit, dass mit Prisma 5.10+ auch `?statement_cache_size=0` als Alternative zu `pgbouncer=true` möglich ist. Für die hier gewählte Lösung egal, aber ein Operator-Hinweis im Doku-Output (Step 8) könnte das ergänzen. **Kein Blocker.**
|
||||
|
||||
### Outbox-Pattern mit OutboxEvent-Model
|
||||
|
||||
**Verdikt:** Schema ist sinnvoll und production-tauglich. `dispatchKey`-Unique-Constraint für Idempotency, `priority`-Spalte für #47 (Forward-Reference!), `scheduledAt` für Delays. Drei Indizes decken die Dispatcher-Queries (status+scheduledAt, tenant+type, dispatchKey).
|
||||
|
||||
**Sehr gut:** `FOR UPDATE SKIP LOCKED` für Multi-Dispatcher-Safety (Step 3, Zeile 159). Das ist der idiomatische Postgres-Pattern für High-Concurrency-Outbox.
|
||||
|
||||
**Finding (Mandatory):** Im Approach (Zeile 84) steht „Wird **nur innerhalb einer Transaction** aufgerufen — Typ-Constraint verhindert direkte Nutzung gegen `prisma`-Singleton." — Die `Prisma.TransactionClient`-Type ist allerdings strukturell gleich zu `PrismaClient` (Duck-Typing in TS). Der „Constraint" ist nicht hart durchsetzbar via TS-Types. Empfehlung: Im Implementation-Step (Step 2) zusätzlich einen Runtime-Check ergänzen, z.B. via Branding `tx as Prisma.TransactionClient & { __tx: true }`, oder zumindest in Code-Review-Section deutlich machen dass „accidentally pass non-tx" möglich ist. **Empfohlen vor Start: Detail-MD um diese Klarstellung ergänzen.**
|
||||
|
||||
**Finding (Minor):** OutboxEvent-Retention ist als Security-Note (Zeile 324) erwähnt („completed Events nach 30 Tagen löschen"). Sollte aber explizit als Implementation-Step oder Acceptance-Criterium auftauchen (Cron-Job für Retention). Aktuell nur als Env-Var `OUTBOX_RETENTION_DAYS=30` (Zeile 361) aufgeführt — Implementierung des Cleanup-Jobs fehlt im Step-Catalog.
|
||||
|
||||
### BullMQ-Worker-Trennung via WORKER_QUEUE_GROUP env
|
||||
|
||||
**Verdikt:** Pragmatisch und sauber. Single-Codebase mit Env-Selector vermeidet Code-Duplication. Group-Mapping in `packages/queue/src/groups.ts` mit Exhaustiveness-Check (Step 1, Zeile 69) ist der richtige Type-Safety-Hebel. Superseded topology note: the current deployed shape has five isolated worker services (`general`, `mail`, `import`, `webhook`, `plugin`) with health ports 9101-9105; the original four-group wording below is historical.
|
||||
|
||||
**Finding (Minor):** Step 7 sagt „Producer-Sites unverändert lassen — kein Change". Aber: in `outbox-pattern.md` Step 4 (event-router) gibt's das Routing `'workflow.': 'workflow'` und `'search.index.': 'search-index'`. Historical note: this finding referred to an early four-group mapping table; the current canonical runbook is `docs/ops/worker-queues.md`, including the fifth `plugin` group. The remaining useful cleanup is only to clarify future domain-queue ownership (`workflow`/`search-index`) when those producers are implemented.
|
||||
|
||||
### Streaming-Exports via ExcelJS-Stream-Writer + @react-pdf-renderToStream
|
||||
|
||||
**Verdikt:** Realistisch und richtig. ExcelJS hat `WorkbookWriter` für Streaming-XLSX (limitiert — kein Cell-Re-Reading, was die 50k-Threshold-Strategie sinnvoll macht). `@react-pdf/renderer` hat `renderToStream` als offizielle API. Der 5k-Hard-Cap für PDF ist UX-defensiv (sehr richtig, ein 50-Seiten-PDF ist unnavigierbar).
|
||||
|
||||
**Sehr gut:** Plan-basierte Caps (Free=10k, Pro=100k, Enterprise=unlimited) — exakt nach User-Wunsch.
|
||||
|
||||
**Finding (Minor):** Step 6 (Worker-Job-Refactor) erwähnt „Stream Rows via Prisma-Cursor-Iteration (`prisma.row.findMany` in Chunks von 1000 mit Skip-Take oder besser `cursor`-based)". Skip-Take wird bei großen Tabellen exponentiell langsamer (Postgres muss N Rows skippen). Empfehlung: Vor Start explizit „cursor-based, nicht skip-take" festlegen. **Empfohlen vor Start:** „Skip-Take oder cursor-based" → „cursor-based pflicht ab N=10000".
|
||||
|
||||
---
|
||||
|
||||
## 4. Test-Requirements
|
||||
|
||||
### testcontainers-Pattern für Redis/Postgres
|
||||
|
||||
| Datei | testcontainers? |
|
||||
|---|---|
|
||||
| shared-store-package.md | ✓ `@testcontainers/redis` explizit |
|
||||
| shared-store-migration.md | ✓ Multi-Replica-Test |
|
||||
| pubsub-cache-invalidation.md | ✓ Multi-Process |
|
||||
| pgbouncer.md | ✓ Postgres + PgBouncer |
|
||||
| read-write-split.md | ✓ optional, gated `TEST_REPLICA=1` |
|
||||
| outbox-pattern.md | ✓ Postgres + Redis + Mail-Mock |
|
||||
| worker-queues.md | ✓ Test-Redis |
|
||||
| streaming-exports.md | ✓ Postgres + Redis + MinIO |
|
||||
| job-priority.md | ✓ Test-Redis |
|
||||
| backup-cli.md | ✓ Postgres + MinIO |
|
||||
| tenant-snapshot.md | ✓ testcontainers |
|
||||
| asset-cdn.md | n/a (External-Service) |
|
||||
|
||||
**Verdikt:** testcontainers ist konsequent als Pattern dokumentiert. Gate über `TEST_REDIS=1` / `TEST_REPLICA=1` (für teure Tests) ist sinnvoll.
|
||||
|
||||
### Multi-Process-Tests für Pub/Sub
|
||||
|
||||
**Verdikt:** Sauber in `pubsub-cache-invalidation.md` Step 9 (Zeile 144-147) — zwei Subscriber-Instances + ein Publisher, alles in einem Test-Process via in-process-Spawning, gegen einen Redis-Container. Reconnect-Verhalten (kill Redis + restart) explizit getestet.
|
||||
|
||||
**Finding (Minor):** Es wäre noch besser, einen tatsächlichen Multi-Process-Test (via `node:cluster` oder `child_process.fork`) zu haben, weil EventEmitter-basierte „Multi-Instance"-Tests im selben Prozess potenziell Bugs verstecken die nur cross-process auftreten (z.B. Connection-Pool-Sharing). Aktuell akzeptabel, weil ioredis korrekt Connection-Isolation hat.
|
||||
|
||||
---
|
||||
|
||||
## 5. Staging-Deployment-Steps
|
||||
|
||||
| Aspekt | Abgedeckt? |
|
||||
|---|---|
|
||||
| Coolify PgBouncer-Setup | ✓ pgbouncer.md Step 2 (Coolify-Service-Definition) |
|
||||
| Redis Logical DBs (0/1/2) | ✓ README + shared-store-package.md explizit (BullMQ=0, Store=1, Pub/Sub=2) |
|
||||
| Sentry-Relay/OTLP-Anpassung | ⚠ Nicht explizit für Phase 03 — wird transitiv über Phase-02-Deps adressiert |
|
||||
| docker-compose-Snippets | ✓ alle Tasks mit Container-Setup haben Snippets |
|
||||
| Health-Checks pro Service | ✓ pgbouncer (healthcheck.sh), worker-queues (/healthz, /readyz), Outbox-Dispatcher implizit |
|
||||
| k6-Last-Tests | ✓ pgbouncer.md, read-write-split.md, streaming-exports.md, job-priority.md |
|
||||
|
||||
**Finding (Minor):** „Sentry-Relay-Anpassung für OTLP" wird in keiner Phase-03-Datei explizit angepasst. Das ist allerdings korrekt, weil Sentry-OTLP-Forwarding in Phase 02 (`opentelemetry.md`) etabliert wird — Phase 03 nutzt nur. Wenn neue Metriken aus Phase 03 (z.B. PgBouncer-Exporter, BullMQ-Job-Counter) ins OTLP-Pipeline müssen, sollte das im jeweiligen Task als „Add metric to OTLP-Pipeline"-Step expliziter sein. Aktuell teilweise nur als „Grafana-Dashboard"-Hinweis. **Empfohlen vor Start:** in `pgbouncer.md` Step 6 und `worker-queues.md` Step 4 (Health) ergänzen „Metrics-Endpoint wird vom OTLP-Collector aus Phase 02 gescraped" als One-Liner.
|
||||
|
||||
---
|
||||
|
||||
## 6. Konsistenz mit User-Wünschen
|
||||
|
||||
| User-Wunsch | Erfüllt in Phase 03? |
|
||||
|---|---|
|
||||
| „DB-Layer: Empfehlung übernehmen" → PgBouncer (A1) | ✓ pgbouncer.md, transaction-mode |
|
||||
| „DB-Layer: R/W-Split via Prisma $extends (B1)" | ✓ read-write-split.md, exact pattern |
|
||||
| „DB-Layer: Outbox + Dispatcher (C1)" | ✓ outbox-pattern.md |
|
||||
| „B+E für Entity-Builder skip — D" | ✓ Nicht in Phase 03, korrekt verortet (gehört nicht hierher) |
|
||||
| „Skalierungs-Refactoring sauber — Hybrid A+D (Redis-default + InMemory-Fallback)" | ✓ shared-store-package.md Factory wählt RedisAdapter wenn REDIS_URL gesetzt, sonst MemoryAdapter mit Warning |
|
||||
| „Streaming für CSV/JSON, Row-Cap für XLSX+PDF" | ✓ streaming-exports.md, exakt nach Vorgabe (XLSX 500k Hard-Cap, PDF 5k) |
|
||||
| „Job-Priority basierend auf Tenant-Plan" | ✓ job-priority.md (Free=10, Pro=5, Enterprise=1) |
|
||||
| „A+D Backup-CLI + Tenant-Snapshot" | ✓ backup-cli.md + tenant-snapshot.md, beide ausführlich |
|
||||
| „EU-only, kein Multi-Region" | ✓ asset-cdn.md empfiehlt Bunny.net (EU/Slowenien); Multi-Region korrekt im Backlog (11-backlog/multi-region.md verifiziert) |
|
||||
|
||||
**Verdikt:** Sehr starke Konsistenz mit Vorgaben. Keine Abweichungen.
|
||||
|
||||
---
|
||||
|
||||
## 7. Phase-Reihenfolge-Logik / Parallelisierung
|
||||
|
||||
Die README-Tabelle (Zeile 17-30) dokumentiert für jeden Task „Parallelisierbar mit". Plausibler Topo-Sort:
|
||||
|
||||
**Wave 1:** #37 (shared-store-package) — Single-Blocker für alles State-bezogene
|
||||
**Wave 2:** #38 + #40 + #43 + #51 (parallel) — Migration, PgBouncer, Backup, CDN unabhängig voneinander
|
||||
**Wave 3:** #39 + #41 + #45 (parallel) — Pub/Sub braucht #38; R/W braucht #40; Worker braucht #37
|
||||
**Wave 4:** #42 + #46 + #44 (parallel) — Outbox braucht #41; Streaming braucht #45; Tenant-Snapshot braucht #43
|
||||
**Wave 5:** #47 — Job-Priority braucht #42
|
||||
|
||||
**Verdikt:** Die Parallelisierung ist sauber dokumentiert. Sub-Phasen-Verteilung (State-Subagent vs Worker-Subagent in README Zeile 64-80) ist sinnvoll mit klarer Synchronisations-Konvention (Redis-DB-Indizes).
|
||||
|
||||
**Finding (Minor):** Die README erwähnt „BullMQ-Queues auf Index 0, Shared-Store auf Index 1, Pub/Sub auf Index 2" (Zeile 80). Das ist konsistent mit `shared-store-package.md` (Zeile 53). Aber: `worker-queues.md` erwähnt diese Konvention nicht explizit. Im Step 3 (connection.ts) wird zwar `WORKER_REDIS_POOL_SIZE` konfiguriert, aber die DB-Index-Zuordnung steht implizit. **Empfohlen vor Start:** in `worker-queues.md` Step 3 die DB-Index-0-Konvention für BullMQ als Comment ergänzen.
|
||||
|
||||
---
|
||||
|
||||
## 8. Fehlende Aspekte / Gaps
|
||||
|
||||
### PgBouncer Stats-Endpoint
|
||||
|
||||
**Verdikt:** Abgedeckt. `pgbouncer.md` Step 6 etabliert Prometheus-Exporter `prometheuscommunity/pgbouncer-exporter`, der `SHOW STATS` periodisch scraped und in Grafana visualisiert. ✓
|
||||
|
||||
### Outbox-Dispatcher Reliability
|
||||
|
||||
**Verdikt:** Sehr gut abgedeckt. `outbox-pattern.md`:
|
||||
- `FOR UPDATE SKIP LOCKED` für Concurrent-Dispatcher-Safety ✓
|
||||
- Retry-Backoff mit Dead-Letter (max 8 Retries) ✓
|
||||
- Admin-UI + CLI für Re-Queue ✓
|
||||
- Concurrency-Tests (2 Dispatcher) ✓
|
||||
- Sentry-Alert bei unknown Event-Type ✓
|
||||
- Staging 24h-Beobachtung als Acceptance-Criterion ✓
|
||||
|
||||
**Finding (Minor):** Dispatcher-Lock-Mechanismus für „nur ein Dispatcher running"-Szenario fehlt. Aktuell ist multi-Dispatcher safe via SKIP LOCKED, aber kein Mechanismus verhindert dass jemand „3 Dispatcher hochfährt und gegen 1 Postgres knallt". Postgres-Connections + Dispatcher-Polling-Pressure könnten ein Issue werden bei vielen Dispatcher-Replicas. Empfehlung: Doku-Hinweis (Step 12) „max 2-3 Dispatcher-Replicas sinnvoll, mehr bringt nichts". Aktuell erwähnt: „Mindestens 1 Replica, 2 Replicas safe für HA" — OK aber Obergrenze fehlt.
|
||||
|
||||
### BullMQ-Job-TTL
|
||||
|
||||
**Verdikt:** **Lücke (Minor Finding).** In keiner Datei wird explizit BullMQ-Job-TTL (`removeOnComplete`, `removeOnFail`) konfiguriert. Default-Verhalten ist „keep all jobs forever in Redis" — kann Redis-Memory schnell vollmüllen.
|
||||
|
||||
**Empfohlen vor Start:** In `worker-queues.md` Step 2 (runtime.ts) oder `job-priority.md` Step 2 (producers.ts) eine `defaultJobOptions: { removeOnComplete: 1000, removeOnFail: 5000 }` Konfiguration als Default ergänzen, plus Dokumentation in Doku-Step. Alternative: eigene Acceptance-Criterion in worker-queues.md.
|
||||
|
||||
### Weitere mögliche Gaps
|
||||
|
||||
- **Redis-Persistence-Strategie:** `shared-store-package.md` Staging-Snippet hat `--save 60 1` (Snapshot alle 60s wenn >1 Key). Für Production-Critical-State (Sessions, Idempotency-Keys) sollte AOF (Append-Only-File) erwogen werden. **Minor Hinweis**, kein Blocker.
|
||||
- **PgBouncer + Prisma Long-Running-Queries:** `query_timeout = 0` ist gut (App-Layer-Timeout), aber `query_wait_timeout = 30` (Zeile 84) könnte Reports blocken wenn alle Server-Connections busy sind. Doku-Hinweis sinnvoll.
|
||||
- **Outbox-Dispatcher Polling-Frequenz:** 1s ist konservativ. Bei Burst-Workloads (1000s Events) könnte das Latency-Bottleneck werden. README erwähnt LISTEN/NOTIFY als zukünftige Migration (Approach Variante B) — sehr gut dokumentiert. ✓
|
||||
|
||||
---
|
||||
|
||||
## 9. Cross-Reference-Konsistenz
|
||||
|
||||
| Cross-Reference | Status |
|
||||
|---|---|
|
||||
| outbox-pattern.md `priority`-Spalte für #47 | ✓ konsistent mit job-priority.md (BullMQ uses 1/5/10) |
|
||||
| streaming-exports.md `worker-import`-Pool | ✓ konsistent mit worker-queues.md Group-Tabelle |
|
||||
| tenant-snapshot.md baut auf backup-cli.md Pattern | ✓ explizit erwähnt + Code-Reuse-Hinweis |
|
||||
| pubsub-cache-invalidation.md Feature-Flag-Stub für Phase 05 | ✓ Step 8 explizit für #53 vorbereitet |
|
||||
| outbox-pattern.md `search.index.`-Routing für Phase 04 | ✓ Step 4 forward-reference |
|
||||
| asset-cdn.md erwähnt CSP-Updates | ✓ Security-Notes Zeile 183 |
|
||||
|
||||
**Verdikt:** Cross-References sind konsistent. Forward-Looks für Phase 04/05 sind sauber als „Stub" markiert ohne die jeweiligen Tasks zu blockieren.
|
||||
|
||||
---
|
||||
|
||||
## 10. Done-Definition + Acceptance-Criteria
|
||||
|
||||
Die Phase-Done-Definition in der README (Zeile 84-97) ist messbar und vollständig:
|
||||
- `cl_active < default_pool_size` ✓ messbar via `SHOW STATS`
|
||||
- Stripe-Webhook → Cache-Invalidation < 2s ✓ messbar via Stripe-CLI + Browser
|
||||
- > 60 % Dashboard-Reads via Replica ✓ messbar via Grafana
|
||||
- 0 unverarbeitete Outbox-Events > 60s alt im 24h-Fenster ✓ messbar
|
||||
- Rollback-Drill als Acceptance-Criterion ✓ exzellent, oft vergessen
|
||||
|
||||
**Pro Task:** Acceptance-Criteria sind durchgängig konkret und verifizierbar. Keine vagen Items wie „funktioniert gut".
|
||||
|
||||
---
|
||||
|
||||
## Mandatory Fixes vor Start
|
||||
|
||||
Die folgenden 4 kleinen Anpassungen sollten vor dem ersten Implementation-Subagent-Spawn erfolgen. Sie sind kein Showstopper, aber verhindern wahrscheinliche Bugs:
|
||||
|
||||
1. **outbox-pattern.md Step 2 / Implementation Hint:** Klarstellen dass `Prisma.TransactionClient`-Constraint nicht hart durchsetzbar via TS-Types ist. Empfehlung: Code-Review-Hinweis aufnehmen, optional Runtime-Branding.
|
||||
2. **outbox-pattern.md neuer Step (oder Step 12 ergänzen):** Cleanup-Cron-Job für `OUTBOX_RETENTION_DAYS` als separater Implementation-Step (nicht nur als Env-Var).
|
||||
3. **worker-queues.md Step 1 / Group-Mapping:** Workflow-Queue explizit zu einer Group zuordnen (vermutlich `general`). Search-Index-Queue als Forward-Comment für Phase 04.
|
||||
4. **worker-queues.md neuer Step oder Default-Config:** BullMQ-Job-TTL via `defaultJobOptions: { removeOnComplete: 1000, removeOnFail: 5000 }` etablieren, um Redis-Memory-Bloat zu verhindern.
|
||||
|
||||
## Empfehlungen (nicht Mandatory)
|
||||
|
||||
5. **streaming-exports.md Step 6:** „Skip-Take oder cursor-based" → eindeutig „cursor-based pflicht".
|
||||
6. **read-write-split.md Approach:** Klarstellen dass `prisma` (ohne `.read`/`.write`) = Write-Client (Default-safe-Konvention) — als One-Liner-Comment.
|
||||
7. **pgbouncer.md Step 8 (Doku):** Hinweis auf Prisma-5.10+ Alternative `?statement_cache_size=0`.
|
||||
8. **worker-queues.md Step 3:** DB-Index-0-Konvention für BullMQ als Comment ergänzen.
|
||||
9. **pubsub-cache-invalidation.md / pgbouncer.md / worker-queues.md:** „Metrics werden vom OTLP-Collector aus Phase 02 gescraped"-One-Liner.
|
||||
10. **outbox-pattern.md Doku:** Empfehlung „max 2-3 Dispatcher-Replicas" gegen Postgres-Connection-Pressure.
|
||||
|
||||
---
|
||||
|
||||
## Gesamtbewertung
|
||||
|
||||
| Dimension | Score |
|
||||
|---|---|
|
||||
| Template-Konformität | 10/10 |
|
||||
| Dependency-Konsistenz | 10/10 |
|
||||
| Technische Korrektheit | 9/10 |
|
||||
| Test-Strategie | 9/10 |
|
||||
| Staging-Setup | 9/10 |
|
||||
| User-Wunsch-Alignment | 10/10 |
|
||||
| Parallelisierungs-Klarheit | 9/10 |
|
||||
| Fehlende Aspekte | 7/10 (Job-TTL, Retention-Cron-Job, Mapping-Lücke) |
|
||||
| Security-Awareness | 10/10 (durchgängig stark) |
|
||||
| Operational-Runbook-Vollständigkeit | 9/10 |
|
||||
|
||||
**Gesamt: 9.2/10**
|
||||
|
||||
**Verdikt: GO mit den 4 oben aufgeführten Mandatory-Fixes.** Die Phase ist deutlich besser ausgearbeitet als für eine reine Plan-Phase üblich. Der ausführende Agent hat einen klaren Bauplan und sollte mit minimalem Re-Planning durchkommen.
|
||||
|
||||
---
|
||||
|
||||
## Verifier-Notes
|
||||
|
||||
- Geprüft wurde READ-ONLY ohne Code-Änderungen.
|
||||
- Cross-Validation gegen `DETAIL-MD-TEMPLATE.md`, `AGENT-INSTRUCTIONS.md`, `00-execution-order.md`, `README.md`.
|
||||
- Backlog-Verification: `11-backlog/multi-region.md` existiert (EU-only-Wunsch korrekt umgesetzt).
|
||||
- Subagents im Execution-Schritt sollten diese Verification.md als zusätzlichen Input bekommen, damit die Mandatory-Fixes als Acceptance-Criteria miteinfließen.
|
||||
Reference in new issue
Block a user