105 lines
5.2 KiB
Markdown
105 lines
5.2 KiB
Markdown
# 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.**
|