165 lines
6.8 KiB
Markdown
165 lines
6.8 KiB
Markdown
---
|
|
phase: 15-email-sending
|
|
plan: 01
|
|
subsystem: email
|
|
tags: [phpmailer, smtp, dompdf, quill, activity-log]
|
|
|
|
requires:
|
|
- phase: 13-email-mailboxes
|
|
provides: email_mailboxes table, SMTP credentials, IntegrationSecretCipher
|
|
- phase: 14-email-templates
|
|
provides: email_templates table, Quill.js editor, VARIABLE_GROUPS, ATTACHMENT_TYPES
|
|
|
|
provides:
|
|
- EmailSendingService (send + preview via SMTP)
|
|
- VariableResolver (template variable substitution)
|
|
- AttachmentGenerator (receipt PDF in-memory)
|
|
- Send email modal on order detail view
|
|
- Activity log integration for email events
|
|
|
|
affects: []
|
|
|
|
tech-stack:
|
|
added: [phpmailer/phpmailer v7.0.2]
|
|
patterns: [activity-log-based email history, in-memory PDF attachments]
|
|
|
|
key-files:
|
|
created:
|
|
- src/Modules/Email/EmailSendingService.php
|
|
- src/Modules/Email/VariableResolver.php
|
|
- src/Modules/Email/AttachmentGenerator.php
|
|
- resources/views/orders/partials/email-send-modal.php
|
|
- resources/scss/modules/_email-send.scss
|
|
modified:
|
|
- src/Modules/Orders/OrdersController.php
|
|
- routes/web.php
|
|
- resources/views/orders/show.php
|
|
- resources/lang/pl.php
|
|
|
|
key-decisions:
|
|
- "PHPMailer v7.0.2 jako SMTP transport (nie natywny mail())"
|
|
- "Email history jako wpisy w order_activity_log (nie osobna sekcja UI)"
|
|
- "VariableResolver wydzielony jako osobna klasa (reuse poza kontrolerem szablonow)"
|
|
- "Zalaczniki in-memory (addStringAttachment) bez plikow tymczasowych"
|
|
|
|
patterns-established:
|
|
- "Activity log integration: nowe typy zdarzen (email_sent/email_failed) z tlumaczeniami w pl.php"
|
|
- "Email modul (App\\Modules\\Email) jako oddzielny namespace od Settings"
|
|
|
|
duration: ~90min
|
|
started: 2026-03-17T10:00:00Z
|
|
completed: 2026-03-17T11:30:00Z
|
|
---
|
|
|
|
# Phase 15 Plan 01: Wysylka e-mail z zamowien — Summary
|
|
|
|
**Pelny flow wysylki e-mail z widoku zamowienia: wybor szablonu, podglad ze zmiennymi, wysylka SMTP z zalacznikiem paragon PDF, logowanie w historii zamowienia.**
|
|
|
|
## Performance
|
|
|
|
| Metric | Value |
|
|
|--------|-------|
|
|
| Duration | ~90min |
|
|
| Tasks | 2 auto + 1 checkpoint |
|
|
| Files created | 5 |
|
|
| Files modified | 9 |
|
|
|
|
## Acceptance Criteria Results
|
|
|
|
| Criterion | Status | Notes |
|
|
|-----------|--------|-------|
|
|
| AC-1: Wysylka e-mail z zamowienia | Pass | Szablon + zmienne + SMTP wysylka dziala end-to-end |
|
|
| AC-2: Zalacznik paragon PDF | Pass | Dompdf generuje PDF in-memory, dolaczany przez addStringAttachment |
|
|
| AC-3: Logowanie wysylek | Pass | Wpis w email_logs + order_activity_log (widoczny w zakladce Historia) |
|
|
| AC-4: Podglad przed wysylka | Pass | AJAX preview z rozwiazanymi zmiennymi + lista zalacznikow |
|
|
| AC-5: Walidacja i obsluga bledow | Pass | Brak konfiguracji → btn disabled; blad SMTP → status failed + komunikat |
|
|
|
|
## Accomplishments
|
|
|
|
- Modul `App\Modules\Email` z 3 klasami: EmailSendingService, VariableResolver, AttachmentGenerator
|
|
- Modal wysylki na widoku zamowienia z wyborem szablonu, skrzynki, podgladem i wysylka AJAX
|
|
- Integracja z order_activity_log — wysylka maila pojawia sie jako zdarzenie w historii zamowienia
|
|
- PHPMailer v7.0.2 jako zaleznosc composer
|
|
|
|
## Files Created/Modified
|
|
|
|
| File | Change | Purpose |
|
|
|------|--------|---------|
|
|
| `src/Modules/Email/EmailSendingService.php` | Created | Glowna klasa wysylki: send(), preview(), SMTP transport, logowanie |
|
|
| `src/Modules/Email/VariableResolver.php` | Created | Zamiana {{grupa.zmienna}} na dane zamowienia/kupujacego/firmy |
|
|
| `src/Modules/Email/AttachmentGenerator.php` | Created | Generowanie PDF paragonu in-memory przez dompdf |
|
|
| `resources/views/orders/partials/email-send-modal.php` | Created | Modal: wybor szablonu/skrzynki, podglad, wysylka AJAX |
|
|
| `resources/scss/modules/_email-send.scss` | Created | Style modala i podgladu |
|
|
| `src/Modules/Orders/OrdersController.php` | Modified | Dodano sendEmail(), emailPreview(), email deps w konstruktorze |
|
|
| `routes/web.php` | Modified | Nowe route'y POST send-email/email-preview, wiring EmailSendingService |
|
|
| `resources/views/orders/show.php` | Modified | Przycisk "Wyslij e-mail", include modala |
|
|
| `resources/lang/pl.php` | Modified | Tlumaczenia email_sent, email_failed |
|
|
| `resources/scss/app.scss` | Modified | Import modules/email-send |
|
|
| `composer.json` | Modified | phpmailer/phpmailer v7.0.2 |
|
|
| `DOCS/DB_SCHEMA.md` | Modified | Wpis o PHPMailer i module Email |
|
|
| `DOCS/ARCHITECTURE.md` | Modified | Nowy modul + route'y |
|
|
| `DOCS/TECH_CHANGELOG.md` | Modified | Changelog Phase 15 |
|
|
|
|
## Decisions Made
|
|
|
|
| Decision | Rationale | Impact |
|
|
|----------|-----------|--------|
|
|
| PHPMailer v7.0.2 (nie natywny mail()) | Pelna kontrola SMTP, auth, TLS, zalaczniki | Nowa zaleznosc composer |
|
|
| Email history w activity_log (nie osobna sekcja) | Spojnosc UX — jeden timeline zdarzen | Prostszy widok, mniej kodu |
|
|
| VariableResolver jako osobna klasa | Reuse logiki zmiennych poza kontrolerem szablonow | Czystsza architektura |
|
|
| In-memory PDF (addStringAttachment) | Brak plikow tymczasowych na dysku | Prostsze, bezpieczniejsze |
|
|
|
|
## Deviations from Plan
|
|
|
|
### Summary
|
|
|
|
| Type | Count | Impact |
|
|
|------|-------|--------|
|
|
| Scope change | 1 | Email history przeniesiona z Dokumentow do activity_log |
|
|
| Auto-fixed | 3 | Bugfixy odkryte podczas pracy |
|
|
|
|
**Total impact:** Istotna zmiana UX (lepsza), plus naprawione 3 bugi.
|
|
|
|
### Scope Change
|
|
|
|
**1. Email history w activity_log zamiast osobnej sekcji w Dokumentach**
|
|
- **Zmiana:** User zażądał przeniesienia historii e-maili z zakładki Dokumenty do zakładki Historia jako wpisy w activity_log
|
|
- **Wpływ:** Usunięto loadEmailLogs(), emailLogsList z widoku; dodano recordActivity() w EmailSendingService
|
|
|
|
### Auto-fixed Issues
|
|
|
|
**1. Search duplicate :search parameter (OrdersRepository)**
|
|
- **Found during:** Testowanie UI
|
|
- **Issue:** PDO named parameter `:search` użyty 5x w jednym zapytaniu — wyszukiwanie po nazwisku klienta nie działało
|
|
- **Fix:** Osobne nazwy parametrów `:s1` do `:s5`
|
|
- **Files:** `src/Modules/Orders/OrdersRepository.php`
|
|
|
|
**2. Migration idempotency (attachment_1)**
|
|
- **Found during:** Uruchomienie migracji
|
|
- **Issue:** `ALTER TABLE ADD COLUMN attachment_1` nie miała warunku IF NOT EXISTS
|
|
- **Fix:** Dodano sprawdzenie information_schema + PREPARE/EXECUTE
|
|
- **Files:** `database/migrations/20260316_000001_add_attachment1_to_email_templates.sql`
|
|
|
|
**3. ReceiptController actor name**
|
|
- **Found during:** Review activity_log entries
|
|
- **Issue:** Używał `$user['username']` (nieistniejące pole) zamiast `$user['name']`
|
|
- **Fix:** Zmieniono na `$user['name'] ?? $user['email']`
|
|
- **Files:** `src/Modules/Accounting/ReceiptController.php`
|
|
|
|
## Next Phase Readiness
|
|
|
|
**Ready:**
|
|
- Milestone v0.4 Modul E-mail kompletny (Phase 13 + 14 + 15)
|
|
- Pelny flow: skrzynki SMTP → szablony z Quill.js → wysylka z zamowien
|
|
|
|
**Concerns:**
|
|
- Brak kolejki/retry dla nieudanych wysylek (synchroniczna wysylka)
|
|
- Brak bulk email z listy zamowien
|
|
|
|
**Blockers:**
|
|
- None
|
|
|
|
---
|
|
*Phase: 15-email-sending, Plan: 01*
|
|
*Completed: 2026-03-17*
|