---
phase: 29-delivery-status-mapping-ui
plan: 01
subsystem: ui, settings
tags: [delivery-status, mapping, override, shipment-tracking]

requires:
  - phase: 28-shipment-tracking-ui
    provides: DeliveryStatus class with hardcoded provider mappings
provides:
  - UI for configuring delivery status mappings per provider
  - DB-backed overrides for normalized status and description
  - DeliveryStatus override methods (normalizeWithOverrides, descriptionWithOverrides)
affects: [shipment-tracking-handler integration]

tech-stack:
  added: []
  patterns: [DB override with hardcoded fallback]

key-files:
  created:
    - database/migrations/20260323_000070_create_delivery_status_mappings_table.sql
    - src/Modules/Shipments/DeliveryStatusMappingRepository.php
    - src/Modules/Settings/DeliveryStatusMappingController.php
    - resources/views/settings/delivery-status-mappings.php
    - resources/scss/modules/_delivery-status-mappings.scss
  modified:
    - src/Modules/Shipments/DeliveryStatus.php
    - routes/web.php
    - resources/views/layouts/app.php
    - resources/scss/app.scss

key-decisions:
  - "Bulk save form + separate hidden reset form to avoid nested forms"
  - "saveBulk auto-detects default vs custom: if values match defaults, deletes override"
  - "resetAll added per user request (deviation from plan)"

patterns-established:
  - "DB override with hardcoded fallback: check overrides map first, then fall back to const arrays"

duration: ~45min
started: 2026-03-23T22:00:00Z
completed: 2026-03-23T22:45:00Z
---

# Phase 29 Plan 01: Delivery Status Mapping UI Summary

**UI konfiguracji mapowania surowych statusów dostawy na znormalizowane — per provider, z edycją, resetem i bulk save.**

## Performance

| Metric | Value |
|--------|-------|
| Duration | ~45min |
| Tasks | 3 completed |
| Files created | 5 |
| Files modified | 4 |

## Acceptance Criteria Results

| Criterion | Status | Notes |
|-----------|--------|-------|
| AC-1: Lista mapowań per provider | Pass | Tabela z InPost/Apaczka/Allegro, kolumny raw/description/normalized |
| AC-2: Edycja mapowania statusu | Pass | Select z LABEL_PL, bulk save |
| AC-3: Edycja opisu statusu | Pass | Input text per wiersz |
| AC-4: Reset do domyślnych | Pass | Przycisk per wiersz + resetuj wszystkie |
| AC-5: DeliveryStatus używa custom overrides | Pass | normalizeWithOverrides() i descriptionWithOverrides() |

## Accomplishments

- Tabela `delivery_status_mappings` z UNIQUE KEY na provider+raw_status
- Pełne CRUD repozytorium z upsert i deleteAllByProvider
- DeliveryStatus rozszerzony o `getDefaultMappings()`, `normalizeWithOverrides()`, `descriptionWithOverrides()`, `ALL_STATUSES`
- Kontroler z index/save/saveBulk/reset/resetAll
- Widok z tabelą per provider, bulk save, reset per wiersz i reset all

## Files Created/Modified

| File | Change | Purpose |
|------|--------|---------|
| `database/migrations/20260323_000070_...sql` | Created | Tabela delivery_status_mappings |
| `src/Modules/Shipments/DeliveryStatusMappingRepository.php` | Created | CRUD repozytorium |
| `src/Modules/Settings/DeliveryStatusMappingController.php` | Created | Kontroler ustawień mapowań |
| `resources/views/settings/delivery-status-mappings.php` | Created | Widok tabeli mapowań |
| `resources/scss/modules/_delivery-status-mappings.scss` | Created | Style CSS dla custom rows |
| `src/Modules/Shipments/DeliveryStatus.php` | Modified | ALL_STATUSES, getDefaultMappings, *WithOverrides methods |
| `routes/web.php` | Modified | 5 nowych endpointów + controller instantiation |
| `resources/views/layouts/app.php` | Modified | Link w menu bocznym |
| `resources/scss/app.scss` | Modified | Import nowego modułu SCSS |

## Decisions Made

| Decision | Rationale | Impact |
|----------|-----------|--------|
| Bulk save z auto-detekcją defaults | Unikamy zbędnych wpisów w DB gdy wartości == domyślne | Czysta tabela overrides |
| Osobny hidden form na reset (nie nested) | HTML nie pozwala na nested forms | Fix buga z resetem |
| resetAll dodany | User request | Dodatkowy endpoint + przycisk |

## Deviations from Plan

### Summary

| Type | Count | Impact |
|------|-------|--------|
| Scope additions | 2 | Minimalne — bug fix + feature request |

1. **Bug fix: nested forms** — Reset forms były zagnieżdżone w bulk save form. Przebudowano na hidden form + JS.
2. **Scope addition: resetAll** — Dodano przycisk "Resetuj wszystkie" + endpoint + repo method na życzenie usera.

## Skill Audit

| Expected | Invoked | Notes |
|----------|---------|-------|
| sonar-scanner | ✓ | 0 nowych unikalnych issues; 3x S1192 pre-existing (duplikaty stringów w DeliveryStatus), 1x S1142 pre-existing (matchCarrierByName), 2x accessibility minor w widoku (pre-existing pattern) |

## Next Phase Readiness

**Ready:**
- UI mapowania gotowe do użytku
- DeliveryStatus override methods gotowe do integracji w ShipmentTrackingHandler

**Concerns:**
- ShipmentTrackingHandler jeszcze nie przekazuje overrides do DeliveryStatus — wymaga osobnego planu integracji

**Blockers:** None

---
*Phase: 29-delivery-status-mapping-ui, Plan: 01*
*Completed: 2026-03-23*