feat(130): erli shipments and labels

.paul/phases/130-erli-shipments-labels/130-01-SUMMARY.md

@@ -0,0 +1,165 @@
+---
+phase: 130-erli-shipments-labels
+plan: 01
+subsystem: settings, integrations, shipments, database
+tags: [erli, shipping, labels, delivery-mapping, external-parcels]
+requires:
+  - phase: 127-erli-integration-foundation
+    provides: global Erli credentials and API client
+  - phase: 128-erli-orders-import
+    provides: Erli orders in common order model
+  - phase: 129-erli-status-mapping-sync
+    provides: tabbed Erli settings UI and outbound API pattern
+provides:
+  - Erli delivery mapping tab
+  - Erli shipping dictionary and external parcel API methods
+  - Local label provider preselection for Erli orders
+  - External parcel registration in Erli after tracking number exists
+affects: [phase-131-erli-tracking-automation, erli-settings, shipment-flow]
+tech-stack:
+  added: []
+  patterns: [marketplace delivery mapping with source vendor, non-critical external parcel sync]
+key-files:
+  created:
+    - database/migrations/20260516_000117_extend_delivery_mappings_for_erli_shipping.sql
+    - src/Modules/Settings/ErliDeliveryMappingController.php
+    - src/Modules/Settings/ErliExternalShipmentService.php
+    - tests/Unit/ErliExternalShipmentServiceTest.php
+  modified:
+    - src/Modules/Settings/ErliApiClient.php
+    - src/Modules/Settings/CarrierDeliveryMethodMappingRepository.php
+    - src/Modules/Settings/ErliIntegrationController.php
+    - src/Modules/Shipments/ShipmentController.php
+    - routes/web.php
+    - resources/views/settings/erli.php
+    - resources/views/shipments/prepare.php
+    - resources/lang/pl.php
+    - DOCS/DB_SCHEMA.md
+    - DOCS/ARCHITECTURE.md
+    - DOCS/TECH_CHANGELOG.md
+key-decisions:
+  - "Erli labels stay on local providers; Erli receives external parcel/tracking through POST /shipping/external."
+  - "Erli vendor code is stored separately from local provider service in carrier_delivery_method_mappings.source_vendor_code."
+patterns-established:
+  - "External marketplace shipment sync is non-critical and must not block local labels."
+duration: ~20min
+started: 2026-05-16T00:37:00+02:00
+completed: 2026-05-16T00:51:00+02:00
+---
+
+# Phase 130-01 Summary: Erli Shipments + Labels
+
+Phase 130 adds Erli delivery mappings, local label provider preselection and external parcel registration through the native Erli shipping API without using Erli carrier-contract label flow.
+
+## Performance
+
+| Metric | Result |
+|--------|--------|
+| Duration | ~20min |
+| Started | 2026-05-16T00:37:00+02:00 |
+| Completed | 2026-05-16T00:51:00+02:00 |
+| Tasks | 3/3 completed |
+| Files changed | 18 phase files, excluding unrelated `.vscode/ftp-kr.sync.cache.json` |
+
+## Acceptance Criteria
+
+| AC | Result | Notes |
+|----|--------|-------|
+| AC-1: Erli Shipping Contract Is Used Where Safe | Pass | `ErliApiClient` now supports shipping/delivery dictionaries, vendors, price lists and `POST /shipping/external`; no native label download endpoint is assumed. |
+| AC-2: Erli Delivery Mapping Tab Exists | Pass | `/settings/integrations/erli?tab=delivery` has a CSRF-protected mapping tab with imported delivery methods, Erli vendor context and local provider service choices. |
+| AC-3: Erli Orders Preselect Shipment Provider | Pass | Shipment prepare includes Erli in delivery mapping lookup and preselects mapped local provider/service. |
+| AC-4: Labels Are Generated Without Erli Carrier Agreement | Pass | Labels remain provider-driven through local InPost/Apaczka/Allegro WZA flow and keep writing `shipment_packages`. |
+| AC-5: External Parcel Is Registered In Erli | Pass with live smoke pending | `ErliExternalShipmentService` registers external parcels only after tracking exists and logs non-critical errors. |
+| AC-6: Documentation And Verification Cover The Flow | Pass with env gaps | PHP lint and diff checks passed; PHPUnit and Sonar are unavailable in this environment. |
+
+## Accomplishments
+
+- Extended generic carrier delivery mappings with Erli-specific source service/vendor metadata.
+- Added an Erli delivery tab that maps Erli delivery methods to local label providers and Erli vendor codes.
+- Added native Erli shipping dictionary and external parcel client methods.
+- Wired Erli shipment preparation into the existing local label flow.
+- Added non-blocking external parcel sync to Erli after local tracking numbers become available.
+- Updated database, architecture and technical changelog documentation.
+
+## Task Results
+
+| Task | Result | Commit |
+|------|--------|--------|
+| Task 1: Extend Erli API and mapping repository for shipping | Done | Phase commit |
+| Task 2: Add Erli delivery mapping tab | Done | Phase commit |
+| Task 3: Use mappings during shipment creation and sync external parcel to Erli | Done | Phase commit |
+
+## Files Created
+
+| File | Purpose |
+|------|---------|
+| `database/migrations/20260516_000117_extend_delivery_mappings_for_erli_shipping.sql` | Adds Erli source service/vendor metadata to delivery mappings. |
+| `src/Modules/Settings/ErliDeliveryMappingController.php` | Loads and saves Erli delivery mapping tab data. |
+| `src/Modules/Settings/ErliExternalShipmentService.php` | Registers local tracking numbers as Erli external parcels. |
+| `tests/Unit/ErliExternalShipmentServiceTest.php` | Focused unit coverage for Erli external parcel sync behavior. |
+
+## Files Modified
+
+| File | Purpose |
+|------|---------|
+| `src/Modules/Settings/ErliApiClient.php` | Added shipping dictionaries, price lists and external parcel API calls. |
+| `src/Modules/Settings/CarrierDeliveryMethodMappingRepository.php` | Added Erli source support and source vendor/service persistence. |
+| `src/Modules/Settings/ErliIntegrationController.php` | Added delivery tab data and tab routing. |
+| `src/Modules/Shipments/ShipmentController.php` | Uses Erli delivery mappings and triggers external parcel sync after tracking exists. |
+| `routes/web.php` | Wires Erli delivery save route and external shipment service dependencies. |
+| `resources/views/settings/erli.php` | Adds Erli delivery tab UI. |
+| `resources/views/shipments/prepare.php` | Preselects mapped local provider/service for Erli shipments. |
+| `resources/lang/pl.php` | Adds Polish labels for Erli delivery mapping UI. |
+| `DOCS/DB_SCHEMA.md` | Documents mapping columns. |
+| `DOCS/ARCHITECTURE.md` | Documents Erli shipment flow. |
+| `DOCS/TECH_CHANGELOG.md` | Records Phase 130 technical changes. |
+
+## Decisions Made
+
+| Decision | Rationale |
+|----------|-----------|
+| Use local label providers for Erli labels | Operator does not want to ship on Erli's carrier agreement; existing provider labels are the source of truth. |
+| Register Erli parcels through `POST /shipping/external` | Official Erli API supports external parcels with order id, vendor, status and tracking number. |
+| Store Erli vendor separately from local provider service | Erli vendor and local provider/service are different contracts and should not overload the same field. |
+| Make Erli external parcel sync non-critical | Local label generation must survive Erli API failures. |
+
+## Deviations
+
+| Type | Description | Impact |
+|------|-------------|--------|
+| Scope addition | Added a small migration because the existing mapping schema could not cleanly store Erli vendor separately from the local provider service. | Low risk, improves contract clarity. |
+| Implementation detail | Native InPost service data is preferred for Erli/InPost mappings where available, with existing Allegro WZA filtered service list as fallback. | Keeps Erli local-provider flow independent from Allegro where possible. |
+| Verification gap | PHPUnit binary is missing and `sonar-scanner` is not available in PATH. | Tests exist but could not be executed locally. |
+
+## Issues Encountered
+
+| Issue | Resolution |
+|-------|------------|
+| Erli `deliveryVendors` dictionary can return scalar rows | Normalization now preserves scalar values as both id and name. |
+| MySQL `CREATE INDEX IF NOT EXISTS` support is environment-sensitive | Migration avoids that syntax and only adds required columns. |
+| External parcel duplicate behavior could not be live-tested | Service stores successful sync payload and treats sync failures as non-critical activity entries. |
+
+## Verification
+
+| Check | Result |
+|-------|--------|
+| PHP syntax lint for changed PHP/view/test files | Passed |
+| `git diff --check -- . ':!.vscode/ftp-kr.sync.cache.json'` | Passed |
+| `vendor/bin/phpunit tests/Unit/ErliExternalShipmentServiceTest.php` | Not run: `vendor/bin/phpunit` missing |
+| `sonar-scanner --version` | Not run: command unavailable in PATH |
+| Manual Erli delivery tab smoke | Pending operator after migration/live configuration |
+| Manual Erli label + external parcel smoke | Pending operator after migration/live configuration |
+
+## Next Phase Readiness
+
+Phase 131 can build on:
+- Erli delivery mappings with local provider and Erli vendor metadata.
+- Local shipment packages with tracking numbers.
+- Non-critical Erli external parcel sync payloads stored in `shipment_packages.payload_json`.
+
+Remaining concerns for Phase 131:
+- Live Erli credentials, migration execution and browser smoke are still pending operator environment.
+- Delivery tracking automation should decide how to poll/update delivery status after the external parcel exists.
+- Duplicate external parcel semantics should be confirmed against live Erli responses.
+
+No blocker prevents planning Phase 131.