9.1 KiB
9.1 KiB
phase, plan, subsystem, tags, requires, provides, affects, tech-stack, key-files, key-decisions, patterns-established, duration, started, completed
| phase | plan | subsystem | tags | requires | provides | affects | tech-stack | key-files | key-decisions | patterns-established | duration | started | completed | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 130-erli-shipments-labels | 01 | settings, integrations, shipments, database |
|
|
|
|
|
|
|
|
~20min | 2026-05-16T00:37:00+02:00 | 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.