orderPRO/.paul/phases/116-hostedsms-integration/116-01-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous, delegation

phase	plan	type	wave	depends_on	files_modified	autonomous	delegation
116-hostedsms-integration	01	execute	1		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	true	auto

## 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.

- **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.

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

## 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.

<acceptance_criteria>

AC-1: Zapis konfiguracji HostedSMS

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

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

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

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

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>

Task 1: Dodac model konfiguracji HostedSMS database/migrations/20260512_000107_create_hostedsms_integration_settings.sql, src/Modules/Settings/HostedSmsIntegrationRepository.php 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. C:\xampp\php\php.exe -l src/Modules/Settings/HostedSmsIntegrationRepository.php AC-1 i AC-2 spelnione dla warstwy zapisu konfiguracji. Task 2: Dodac klienta SimpleAPI i kontroler ustawien src/Modules/Settings/HostedSmsApiClient.php, src/Modules/Settings/HostedSmsIntegrationController.php, routes/web.php 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`. 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 AC-2 i AC-3 spelnione dla backendu i realnej wysylki testowej. Task 3: Dodac UI, hub integracji i dokumentacje 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 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. 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 AC-4 i AC-5 spelnione dla UI, hubu i dokumentacji.

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.

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

<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>

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