Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -0,0 +1,104 @@
# MAIL-01 · Mailjet-Willkommensmail nach Signup zuverlässig zustellen
| | |
| ----------------- | -------------------------------------------- |
| **Typ** | Launch-Fix · Transactional Mail |
| **Owner** | Raffael |
| **Phase** | Pilot-Härtung |
| **Cycle/Fenster** | gestartet 2026-08-01 |
| **Status** | Done |
| **Plane** | HIVEGRID-237 |
## Abhängigkeiten & Parallelität
- **Blocked by:** kein technischer Blocker. `EXT-02` bestätigt Domain, Sender,
SPF und DKIM; Signup und Transactional-Mail-Queue sind bereits produktiv verdrahtet.
- **Blocks:** zuverlässige Welcome-Experience für neue Pilot-Tenants.
- **Abhängigkeitsschutz:** Sender, React-Email-Template, Queue, Retry,
Signup-Idempotenz und Marketingversand bleiben unverändert.
## Was / Warum
Der direkte Staging-Signup erzeugt für die Willkommensmail den stabilen Key
`mail:signup-welcome:<tenant>:<creation-request-key>`. Dieser Key ist im echten
Fall 93 Zeichen lang. Der Mailjet-Sandbox-Proof mit dem exakten Staging-Konto
bestätigte die Grenze: 64 Zeichen werden akzeptiert; ab 65 Zeichen antwortet
Mailjet mit HTTP 400 / `mj-0006` für `CustomID`.
Der Provider-Adapter nahm fälschlich 100 Zeichen an. Lange Replay-Keys werden
deshalb deterministisch auf eine höchstens 64 Zeichen lange Korrelation
abgebildet. Kurze IDs bleiben für den Betrieb lesbar. Exakte Retries müssen
dieselbe ID, verschiedene lange Keys praktisch kollisionsfrei verschiedene IDs
erhalten.
## Nicht im Scope
- Kein neues Mail-Template, kein Providerwechsel und kein Marketingversand.
- Keine Änderung an Signup-, Queue-, Retry- oder Delivery-Idempotenz.
- Keine Live-/Produktionsmail und keine Änderung an Mailjet-Secrets.
## Definition of Done
- [x] `CustomID` ist für jede Eingabe höchstens 64 Zeichen lang; Werte bis zur
Grenze bleiben bytegleich.
- [x] Lange Keys werden deterministisch und kollisionsresistent kompaktiert;
der rohe lange Key verlässt den Adapter nicht im Payload.
- [x] Fokus-Tests decken 64/65+, exaktes Replay und verschiedene lange Keys ab.
- [x] Typecheck, Lint, vollständige Testsuite und Package-/Security-Gates sind grün.
- [x] PR-CI, normaler Merge und Staging-Deploy sind grün; ein frischer
Test-Signup belegt die Welcome-Zustellung und das Rendering per Screenshot.
**MAIL-01: 5/5 DoD = 100 % done. Kein selbst machbarer Punkt offen.**
## Technische Bausteine
- `packages/mail/src/mailjet.ts`
- `packages/mail/src/mailjet.test.ts`
- bestehender `mail:signup-welcome`-Outbox-/Queue-Vertrag
- CR-012 in `docs/CHANGE-REQUESTS.md`
## Rollback
Reiner Code-Rollback des Provider-Normalizers. Es gibt keine DB-Migration und
keinen persistierten Vertragswechsel. Bereits kompaktierte IDs sind nur
Provider-Korrelationen; Queue- und Delivery-Idempotenz bleiben an den
unveränderten vollständigen Replay-Key gebunden.
## Umsetzungs-Notiz
2026-08-01 · Diagnose und Implementierung gestartet
- Mailjet-Sandbox-Proof: 32, 50 und 64 Zeichen HTTP 200; 65, 80, 93 und 100
Zeichen HTTP 400 / `mj-0006` für `CustomID`.
- Sender `noreply@hivegrid.de` und Wildcard-Domain sind im exakten
Staging-Konto aktiv; SPF/DKIM sind grün. Der Fehler liegt nicht am Sender.
- Der Adapter bewahrt IDs bis einschließlich 64 Zeichen bytegleich. Längere
IDs erhalten `hivegrid-id:` plus 52 Hex-Zeichen SHA-256; gleiche Keys bleiben
replay-stabil, verschiedene lange Keys erhalten verschiedene Korrelationen.
- Lokaler Proof: 99/99 Mail-Package-Tests, Package-Typecheck und fokussiertes
ESLint grün; anschließend Repo-Typecheck, Repo-Lint und 8.207/8.207 Tests in
1.168 Testdateien grün (60 bewusst übersprungen).
- Der bestehende Transactional-Mail-Baseline-Gate verwies noch auf die längst
entfernte `mailersend.test.ts` und scannte historische Doku nach Postmark.
Er läuft jetzt gegen Mailjet plus den kanonischen Runtime-Removed-Module-
Scanner; 3.834 Runtime-Dateien sind frei von verbotenen Provider-Resten und
der vollständige Baseline-Gate ist grün.
**MAIL-01: 4/5 DoD = 80 % done. Offen: PR-CI, normaler Merge,
Staging-Deploy und Welcome-Zustellproof; kein externer Blocker.**
2026-08-01 · Staging-Zustellung und Rendering abgenommen
- Commit `71ea96992` bestand die vollständigen Gates, wurde über PR `#327`
normal gemergt und war Bestandteil der grünen Staging-Revision `137358736`
aus Deploy `11669`.
- Der frische deutsche BILL-14-Signup erzeugte exakt eine Mail. Das reale
Testpostfach erhielt am 2026-08-01 um 12:55:44 UTC den Betreff
„Willkommen bei HiveGrid, Pilot!“; HTML-Rendering und CTA waren vorhanden.
- Screenshot `58-final-welcome-mail-delivered.png` im finalen Desktop-UAT-
Ordner belegt die tatsächlich zugestellte und gerenderte Mail. Es wurden
keine Production-Mail und keine Mailjet-Secret-Änderung ausgelöst.
- Locale-/Footer-, Plaintext- und Branding-Härtung bleiben bewusst außerhalb
des engen CustomID-Fix-Scope und werden getrennt nachgezogen.
**MAIL-01: 5/5 DoD = 100 % done. Kein selbst machbarer Punkt offen.**