---
phase: 116-hostedsms-integration
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - database/migrations/20260512_000107_create_hostedsms_integration_settings.sql
  - src/Modules/Settings/HostedSmsApiClient.php
  - src/Modules/Settings/HostedSmsIntegrationRepository.php
  - src/Modules/Settings/HostedSmsIntegrationController.php
  - src/Modules/Settings/IntegrationsHubController.php
  - routes/web.php
  - resources/views/settings/hostedsms.php
  - resources/views/settings/integrations.php
  - resources/views/layouts/app.php
  - resources/lang/pl.php
  - DOCS/DB_SCHEMA.md
  - DOCS/ARCHITECTURE.md
  - DOCS/TECH_CHANGELOG.md
  - .paul/codebase/db_schema.md
  - .paul/codebase/architecture.md
  - .paul/codebase/tech_changelog.md
autonomous: true
delegation: auto
---

<objective>
## Goal
Dodac pierwsza wersje integracji HostedSMS: pojedyncza globalna konfiguracja konta oraz formularz realnej wysylki testowego SMS-a z edytowalna trescia.

## Purpose
Operator ma moc potwierdzic, ze dane HostedSMS sa poprawne, zanim integracja zostanie uzyta w automatyzacjach lub komunikacji z klientami.

## Output
Nowa podstrona `/settings/integrations/hostedsms`, zapis konfiguracji w DB, klient API SimpleAPI, akcja testowej wysylki SMS i wpis w hubie integracji.
</objective>

<context>
<clarifications>
- **Test SMS** - Czy test ma faktycznie wysylac wiadomosc?
  -> Odpowiedz: Ma faktycznie wysylac testowy sms.
- **Liczba kont** - Jedna globalna konfiguracja czy wiele kont?
  -> Odpowiedz: Wystarczy jedna.
- **Tresc testu** - Tresc testowego SMS ma byc stala czy edytowalna?
  -> Odpowiedz: Edytowalna.
</clarifications>

## Project Context
@.paul/PROJECT.md
@.paul/ROADMAP.md
@.paul/STATE.md
@AGENTS.md
@DOCS/DB_SCHEMA.md
@DOCS/ARCHITECTURE.md

## API Context
HostedSMS SimpleAPI z dokumentacji `https://panel.hostedsms.pl/Doc/HostedSms-Opis_Techniczny_API_pl.pdf`:
- endpoint podstawowy: `POST https://api.hostedsms.pl/SimpleApi`
- endpoint zapasowy: `POST https://api2.hostedsms.pl/SimpleApi`
- pola: `UserEmail`, `Password`, `Sender`, `Phone`, `Message`, opcjonalnie `ConvertMessageToGSM7`
- numer telefonu w formacie miedzynarodowym, np. `48xxxxxxxxx`
- odpowiedz JSON zawiera `MessageId` przy sukcesie albo `ErrorMessage` przy bledzie; HTTP 200 moze oznaczac blad biznesowy

## Source Files
@routes/web.php
@src/Modules/Settings/IntegrationsRepository.php
@src/Modules/Settings/IntegrationSecretCipher.php
@src/Modules/Settings/IntegrationsHubController.php
@src/Modules/Settings/FakturowniaIntegrationRepository.php
@src/Modules/Settings/FakturowniaIntegrationController.php
@src/Modules/Settings/FakturowniaApiClient.php
@resources/views/settings/fakturownia.php
@resources/views/settings/fakturownia-edit.php
@resources/views/settings/integrations.php
@resources/views/layouts/app.php
@resources/lang/pl.php
</context>

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

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

## Skill Invocation Checklist
- [ ] Uruchomic `sonar-scanner` po implementacji, jezeli CLI i SonarQube sa dostepne.
</skills>

<acceptance_criteria>

## AC-1: Zapis konfiguracji HostedSMS
```gherkin
Given zalogowany operator jest na stronie ustawien HostedSMS
When wpisze UserEmail, haslo, nadpis Sender, status aktywnosci i zapisze formularz z poprawnym CSRF
Then konfiguracja zostanie zapisana jako jedna globalna integracja, haslo bedzie zaszyfrowane przez IntegrationSecretCipher, a zapisany sekret nie bedzie widoczny w formularzu
```

## AC-2: Walidacja konfiguracji
```gherkin
Given operator probuje zapisac lub testowac HostedSMS
When brakuje loginu, hasla przy pierwszym zapisie, nadpisu Sender albo numer testowy nie jest w formacie miedzynarodowym
Then aplikacja pokazuje czytelny blad i nie wykonuje wysylki testowej bez kompletnych danych
```

## AC-3: Realny test wysylki SMS
```gherkin
Given konfiguracja HostedSMS jest zapisana z poprawnymi danymi
When operator poda numer testowy i edytowalna tresc testowa oraz kliknie wysylke testowa
Then aplikacja wykona POST do HostedSMS SimpleAPI, zapisze wynik w polach last_test_* integracji i pokaze MessageId albo komunikat bledu z API
```

## AC-4: Widocznosc w panelu integracji
```gherkin
Given operator otwiera Ustawienia > Integracje
When integracja HostedSMS istnieje albo jeszcze nie jest skonfigurowana
Then hub pokazuje wiersz HostedSMS ze statusem konfiguracji, aktywnosci, ostatniego testu i linkiem do ustawien
```

## AC-5: Dokumentacja i zgodnosc projektu
```gherkin
Given funkcja zostala wdrozona
When sprawdzane sa dokumenty techniczne i testy
Then DOCS oraz .paul/codebase opisuja nowa tabele, klasy, endpointy i przeplyw, a testy/lint nie wykazuja regresji
```

</acceptance_criteria>

<tasks>

<task type="auto">
  <name>Task 1: Dodac model konfiguracji HostedSMS</name>
  <files>database/migrations/20260512_000107_create_hostedsms_integration_settings.sql, src/Modules/Settings/HostedSmsIntegrationRepository.php</files>
  <action>
    Utworz migracje dla pojedynczej tabeli `hostedsms_integration_settings` z rekordem `id=1`, `integration_id` jako UNIQUE FK do `integrations`, polami `user_email`, `password_encrypted`, `sender`, `convert_message_to_gsm7`, `created_at`, `updated_at`.
    Repozytorium ma zapewniac bazowy rekord `integrations` typu `hostedsms`, nazwa `HostedSMS`, base_url `https://api.hostedsms.pl/SimpleApi`, zwracac status `has_password` bez ujawniania hasla, zapisywac nowe haslo tylko gdy pole formularza nie jest puste, przy pierwszym zapisie wymagac hasla oraz uzywac `IntegrationSecretCipher` i prepared statements.
  </action>
  <verify>C:\xampp\php\php.exe -l src/Modules/Settings/HostedSmsIntegrationRepository.php</verify>
  <done>AC-1 i AC-2 spelnione dla warstwy zapisu konfiguracji.</done>
</task>

<task type="auto">
  <name>Task 2: Dodac klienta SimpleAPI i kontroler ustawien</name>
  <files>src/Modules/Settings/HostedSmsApiClient.php, src/Modules/Settings/HostedSmsIntegrationController.php, routes/web.php</files>
  <action>
    Utworz `HostedSmsApiClient` wykonujacy POST form-urlencoded do SimpleAPI z `Accept: application/json`, SSL verification i CA z `SslCertificateResolver`. Parsuj odpowiedz JSON: `MessageId` oznacza sukces, `ErrorMessage` blad biznesowy mimo HTTP 200; blad cURL/HTTP ma trafic do komunikatu.
    Utworz `HostedSmsIntegrationController` z akcjami `index`, `save`, `test`. `save` waliduje CSRF, login e-mail, sender i wymaganie hasla przy pierwszym zapisie. `test` waliduje CSRF, numer w formacie miedzynarodowym (`^\d{8,15}$`, z hintem `48...`), tresc niepusta i maks. 4000 znakow. Test realnie wysyla SMS i zapisuje `last_test_status`, `last_test_http_code`, `last_test_message` przez `IntegrationsRepository::updateTestResult`.
    Podlacz DI i trasy: GET `/settings/integrations/hostedsms`, POST `/settings/integrations/hostedsms/save`, POST `/settings/integrations/hostedsms/test`.
  </action>
  <verify>C:\xampp\php\php.exe -l src/Modules/Settings/HostedSmsApiClient.php; C:\xampp\php\php.exe -l src/Modules/Settings/HostedSmsIntegrationController.php; C:\xampp\php\php.exe -l routes/web.php</verify>
  <done>AC-2 i AC-3 spelnione dla backendu i realnej wysylki testowej.</done>
</task>

<task type="auto">
  <name>Task 3: Dodac UI, hub integracji i dokumentacje</name>
  <files>resources/views/settings/hostedsms.php, resources/views/settings/integrations.php, resources/views/layouts/app.php, resources/lang/pl.php, src/Modules/Settings/IntegrationsHubController.php, DOCS/DB_SCHEMA.md, DOCS/ARCHITECTURE.md, DOCS/TECH_CHANGELOG.md, .paul/codebase/db_schema.md, .paul/codebase/architecture.md, .paul/codebase/tech_changelog.md</files>
  <action>
    Dodaj kompaktowy widok ustawien HostedSMS bez inline CSS w nowych blokach. Formularz konfiguracji ma pokazac pola: UserEmail, nowe haslo (placeholder gdy zapisane), Sender, checkbox konwersji do GSM7, aktywnosc. Sekcja testu ma miec numer telefonu i edytowalna tresc z domyslna wartoscia `Test orderPRO HostedSMS`.
    Dodaj HostedSMS do hubu integracji i aktywnego menu ustawien. Jezeli potrzeba nowych styli, umiesc je w SCSS, nie w widoku.
    Zaktualizuj dokumentacje techniczna: tabela `hostedsms_integration_settings`, nowe klasy, trasy i przeplyw testowej wysylki.
  </action>
  <verify>C:\xampp\php\php.exe -l resources/views/settings/hostedsms.php; C:\xampp\php\php.exe -l src/Modules/Settings/IntegrationsHubController.php; npm run build --if-present</verify>
  <done>AC-4 i AC-5 spelnione dla UI, hubu i dokumentacji.</done>
</task>

</tasks>

<boundaries>

## DO NOT CHANGE
- Nie podpinac `DB_HOST_REMOTE` do runtime aplikacji.
- Nie dodawac automatyzacji SMS, szablonow SMS ani wysylki z zamowien w tym planie.
- Nie dodawac natywnych `alert()` / `confirm()`.
- Nie przenosic ani refaktoryzowac istniejacych integracji poza minimalnym dopieciem HostedSMS.

## SCOPE LIMITS
- Tylko jedna globalna konfiguracja HostedSMS.
- Tylko realna wysylka testowa SMS z ustawien.
- Bez historii wyslanych SMS poza istniejacym `last_test_*` i ewentualnym `integration_test_logs`, jesli aktualny `IntegrationsRepository` juz go uzywa.
- Bez raportow dostarczenia, FullApi, WebService2SMS i endpointu zapasowego `api2` w pierwszej wersji, chyba ze zostanie uzyty jako prosty fallback po bledzie polaczenia.

</boundaries>

<verification>
Before declaring plan complete:
- [ ] `C:\xampp\php\php.exe bin/migrate.php`
- [ ] `C:\xampp\php\php.exe -l` dla nowych/zmienionych plikow PHP
- [ ] `npm run build --if-present`
- [ ] Manualnie: zapis konfiguracji HostedSMS, wysylka testowego SMS na numer w formacie `48...`, komunikat z `MessageId`
- [ ] `sonar-scanner` po APPLY, jezeli CLI i SonarQube sa dostepne
- [ ] DOCS i `.paul/codebase` zaktualizowane
- [ ] All acceptance criteria met
</verification>

<success_criteria>
- Operator moze zapisac jedna konfiguracje HostedSMS bez ujawniania hasla.
- Operator moze wyslac realny testowy SMS z edytowalna trescia.
- Wynik testu jest widoczny w ekranie HostedSMS i hubie integracji.
- Migracje, lint i build przechodza albo blokery srodowiskowe sa jasno opisane w SUMMARY.
</success_criteria>

<output>
After completion, create `.paul/phases/116-hostedsms-integration/116-01-SUMMARY.md`
</output>