feat(127): erli integration foundation

Phase 127 complete: - add global Erli settings schema and encrypted API key repository - add real read-only Erli API connection test and settings UI - expose Erli in integrations hub and update PAUL/docs state
2026-05-15 23:26:44 +02:00
parent afdbc67887
commit d6b18a6438
18 changed files with 1281 additions and 28 deletions
--- a/.paul/phases/127-erli-integration-foundation/127-01-SUMMARY.md
+++ b/.paul/phases/127-erli-integration-foundation/127-01-SUMMARY.md
@@ -0,0 +1,167 @@
+---
+phase: 127-erli-integration-foundation
+plan: 01
+subsystem: settings, integrations, api, database
+tags: [erli, marketplace, integration-settings, api-client, encrypted-secrets]
+
+requires:
+  - phase: 113-fakturownia-integration-foundation
+    provides: integrations hub test-result pattern and encrypted integration settings
+  - phase: 117-smsplanet-integration-settings
+    provides: single global settings + real API test pattern
+provides:
+  - single global Erli API configuration
+  - encrypted Erli Bearer API key storage
+  - real Erli connection test via GET /inbox
+  - Erli row in integrations hub
+affects: [erli-orders-import, erli-status-sync, erli-shipments, erli-tracking]
+
+tech-stack:
+  added: []
+  patterns: [single-global-marketplace-settings, encrypted-bearer-api-key, real-readonly-api-test]
+
+key-files:
+  created:
+    - database/migrations/20260515_000114_create_erli_integration_settings.sql
+    - src/Modules/Settings/ErliIntegrationRepository.php
+    - src/Modules/Settings/ErliApiClient.php
+    - src/Modules/Settings/ErliIntegrationController.php
+    - resources/views/settings/erli.php
+  modified:
+    - src/Modules/Settings/IntegrationsHubController.php
+    - routes/web.php
+    - resources/lang/pl.php
+    - DOCS/DB_SCHEMA.md
+    - DOCS/ARCHITECTURE.md
+    - DOCS/TECH_CHANGELOG.md
+    - .paul/ROADMAP.md
+    - .paul/STATE.md
+
+key-decisions:
+  - "Erli starts as one global configuration, not multi-account"
+  - "No sandbox/environment switch in Phase 127"
+  - "Connection test performs a real read-only Erli API request"
+
+patterns-established:
+  - "Erli settings mirror Fakturownia/SMSPLANET single-row repository pattern"
+  - "Erli API test uses Authorization: Bearer plus User-Agent and stores result in integrations.last_test_*"
+
+duration: ~20min
+started: 2026-05-15T23:00:00+02:00
+completed: 2026-05-15T23:19:00+02:00
+---
+
+# Phase 127 Plan 01: Erli Integration Foundation Summary
+
+**Single global Erli marketplace configuration with encrypted API key storage, real read-only API test, settings UI, and integrations hub row.**
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~20min |
+| Started | 2026-05-15T23:00:00+02:00 |
+| Completed | 2026-05-15T23:19:00+02:00 |
+| Tasks | 3 completed |
+| Files created | 6 |
+| Files modified | 8 |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| AC-1: Schema And Single Integration Row | Pass | Migration creates `erli_integration_settings`, seeds/updates `integrations.type='erli'`, fixed row `id=1`, encrypted key column. |
+| AC-2: Save Erli Configuration | Pass | `/settings/integrations/erli/save` validates CSRF, saves label/API key/active flag, preserves secret on empty input, shows saved/missing state. |
+| AC-3: Real API Connection Test | Pass | `ErliApiClient::testConnection()` performs authenticated `GET /inbox`; controller stores `integrations.last_test_*`. Live test awaits real credentials. |
+| AC-4: Integrations Hub Visibility | Pass | `IntegrationsHubController::buildErliRow()` adds Erli with configured/missing, active, last test and configure link. |
+| AC-5: Documentation Updated | Pass | `DOCS/DB_SCHEMA.md`, `DOCS/ARCHITECTURE.md`, `DOCS/TECH_CHANGELOG.md` updated. |
+
+## Accomplishments
+
+- Added global Erli settings table and repository with encrypted Bearer API key handling.
+- Added real connection-test client for official Erli API using `GET https://erli.pl/svc/shop-api/inbox`.
+- Added authenticated settings routes and compact UI under `/settings/integrations/erli`.
+- Added Erli to the integrations hub.
+- Documented schema, architecture and technical changelog.
+
+## Task Commits
+
+No per-task commits were created during APPLY. Phase commit is created during UNIFY transition.
+
+## Files Created/Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `database/migrations/20260515_000114_create_erli_integration_settings.sql` | Created | Global Erli config table and base integration seed. |
+| `src/Modules/Settings/ErliIntegrationRepository.php` | Created | Settings persistence, secret encryption, active credentials. |
+| `src/Modules/Settings/ErliApiClient.php` | Created | Real read-only Erli API connection test. |
+| `src/Modules/Settings/ErliIntegrationController.php` | Created | Settings page, save action, test action. |
+| `resources/views/settings/erli.php` | Created | Erli settings and test UI. |
+| `routes/web.php` | Modified | Erli DI wiring and routes. |
+| `resources/lang/pl.php` | Modified | Erli translations and hub provider label. |
+| `src/Modules/Settings/IntegrationsHubController.php` | Modified | Erli row in integrations hub. |
+| `DOCS/DB_SCHEMA.md` | Modified | Added `erli_integration_settings`. |
+| `DOCS/ARCHITECTURE.md` | Modified | Added Erli foundation flow/classes. |
+| `DOCS/TECH_CHANGELOG.md` | Modified | Added Phase 127 technical entry. |
+
+## Decisions Made
+
+| Decision | Rationale | Impact |
+|----------|-----------|--------|
+| Single global Erli configuration | User chose one global account; matches small single-instance integration pattern. | Future phases use one Erli integration id unless requirements change. |
+| No sandbox switch | User explicitly declined sandbox/environment toggle. | UI/schema stay simpler; live testing uses production API credentials. |
+| Real read-only connection test | User required a real API test. | Test uses `GET /inbox`, but does not import or mark messages read. |
+
+## Deviations from Plan
+
+### Summary
+
+| Type | Count | Impact |
+|------|-------|--------|
+| Deferred | 2 | Environment/live resources needed |
+| Scope additions | 0 | None |
+| Auto-fixed | 0 | None |
+
+### Deferred Items
+
+- Run `php bin/migrate.php` when local MySQL/XAMPP is online.
+- Save real Erli API key and perform manual `/settings/integrations/erli` connection test.
+- `sonar-scanner` was not available in PATH, so scan was not run.
+
+## Issues Encountered
+
+| Issue | Resolution |
+|-------|------------|
+| Live API verification needs real Erli credentials | Implemented real test path and documented manual follow-up. |
+| SonarQube CLI missing from PATH | Documented as verification gap. |
+
+## Verification Results
+
+| Check | Result |
+|-------|--------|
+| `php -l src/Modules/Settings/ErliIntegrationRepository.php` | Pass |
+| `php -l src/Modules/Settings/ErliApiClient.php` | Pass |
+| `php -l src/Modules/Settings/ErliIntegrationController.php` | Pass |
+| `php -l src/Modules/Settings/IntegrationsHubController.php` | Pass |
+| `php -l resources/views/settings/erli.php` | Pass |
+| `php -l routes/web.php` | Pass |
+| `php -l resources/lang/pl.php` | Pass |
+| `git diff --check` | Pass; only CRLF warnings from Git |
+
+## Next Phase Readiness
+
+**Ready:**
+- Erli credentials can be stored and decrypted by future import/status/shipment services.
+- Hub and last-test result contract is available for operator visibility.
+- API client establishes header, timeout, SSL and error-handling pattern for future Erli calls.
+
+**Concerns:**
+- Real credentials and migration smoke remain manual follow-up.
+- `/inbox` test endpoint checks authorization but does not verify order payload mapping yet.
+
+**Blockers:**
+- None for planning Phase 128.
+
+---
+*Phase: 127-erli-integration-foundation, Plan: 01*
+*Completed: 2026-05-15*