orderPRO/.paul/phases/14-email-templates/14-02-PLAN.md

---
phase: 14-email-templates
plan: 02
type: execute
wave: 1
depends_on: ["14-01"]
files_modified:
  - database/migrations/20260316_000001_add_attachment1_to_email_templates.sql
  - src/Modules/Settings/EmailTemplateRepository.php
  - src/Modules/Settings/EmailTemplateController.php
  - resources/views/settings/email-templates.php
  - DOCS/DB_SCHEMA.md
autonomous: false
---

<objective>
## Goal
Dodać pole "Załącznik nr 1" do szablonów e-mail z opcją "paragon". Pole zapisywane w DB jako `attachment_1 VARCHAR(50)`, wyświetlane jako select w formularzu szablonu.

## Purpose
Przygotowanie infrastruktury załączników na poziomie szablonu — faza 15 (wysyłka e-mail) odczyta tę konfigurację i automatycznie dołączy PDF paragonu do wiadomości, jeśli istnieje.

## Output
- Migracja SQL dodająca kolumnę `attachment_1`
- Repository/Controller obsługujący nowe pole
- Select w widoku z opcjami "— brak —" / "Paragon"
- Zaktualizowany DB_SCHEMA.md
</objective>

<context>
## Project Context
@.paul/PROJECT.md
@.paul/ROADMAP.md
@.paul/STATE.md

## Prior Work
@.paul/phases/14-email-templates/14-01-PLAN.md — CRUD szablonów, Quill.js, system zmiennych

## Source Files
@src/Modules/Settings/EmailTemplateController.php
@src/Modules/Settings/EmailTemplateRepository.php
@resources/views/settings/email-templates.php
@DOCS/DB_SCHEMA.md
</context>

<skills>
## Required Skills (from SPECIAL-FLOWS.md)

| Skill | Priority | When to Invoke | Loaded? |
|-------|----------|----------------|---------|
| sonar-scanner | required | Po APPLY, przed UNIFY | ○ |

</skills>

<acceptance_criteria>

## AC-1: Kolumna attachment_1 w bazie danych
```gherkin
Given tabela email_templates istnieje
When migracja 20260316_000001 zostanie wykonana
Then kolumna attachment_1 VARCHAR(50) DEFAULT NULL istnieje w tabeli email_templates
```

## AC-2: Zapis i odczyt attachment_1 przez formularz
```gherkin
Given użytkownik edytuje szablon e-mail
When wybierze "Paragon" w polu "Załącznik nr 1" i zapisze
Then wartość 'receipt' jest zapisana w kolumnie attachment_1
And przy ponownej edycji select pokazuje "Paragon" jako wybraną opcję
```

## AC-3: Opcja "brak" czyści attachment_1
```gherkin
Given szablon ma ustawiony attachment_1 = 'receipt'
When użytkownik zmieni select na "— brak —" i zapisze
Then wartość attachment_1 w bazie to NULL
```

## AC-4: Lista szablonów pokazuje informację o załączniku
```gherkin
Given szablon ma attachment_1 = 'receipt'
When użytkownik otwiera listę szablonów
Then w kolumnie "Załącznik" widoczne jest "Paragon"
And dla szablonów bez załącznika kolumna pokazuje "—"
```

</acceptance_criteria>

<tasks>

<task type="auto">
  <name>Task 1: Migracja DB + aktualizacja Repository i Controller</name>
  <files>
    database/migrations/20260316_000001_add_attachment1_to_email_templates.sql,
    src/Modules/Settings/EmailTemplateRepository.php,
    src/Modules/Settings/EmailTemplateController.php
  </files>
  <action>
    1. Utworzyć migrację SQL:
       ```sql
       ALTER TABLE email_templates ADD COLUMN attachment_1 VARCHAR(50) DEFAULT NULL AFTER mailbox_id;
       ```

    2. EmailTemplateRepository — dodać `attachment_1` do:
       - `listAll()` — dodać do SELECT (i do listActive() też)
       - `findById()` — dodać do SELECT
       - `save()` — dodać do INSERT i UPDATE, wartość: NULL gdy puste/'none', string gdy wybrane

    3. EmailTemplateController — dodać stałą ATTACHMENT_TYPES jako centralną mapę:
       ```php
       private const ATTACHMENT_TYPES = [
           'receipt' => 'Paragon',
       ];
       ```
       Dodanie nowego typu w przyszłości = jedna linia w tej tablicy.

    4. EmailTemplateController::index() — przekazać `'attachmentTypes' => self::ATTACHMENT_TYPES` do widoku.

    5. EmailTemplateController::save() — pobrać `attachment_1` z requestu:
       - Jeśli wartość to '' → null
       - Jeśli wartość istnieje w kluczach ATTACHMENT_TYPES → zapisz
       - Inaczej → null (walidacja)
       - Przekazać do repository
  </action>
  <verify>
    - Migracja wykonana na serwerze bez błędów
    - DESCRIBE email_templates pokazuje kolumnę attachment_1
    - Zapis szablonu z attachment_1 = 'receipt' widoczny w DB
  </verify>
  <done>AC-1, AC-2, AC-3 satisfied</done>
</task>

<task type="auto">
  <name>Task 2: Select w widoku + kolumna w liście + aktualizacja DB_SCHEMA</name>
  <files>
    resources/views/settings/email-templates.php,
    DOCS/DB_SCHEMA.md
  </files>
  <action>
    1. Widok — formularz: dodać select "Załącznik nr 1" w nowym wierszu form-grid-2 (pod tematem/aktywny).
       Select generowany dynamicznie z `$attachmentTypes` (przekazane z kontrolera):
       ```php
       <option value="">— brak —</option>
       <?php foreach ($attachmentTypes as $key => $label): ?>
         <option value="<?= $e($key) ?>" ...selected...><?= $e($label) ?></option>
       <?php endforeach; ?>
       ```
       Drugi slot w tym wierszu zostawić pusty lub użyć na przyszły attachment_2.

    2. Widok — tabela listy: dodać kolumnę "Załącznik" między "Skrzynka" a "Status":
       - Odczytać label z `$attachmentTypes[$tpl['attachment_1']]` jeśli klucz istnieje
       - W przeciwnym razie → "—"

    3. DOCS/DB_SCHEMA.md — dodać opis kolumny attachment_1 w sekcji email_templates.
  </action>
  <verify>
    - Formularz wyświetla select z dwoma opcjami
    - Przy edycji szablonu z attachment_1='receipt' select zaznacza "Paragon"
    - Lista szablonów pokazuje kolumnę "Załącznik"
  </verify>
  <done>AC-2, AC-3, AC-4 satisfied</done>
</task>

<task type="checkpoint:human-verify" gate="blocking">
  <what-built>Select "Załącznik nr 1" w formularzu szablonu + kolumna "Załącznik" w liście</what-built>
  <how-to-verify>
    1. Wejdź na /settings/email-templates
    2. Sprawdź czy lista ma kolumnę "Załącznik"
    3. Edytuj istniejący szablon — sprawdź select "Załącznik nr 1" z opcjami "— brak —" i "Paragon"
    4. Wybierz "Paragon", zapisz
    5. Ponownie edytuj — select powinien mieć "Paragon" zaznaczony
    6. W liście przy tym szablonie kolumna "Załącznik" powinna pokazywać "Paragon"
    7. Zmień na "— brak —", zapisz — kolumna powinna pokazywać "—"
  </how-to-verify>
  <resume-signal>Type "approved" to continue, or describe issues to fix</resume-signal>
</task>

</tasks>

<boundaries>

## DO NOT CHANGE
- resources/views/layouts/app.php — sidebar already configured in 14-01
- Logika wysyłania maili — to jest faza 15
- Quill.js editor i system zmiennych — bez zmian

## SCOPE LIMITS
- Tylko konfiguracja załącznika na poziomie szablonu (jaki typ)
- NIE implementować generowania/dołączania pliku — to faza 15
- Tylko jeden slot załącznika (attachment_1), bez dynamicznego dodawania

</boundaries>

<verification>
Before declaring plan complete:
- [ ] Migracja wykonana, kolumna attachment_1 istnieje
- [ ] Zapis/odczyt attachment_1 działa (receipt / null)
- [ ] Select w formularzu z poprawnymi opcjami
- [ ] Kolumna "Załącznik" w liście szablonów
- [ ] DB_SCHEMA.md zaktualizowany
- [ ] Brak regresji w istniejącym CRUD szablonów
</verification>

<success_criteria>
- Kolumna attachment_1 w DB
- Formularz szablonu pozwala wybrać "Paragon" lub "brak"
- Lista szablonów informuje o skonfigurowanym załączniku
- Faza 15 może odczytać attachment_1 z szablonu i na tej podstawie dołączyć PDF
</success_criteria>

<output>
After completion, create `.paul/phases/14-email-templates/14-02-SUMMARY.md`
</output>