Jacek Pyziak
02d06298ea
- Przycisk "Drukuj" w prepare.php i show.php z AJAX + duplikat protection - Bulk print z listy zamówień (checkboxy + header action) - Kolejka wydruku w Ustawienia > Drukowanie (filtr statusu, retry) - POST /api/print/jobs/bulk endpoint (package_ids + order_ids) - ensureLabel() auto-download przez ShipmentProviderRegistry - Apaczka carrier_id = nazwa usługi, kolumna Przewoznik - Tab persistence (localStorage), label file_exists check - Fix use statement ApaczkaApiClient, redirect po utworzeniu przesyłki - Phase 17 (receipt duplicate guard) + Phase 18 (print queue backend) docs Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
139 lines
5.4 KiB
Markdown
139 lines
5.4 KiB
Markdown
---
|
|
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*
|