---
phase: 18-print-queue-backend
plan: 01
subsystem: api
tags: [printing, api-key, rest-api, middleware, remote-printing]

requires: []
provides:
  - Print jobs REST API (create, list pending, download, complete)
  - API key authentication middleware (X-Api-Key header)
  - Print settings UI (CRUD kluczy API)
  - Request::header() method
affects: [19-ui-integration, 20-windows-client]

tech-stack:
  added: []
  patterns: [api-key-auth, sha256-hashing, rest-json-api]

key-files:
  created:
    - database/migrations/20260322_000058_create_print_tables.sql
    - src/Modules/Printing/PrintApiKeyRepository.php
    - src/Modules/Printing/PrintJobRepository.php
    - src/Modules/Printing/PrintApiController.php
    - src/Modules/Printing/ApiKeyMiddleware.php
    - src/Modules/Settings/PrintSettingsController.php
    - resources/views/settings/printing.php
  modified:
    - src/Core/Http/Request.php
    - resources/views/layouts/app.php
    - routes/web.php

key-decisions:
  - "FK constraints removed from print_jobs — type mismatch between orders (INT UNSIGNED) and shipment_packages (BIGINT UNSIGNED)"
  - "API key stored as SHA-256 hash, prefix saved for identification"
  - "Request::header() method added to core Request class for API key extraction"

patterns-established:
  - "API key auth: ApiKeyMiddleware reads X-Api-Key, hashes SHA-256, validates against print_api_keys"
  - "Flash key convention: settings_error, settings_success, settings_new_api_key (underscore, not dot)"

duration: 25min
started: 2026-03-22T00:00:00Z
completed: 2026-03-22T00:25:00Z
---

# Phase 18 Plan 01: Print Queue Backend Summary

**REST API do zdalnego drukowania etykiet — tabele DB, API key auth middleware, 4 endpointy JSON, CRUD kluczy API w ustawieniach.**

## Performance

| Metric | Value |
|--------|-------|
| Duration | ~25min |
| Tasks | 3 completed (2 auto + 1 checkpoint) |
| Files created | 7 |
| Files modified | 3 |

## Acceptance Criteria Results

| Criterion | Status | Notes |
|-----------|--------|-------|
| AC-1: Tabele DB utworzone poprawnie | Pass | print_api_keys + print_jobs, bez FK (type mismatch) |
| AC-2: CRUD kluczy API w ustawieniach | Pass | Tworzenie, wyświetlanie, usuwanie kluczy |
| AC-3: API — tworzenie zlecenia wydruku | Pass | POST /api/print/jobs z session auth |
| AC-4: API — pobieranie zleceń i etykiet | Pass | GET /api/print/jobs/pending + download |
| AC-5: API — oznaczanie jako wydrukowane | Pass | POST /api/print/jobs/{id}/complete |
| AC-6: Nieprawidłowy klucz API odrzucony | Pass | 401 Unauthorized z JSON |

## Accomplishments

- Moduł Printing: PrintApiKeyRepository, PrintJobRepository, PrintApiController, ApiKeyMiddleware
- REST API: 4 endpointy (create job, list pending, download label, mark complete)
- API key auth: SHA-256 hash, prefix do identyfikacji, last_used_at tracking
- Settings UI: lista kluczy + jednorazowe wyświetlenie nowego klucza
- Request::header() method w core — reusable dla przyszłych API

## Files Created/Modified

| File | Change | Purpose |
|------|--------|---------|
| `database/migrations/20260322_000058_create_print_tables.sql` | Created | Tabele print_api_keys + print_jobs |
| `src/Modules/Printing/PrintApiKeyRepository.php` | Created | CRUD kluczy API |
| `src/Modules/Printing/PrintJobRepository.php` | Created | CRUD zleceń wydruku |
| `src/Modules/Printing/PrintApiController.php` | Created | REST API endpointy |
| `src/Modules/Printing/ApiKeyMiddleware.php` | Created | Auth middleware X-Api-Key |
| `src/Modules/Settings/PrintSettingsController.php` | Created | UI zarządzania kluczami |
| `resources/views/settings/printing.php` | Created | Widok ustawień drukowania |
| `src/Core/Http/Request.php` | Modified | Dodano header() method |
| `resources/views/layouts/app.php` | Modified | Link "Drukowanie" w sidebar |
| `routes/web.php` | Modified | 7 nowych route'ów + DI |

## Decisions Made

| Decision | Rationale | Impact |
|----------|-----------|--------|
| Usunięto FK constraints z print_jobs | orders.id (INT UNSIGNED) vs shipment_packages.order_id (BIGINT UNSIGNED) — type mismatch w produkcji | Integralność referencyjna tylko na poziomie aplikacji |
| SHA-256 hash klucza API | Bezpieczeństwo — raw key nigdy nie przechowywany w DB | Klucz wyświetlany jednorazowo po utworzeniu |
| Request::header() w core | Potrzebne do X-Api-Key, reusable | Minimalna zmiana core — 1 metoda |

## Deviations from Plan

### Summary

| Type | Count | Impact |
|------|-------|--------|
| Auto-fixed | 1 | FK constraints usunięte — brak wpływu na funkcjonalność |

**1. FK constraints usunięte z migracji**
- **Found during:** Task 1 (migracja)
- **Issue:** Type mismatch: orders.id = INT UNSIGNED, shipment_packages.order_id = BIGINT UNSIGNED
- **Fix:** Usunięto CONSTRAINT, zostawiono INDEX
- **Verification:** Migracja przeszła poprawnie

## Issues Encountered

| Issue | Resolution |
|-------|------------|
| FK errno 150 (1. próba) | Zmieniono BIGINT→INT UNSIGNED + INT→BIGINT UNSIGNED |
| FK errno 150 (2. próba) | Usunięto FK constraints całkowicie — type mismatch w produkcji |

## Next Phase Readiness

**Ready:**
- API endpoints gotowe do konsumpcji przez Windows Client (faza 20)
- API key auth działa — klient może się uwierzytelnić
- Przycisk "Drukuj" w UI (faza 19) może wywoływać POST /api/print/jobs

**Concerns:**
- Brak FK constraints — integralność tylko na poziomie aplikacji

**Blockers:**
- None

---
*Phase: 18-print-queue-backend, Plan: 01*
*Completed: 2026-03-22*