Project-Pro/orderPRO
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
380146bf0712e140cb40fe27e46fd1a7a709af36
orderPRO/.paul/phases/129-erli-status-mapping-sync/129-01-SUMMARY.md
Jacek Pyziak 7972bb9fa4 feat(129): erli status mapping sync 
Phase 129 complete:
- Add Erli pull/push status mapping tables, seeds and repositories
- Wire Erli status sync cron for inbox pull and manual-only push
- Add tabbed Erli settings UI, tests and documentation

Co-Authored-By: Claude <noreply@anthropic.com>
2026-05-16 00:27:28 +02:00

11 KiB
Raw Blame History

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
129-erli-status-mapping-sync 01 settings, integrations, cron, database
erli
status-mapping
status-sync
cron
marketplace
phase provides
127-erli-integration-foundation global Erli credentials, API client, settings page and hub row
phase provides
128-erli-orders-import Erli inbox import, order mapper, sync state and safe ACK flow
Configurable Erli -> orderPRO pull status mappings with discovery
Configurable orderPRO -> Erli push status mappings
Cron-driven Erli status sync in pull or push direction
Tabbed Erli settings UI consistent with other integrations
phase-130-erli-shipments-labels
phase-131-erli-tracking-automation
erli-settings
added patterns
separate pull/push marketplace status mappings
manual-only push cursor
tabbed integration settings
created modified
database/migrations/20260515_000116_add_erli_status_mapping_sync.sql
src/Modules/Settings/ErliStatusMappingRepository.php
src/Modules/Settings/ErliPullStatusMappingRepository.php
src/Modules/Settings/ErliStatusSyncService.php
src/Modules/Cron/ErliStatusSyncHandler.php
tests/Unit/ErliStatusSyncServiceTest.php
src/Modules/Settings/ErliApiClient.php
src/Modules/Settings/ErliIntegrationController.php
src/Modules/Settings/ErliOrderMapper.php
src/Modules/Settings/ErliOrdersSyncService.php
src/Modules/Settings/ErliOrderSyncStateRepository.php
src/Modules/Cron/CronHandlerFactory.php
routes/web.php
resources/views/settings/erli.php
resources/lang/pl.php
DOCS/DB_SCHEMA.md
DOCS/ARCHITECTURE.md
DOCS/TECH_CHANGELOG.md
Push to Erli uses only manual orderPRO status changes from order_status_history.change_source='manual'.
Pull status changes reuse the existing Erli inbox import and ACK flow instead of a separate status endpoint.
Erli settings use the same tabbed UI pattern as Allegro/shopPRO.
Erli has separate pull and push mapping repositories/tables to avoid mixing import and outbound sync semantics.
Unknown Erli statuses discovered in inbox are stored for later operator mapping.
35min 2026-05-16T00:00:00+02:00 2026-05-16T00:23:35+02:00

Phase 129 Plan 01: Erli Status Mapping + Sync Summary

Erli now supports configurable pull/push status mapping, status discovery from inbox, and cron-based status synchronization with a tabbed settings UI.

Performance

Metric Value
Duration ~35min
Started 2026-05-16T00:00:00+02:00
Completed 2026-05-16T00:23:35+02:00
Tasks 3 completed
Files modified 25 phase files, excluding unrelated .vscode/ftp-kr.sync.cache.json

Acceptance Criteria Results

Criterion Status Notes
AC-1: Erli status mapping schema and seeds Pass Migration adds pull/push mapping tables, integration_order_sync_state.last_status_pushed_at, app settings, seed status options, and disabled erli_status_sync schedule.
AC-2: Erli settings UI exposes status mappings Pass /settings/integrations/erli exposes tabbed panels for integration, statuses and settings; operators can save pull/push mappings, direction and interval with CSRF-protected forms.
AC-3: Import uses configurable pull mappings with discovery Pass ErliOrderMapper uses configured pull mappings with safe fallbacks; ErliOrdersSyncService stores newly seen raw Erli statuses for later mapping.
AC-4: Cron pushes only manual orderPRO status changes to Erli Pass ErliStatusSyncService selects only Erli orders with manual status history newer than last_status_pushed_at and calls PATCH /orders/{id}/status only when mapped.
AC-5: Push is safe and observable Pass Sync result reports pushed/skipped/failed and bounded errors; cursor advances only through successfully processed timestamps.
AC-6: Documentation and tests cover status behavior Pass with env gaps PHP lint and diff checks passed; PHPUnit and Sonar are documented gaps because local CLIs are unavailable/broken. Docs were updated.

Accomplishments

  • Added Erli status persistence for both directions with seed statuses from the documented Erli status contract.
  • Extended Erli API client with PATCH /orders/{id}/status.
  • Added repositories and controller endpoints for saving pull and push mappings.
  • Reused the existing inbox import path for Erli -> orderPRO status pulls.
  • Added ErliStatusSyncService and cron handler for configurable pull/push sync.
  • Updated Erli settings UI to match other integrations with tabs.
  • Added mapper and status sync unit test coverage files.

Task Commits

No per-task commits were created during APPLY. Phase transition creates the scoped phase commit.

Task Commit Type Description
Task 1: Persistence/API foundation pending phase commit feat Mapping tables, seeds, repositories and API status update method.
Task 2: Settings UI/routes pending phase commit feat Erli settings status controls, mapping forms, routes and translations.
Task 3: Runtime sync/tests/docs pending phase commit feat/test/docs Discovery, pull/push sync service, cron handler, tests and docs.

Files Created/Modified

File Change Purpose
database/migrations/20260515_000116_add_erli_status_mapping_sync.sql Created Status mapping tables, sync cursor, seeds and cron/app settings.
src/Modules/Settings/ErliStatusMappingRepository.php Created Push mapping persistence for orderPRO -> Erli.
src/Modules/Settings/ErliPullStatusMappingRepository.php Created Pull mapping persistence and discovery for Erli -> orderPRO.
src/Modules/Settings/ErliStatusSyncService.php Created Pull/push status sync orchestration and result counters.
src/Modules/Cron/ErliStatusSyncHandler.php Created Cron entrypoint for erli_status_sync.
tests/Unit/ErliStatusSyncServiceTest.php Created Unit tests for push success, skipped unmapped changes and failure cursor behavior.
src/Modules/Settings/ErliApiClient.php Modified Added authenticated Erli status update request.
src/Modules/Settings/ErliIntegrationController.php Modified Added tab state, status settings and mapping save handlers.
src/Modules/Settings/ErliOrderMapper.php Modified Added configurable pull mapping with safe fallback.
src/Modules/Settings/ErliOrdersSyncService.php Modified Added raw Erli status discovery during inbox import.
src/Modules/Settings/ErliOrderSyncStateRepository.php Modified Added push cursor support.
src/Modules/Cron/CronHandlerFactory.php Modified Registered erli_status_sync.
routes/web.php Modified Wired repositories, status sync service and mapping routes.
resources/views/settings/erli.php Modified Added tabbed UI and pull/push mapping forms.
resources/lang/pl.php Modified Added Erli status mapping/sync/tabs translations.
DOCS/DB_SCHEMA.md Modified Documented new tables/settings/cursor.
DOCS/ARCHITECTURE.md Modified Documented Erli status sync flow and tabbed settings.
DOCS/TECH_CHANGELOG.md Modified Logged Phase 129 and Erli settings tabs fix.

Decisions Made

Decision Rationale Impact
Push only manual status changes Prevents loops from imports, automation and system updates. Operator intent is explicit; automated changes stay local unless manually changed.
Pull uses inbox import Erli status events arrive through inbox and the Phase 128 ACK flow is already safe. One source of truth for Erli event processing.
Separate pull/push mapping tables Import statuses and outbound Erli status values have different semantics. Safer UI and easier future extension.
Unknown pull statuses are discovered Erli can introduce or send statuses not present in seed data. Operator can map new statuses without code changes.
Erli settings use tabs Page grew after Phase 129 and needed parity with Allegro/shopPRO. Better scanability, same interaction model as other integrations.

Deviations from Plan

Summary

Type Count Impact
Auto-fixed 1 UI parity fix, no backend contract change.
Scope additions 1 Tabbed Erli settings page added during final verification.
Deferred 2 Environment-dependent verification remains operator follow-up.

Total impact: Positive UI consistency improvement; no expansion into shipments/labels/tracking.

Auto-fixed Issues

1. Erli settings were missing tabs

  • Found during: Post-APPLY manual inspection.
  • Issue: Erli settings displayed all integration/status/import/test sections in one vertical page, unlike Allegro/shopPRO.
  • Fix: Added active tab handling, return_to for forms and standard content-tabs-nav / content-tab-panel markup.
  • Files: resources/views/settings/erli.php, src/Modules/Settings/ErliIntegrationController.php, resources/lang/pl.php, docs.
  • Verification: PHP lint for view/controller/lang and git diff --check.

Deferred Items

  • Phase 129 follow-up: run php bin/migrate.php, verify /settings/integrations/erli mappings, set orderPRO -> Erli, manually change an Erli order status and run erli_status_sync.
  • Phase 129 verification gap: vendor/bin/phpunit is absent in this checkout and global XAMPP PHPUnit is incompatible with the current PHP, so PHPUnit tests were not executed.
  • Phase 129 skill gap: sonar-scanner is not available in PATH, so Sonar scan could not run.

Issues Encountered

Issue Resolution
vendor/bin/phpunit missing Documented as verification gap; PHP lint and diff checks were run.
Global XAMPP phpunit crashes on removed PHP each() Documented as verification gap.
sonar-scanner unavailable Documented in SUMMARY and STATE skill audit.

Verification Results

Check Result
php -l resources/views/settings/erli.php Pass
php -l src/Modules/Settings/ErliIntegrationController.php Pass
php -l resources/lang/pl.php Pass
Phase APPLY PHP lints for changed PHP/view/test files Pass
git diff --check Pass
vendor/bin/phpunit tests/Unit/ErliOrderMapperTest.php tests/Unit/ErliStatusSyncServiceTest.php Not run: vendor/bin/phpunit missing
phpunit --version Failed: old XAMPP PHPUnit uses removed each()
sonar-scanner --version Failed: command not found

Skill audit: required sonar-scanner was attempted and documented unavailable.

Next Phase Readiness

Ready:

  • Erli status mapping and sync foundation is in place for later shipment/tracking work.
  • Erli settings now has the tab structure needed to host future shipment/label settings.
  • Push sync cursor and manual-change filtering provide a safe outbound pattern for future Erli API writes.

Concerns:

  • Live Erli behavior still needs migration and production credential smoke testing.
  • PHPUnit dev dependencies are missing locally, so unit tests need a composer install or CI run.
  • Sonar scan still depends on installing/configuring sonar-scanner in PATH.

Blockers:

  • None for planning Phase 130. Manual smoke remains required before production confidence.

Phase: 129-erli-status-mapping-sync, Plan: 01 Completed: 2026-05-16

Reference in New Issue View Git Blame Copy Permalink