---
phase: 26-manual-tracking-number
plan: 01
subsystem: shipments
tags: [tracking-number, manual-entry, shipment-packages]

requires:
  - phase: 25-shipment-presets-management
    provides: shipment UI in order details
provides:
  - manual tracking number entry endpoint
  - inline form in order detail shipments tab
affects: []

tech-stack:
  added: []
  patterns: [provider='manual' for non-API shipments]

key-files:
  created: []
  modified:
    - src/Modules/Shipments/ShipmentPackageRepository.php
    - src/Modules/Shipments/ShipmentController.php
    - routes/web.php
    - resources/views/orders/show.php
    - resources/scss/app.scss

key-decisions:
  - "Reuse shipment_packages table with provider='manual' instead of new table"
  - "Inline form in shipments tab instead of modal"

patterns-established:
  - "provider='manual' pattern for non-API tracking entries"

duration: ~10min
completed: 2026-03-23
---

# Phase 26 Plan 01: Manual Tracking Number Summary

**Endpoint POST /orders/{id}/shipment/manual z formularzem inline — ręczne dodawanie numerów śledzenia przesyłek do zamówień**

## Performance

| Metric | Value |
|--------|-------|
| Duration | ~10min |
| Completed | 2026-03-23 |
| Tasks | 3 completed |
| Files modified | 7 |

## Acceptance Criteria Results

| Criterion | Status | Notes |
|-----------|--------|-------|
| AC-1: Ręczne dodanie numeru przesyłki | Pass | Endpoint tworzy rekord, activity log, flash success |
| AC-2: Walidacja — pusty numer | Pass | HTML required + server-side trim check |
| AC-3: Wyświetlanie ręcznych przesyłek | Pass | Status "Dodana recznie", przewoźnik z carrier_id, etykieta "—" |

## Accomplishments

- Nowy endpoint `POST /orders/{id}/shipment/manual` z walidacją CSRF i tracking_number
- Metoda `ShipmentPackageRepository::createManual()` — INSERT z provider='manual', status='created'
- Formularz inline w zakładce Przesyłki + zmienione renderowanie dla ręcznych przesyłek

## Files Created/Modified

| File | Change | Purpose |
|------|--------|---------|
| `src/Modules/Shipments/ShipmentPackageRepository.php` | Modified | Nowa metoda createManual() |
| `src/Modules/Shipments/ShipmentController.php` | Modified | Nowa metoda createManual() — endpoint |
| `routes/web.php` | Modified | Nowa route POST /orders/{id}/shipment/manual |
| `resources/views/orders/show.php` | Modified | Formularz inline + wyświetlanie ręcznych przesyłek |
| `resources/scss/app.scss` | Modified | Klasa .manual-tracking-form |
| `public/assets/css/app.css` | Rebuilt | Skompilowany SCSS |
| `DOCS/ARCHITECTURE.md` | Modified | Dokumentacja nowego endpointu |
| `DOCS/TECH_CHANGELOG.md` | Modified | Wpis Phase 26 |

## Decisions Made

| Decision | Rationale | Impact |
|----------|-----------|--------|
| Reuse shipment_packages z provider='manual' | Tabela ma już tracking_number, carrier_id, status — nie trzeba nowej migracji | Zero zmian DB |
| Formularz inline zamiast modala | Szybszy dostęp, mniej kliknięć, spójny z kompaktowym UI | Prostsze UX |
| carrier_id jako nazwa przewoźnika dla manual | Pole VARCHAR już istnieje, semantycznie pasuje | Brak zmian schematu |

## Deviations from Plan

None — plan executed exactly as written.

## Issues Encountered

None.

## Next Phase Readiness

**Ready:**
- Ręczne numery przesyłek w pełni funkcjonalne
- Milestone v1.1 gotowy do zamknięcia

**Concerns:**
- Brak możliwości edycji/usunięcia ręcznych przesyłek (celowo poza scope)

**Blockers:**
- None

---
*Phase: 26-manual-tracking-number, Plan: 01*
*Completed: 2026-03-23*