docs(04): auto-generated context (hardware phase)

.planning/phases/04-usb-manager-label-printing/04-CONTEXT.md

@@ -0,0 +1,95 @@
+# Phase 4: USB Manager & Label Printing - Context
+
+**Gathered:** 2026-04-10
+**Status:** Ready for planning
+**Mode:** Auto-generated (autonomous mode)
+
+<domain>
+## Phase Boundary
+
+USB peripherals are managed by a goroutine-per-device subsystem and any cataloged item can have a QR-coded label printed by the PRT Qutie without operator intervention after intake. This phase delivers the USB device manager with VID/PID enumeration, goroutine-per-device pattern, reconnect handling, QR code generation, label rendering, and PRT Qutie printer driver.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Hardware Status
+- PRT Qutie printer, Treedix testers, FNIRSI FNB58 arrive 2026-04-13 (in 3 days)
+- Phase 4 builds code-complete implementation with mock USB device for testing
+- Integration tests use mock or skip gracefully
+- Real hardware validation is a human verification item
+
+### USB Device Architecture (from RESEARCH/ARCHITECTURE)
+- Use `go.bug.st/serial` for USB serial communication
+- Single USB Manager owns all device connections
+- Goroutine-per-device model with command/event channels
+- VID/PID enumeration at startup and on hotplug (via periodic poll on macOS)
+- Reconnect handling on unplug/replug without path reconfiguration
+
+### PRT Qutie Protocol
+- Protocol is unknown until hardware arrives — build a stub driver with command abstraction
+- Use a `PrinterDriver` interface so the PRT Qutie driver can be dropped in later
+- Implement bitmap label rendering using `image` package — output PNG/raw bitmap
+
+### QR Code + Label Rendering
+- `github.com/skip2/go-qrcode` for QR generation (low error correction for compact labels)
+- Label contains: QR code (left), HW-ID (top right), name (middle), spec line (bottom)
+- 15mm wide at 203 DPI = ~120px label height
+- Font: use basicfont from x/image or embed a simple bitmap font
+
+### Cable-Specific Label Template
+- Detect cable records (device_type contains "cable" or catalog tag) → use cable template
+- Cable template shows: USB version, max speed, max power, test date
+
+### Integration with Existing Code
+- Add `internal/usb/` package for USB Manager
+- Add `internal/printer/` package for printer driver
+- Add `internal/labels/` package for QR + rendering
+- Extend chi router with POST /api/labels/:deviceID/print
+- Add SSE endpoint GET /api/usb/events for device connect/disconnect
+
+### Infrastructure
+- No external services needed for Phase 4
+- Mock USB device for tests
+- go.bug.st/serial supports macOS and Linux dev
+
+</decisions>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets from Phase 1-3
+- `internal/netbox/client.go` — GetDevice to look up item for label
+- `internal/netbox/types.go` — Device, CustomFields
+- `internal/api/router.go` — chi router (add label + usb endpoints)
+- `internal/config/config.go` — viper config (add USB device paths)
+- `web/src/pages/DashboardPage.tsx` — add "Print Label" quick action
+
+### Integration Points
+- Dashboard quick action: POST /api/labels/{deviceID}/print
+- Intake flow final step: auto-print after record creation
+- SSE GET /api/usb/events for frontend connect/disconnect notifications
+- USB Manager runs as goroutine, started from main.go
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+- Use a PrinterDriver interface: Connect(), Print(bitmap []byte) error, Disconnect()
+- Mock printer driver logs to stdout and saves PNG to /tmp for visual inspection
+- Label renderer produces a standard Go image.Image that the driver converts
+- For PRT Qutie stub: write raw bytes to serial port with TODO comment for real protocol
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Treedix cable tester integration (Phase 5)
+- FNIRSI FNB58 (Phase 5)
+- Actual PRT Qutie protocol implementation (requires hardware + reverse engineering)
+- Print queue (unnecessary for single-user homelab)
+
+</deferred>