Jacek Pyziak
957fddaf84
Implement bidirectional status sync for shopPRO integrations. When direction is set to orderpro_to_shoppro, cron pushes manual status changes to shopPRO via PUT API with reverse status mapping. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
137 lines
5.3 KiB
Markdown
137 lines
5.3 KiB
Markdown
---
|
|
phase: 45-shoppro-status-push
|
|
plan: 01
|
|
subsystem: integration
|
|
tags: [shoppro, status-sync, cron, curl-put, api]
|
|
|
|
requires:
|
|
- phase: shoppro-integrations
|
|
provides: ShopproApiClient, ShopproIntegrationsRepository, order_status_mappings, integration_order_sync_state
|
|
|
|
provides:
|
|
- Bidirectional status sync between orderPRO and shopPRO
|
|
- ShopproApiClient::updateOrderStatus() PUT method
|
|
- Reverse status mapping (orderpro -> shoppro)
|
|
|
|
affects: []
|
|
|
|
tech-stack:
|
|
added: []
|
|
patterns: [reverse-status-mapping, cursor-based-push-sync]
|
|
|
|
key-files:
|
|
created:
|
|
- database/migrations/20260327_000071_add_last_status_pushed_at_to_sync_state.sql
|
|
modified:
|
|
- src/Modules/Settings/ShopproApiClient.php
|
|
- src/Modules/Settings/ShopproStatusSyncService.php
|
|
- src/Modules/Settings/ShopproOrderSyncStateRepository.php
|
|
- src/Modules/Cron/CronHandlerFactory.php
|
|
|
|
key-decisions:
|
|
- "Refactor: wydzielenie executeRequest() z requestJson() dla reuse GET/PUT"
|
|
- "Push only change_source=manual to prevent sync loops"
|
|
- "Fallback 24h when last_status_pushed_at is null"
|
|
|
|
patterns-established:
|
|
- "Reverse mapping: orderpro_status_code -> shoppro_status_code (first match wins)"
|
|
- "Cursor-based push: last_status_pushed_at tracks sync progress per integration"
|
|
|
|
duration: 15min
|
|
started: 2026-03-27T00:00:00Z
|
|
completed: 2026-03-27T00:15:00Z
|
|
---
|
|
|
|
# Phase 45 Plan 01: ShopPRO Status Push Summary
|
|
|
|
**Implementacja synchronizacji statusow zamowien orderPRO -> shopPRO przez cron z reverse mapping i PUT API**
|
|
|
|
## Performance
|
|
|
|
| Metric | Value |
|
|
|--------|-------|
|
|
| Duration | ~15min |
|
|
| Tasks | 3 completed |
|
|
| Files modified | 7 |
|
|
|
|
## Acceptance Criteria Results
|
|
|
|
| Criterion | Status | Notes |
|
|
|-----------|--------|-------|
|
|
| AC-1: API Client obsluguje PUT change_status | Pass | `updateOrderStatus()` wysyla PUT z JSON body `{status_id, send_email}` |
|
|
| AC-2: Push kierunek dziala w cron sync | Pass | `syncPushDirection()` query manual changes, reverse map, API call, cursor update |
|
|
| AC-3: Brak mapowania nie blokuje synca | Pass | Brak mapowania = `$skipped++`, kontynuacja petli |
|
|
|
|
## Accomplishments
|
|
|
|
- `ShopproApiClient::updateOrderStatus()` — metoda PUT do `/api.php?endpoint=orders&action=change_status`
|
|
- `ShopproStatusSyncService::syncPushDirection()` — pelna logika push: reverse mapping, query `order_status_history` (tylko `change_source=manual`), wywolanie API, aktualizacja kursora
|
|
- Refactor `ShopproApiClient` — wydzielenie `executeRequest()` z `requestJson()` dla reuse GET/PUT (eliminacja duplikacji SSL/curl logic)
|
|
- Kursor `last_status_pushed_at` w `integration_order_sync_state` z defensywnym sprawdzaniem istnienia kolumny
|
|
|
|
## Files Created/Modified
|
|
|
|
| File | Change | Purpose |
|
|
|------|--------|---------|
|
|
| `database/migrations/20260327_000071_*.sql` | Created | Migracja: kolumna `last_status_pushed_at` |
|
|
| `src/Modules/Settings/ShopproApiClient.php` | Modified | Nowa metoda `updateOrderStatus()` + refactor na `executeRequest()` |
|
|
| `src/Modules/Settings/ShopproStatusSyncService.php` | Modified | Implementacja push direction z reverse mapping |
|
|
| `src/Modules/Settings/ShopproOrderSyncStateRepository.php` | Modified | Metody `getLastStatusPushedAt()`, `updateLastStatusPushedAt()` |
|
|
| `src/Modules/Cron/CronHandlerFactory.php` | Modified | Nowe zaleznosci dla ShopproStatusSyncService, reuse instancji repo |
|
|
| `DOCS/DB_SCHEMA.md` | Modified | Dokumentacja kolumny `last_status_pushed_at` |
|
|
| `DOCS/ARCHITECTURE.md` | Modified | Opis push direction i nowej metody API |
|
|
| `DOCS/TECH_CHANGELOG.md` | Modified | Wpis chronologiczny |
|
|
|
|
## Decisions Made
|
|
|
|
| Decision | Rationale | Impact |
|
|
|----------|-----------|--------|
|
|
| Refactor `requestJson()` na `executeRequest()` | Eliminacja duplikacji SSL/curl logic miedzy GET i PUT | Latwiejsze dodawanie kolejnych metod HTTP |
|
|
| Push tylko `change_source=manual` | Zapobieganie petli synchronizacji (import->push->import) | Bezpieczna dwukierunkowa synchronizacja |
|
|
| Fallback 24h dla null cursor | Przy pierwszym uruchomieniu nie pushowac calej historii | Ograniczenie zakresu pierwszego synca |
|
|
| `send_email=false` w push | Sync nie powinien generowac maili do klientow | Brak niechcianych powiadomien |
|
|
|
|
## Deviations from Plan
|
|
|
|
### Summary
|
|
|
|
| Type | Count | Impact |
|
|
|------|-------|--------|
|
|
| Auto-fixed | 1 | Minimal |
|
|
|
|
**Total impact:** Essential refactor, no scope creep
|
|
|
|
### Auto-fixed Issues
|
|
|
|
**1. Refactor: duplikacja curl logic**
|
|
- **Found during:** Task 1
|
|
- **Issue:** Plan sugerowal zduplikowanie SSL opts lub wydzielenie `buildCurlHandle()`. Duplikacja bylaby nieoptymalna.
|
|
- **Fix:** Wydzielono `executeRequest()` z pelna logika curl (GET/PUT), `requestJson()` i `requestJsonPut()` sa teraz thin wrappers.
|
|
- **Files:** `ShopproApiClient.php`
|
|
- **Verification:** `php -l` pass
|
|
|
|
### Deferred Items
|
|
|
|
None
|
|
|
|
## Issues Encountered
|
|
|
|
None
|
|
|
|
## Next Phase Readiness
|
|
|
|
**Ready:**
|
|
- Push direction w pelni funkcjonalny — po uruchomieniu migracji i restarcie crona, statusy beda synchronizowane
|
|
- Istniejace mapowania statusow (skonfigurowane w UI) beda uzywane w obu kierunkach
|
|
|
|
**Concerns:**
|
|
- Migracja `000071` musi byc uruchomiona na serwerze produkcyjnym
|
|
- Nalezy zweryfikowac mapowania statusow w konfiguracji integracji shopPRO (czy pokrywaja wszystkie uzywane statusy)
|
|
|
|
**Blockers:**
|
|
None
|
|
|
|
---
|
|
*Phase: 45-shoppro-status-push, Plan: 01*
|
|
*Completed: 2026-03-27*
|