orderPRO/.paul/phases/129-erli-status-mapping-sync/129-01-SUMMARY.md

---
phase: 129-erli-status-mapping-sync
plan: 01
subsystem: settings, integrations, cron, database
tags: [erli, status-mapping, status-sync, cron, marketplace]
requires:
  - phase: 127-erli-integration-foundation
    provides: global Erli credentials, API client, settings page and hub row
  - phase: 128-erli-orders-import
    provides: Erli inbox import, order mapper, sync state and safe ACK flow
provides:
  - 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
affects: [phase-130-erli-shipments-labels, phase-131-erli-tracking-automation, erli-settings]
tech-stack:
  added: []
  patterns: [separate pull/push marketplace status mappings, manual-only push cursor, tabbed integration settings]
key-files:
  created:
    - 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
  modified:
    - 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
key-decisions:
  - "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."
patterns-established:
  - "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."
duration: 35min
started: 2026-05-16T00:00:00+02:00
completed: 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*