docs: define v1 requirements

2026-04-10 00:01:35 +00:00 · 2026-04-10 00:01:35 +00:00 · f7e5e72686
commit f7e5e72686
parent 5d7c5e90a2
2 changed files with 176 additions and 2 deletions
--- a/.planning/PROJECT.md
+++ b/.planning/PROJECT.md
@ -41,9 +41,11 @@ Any physical item can be cataloged by uploading a photo — AI extracts data, cr
 ## Context

 - **Target machine**: Mac Mini M4 (16GB unified memory) running macOS
- **NetBox**: Partially deployed in Proxmox LXC at netbox.georgsen.dk — needs netbox-inventory plugin and custom fields
+- **NetBox**: Running in Proxmox LXC 130 (10.5.0.130:8000), API token: `homelab-netbox-api-token-2024`, DNS: netbox.lab.georgsen.dk, external: netbox.georgsen.dk — needs netbox-inventory plugin and custom fields
 - **oMLX**: Not yet installed — needs setup with Gemma 4 model on Mac Mini
- **SearXNG**: Already running in existing infrastructure
+- **SearXNG**: Running in Proxmox LXC 129 (10.5.0.129:8080), JSON API: `http://10.5.0.129:8080/search?q=query&format=json`, DNS: searxng.lab.georgsen.dk, external: search.georgsen.dk — no auth needed
+- **Community Postgres**: Available in homelab infrastructure
+- **DragonFlyDB**: Available in homelab infrastructure — candidate for write-ahead queue / caching
 - **USB peripherals arriving**: Monday 2026-04-13 (PRT Qutie printer, Treedix testers, FNIRSI FNB58)
 - **Git remote**: git.georgsen.dk
 - **Design system**: ClickHouse-inspired (pure black + neon volt) — not Tokyo Night as originally brainstormed
--- a/.planning/REQUIREMENTS.md
+++ b/.planning/REQUIREMENTS.md
@ -0,0 +1,172 @@
+# Requirements: HWLab
+
+**Defined:** 2026-04-09
+**Core Value:** Any physical item can be cataloged by uploading a photo — AI extracts data, creates a NetBox record, and prints a QR-coded label — with zero manual data entry for 80-90% of items.
+
+## v1 Requirements
+
+### NetBox Integration
+
+- [ ] **NB-01**: System connects to NetBox REST API and performs CRUD on devices, modules, and cables
+- [ ] **NB-02**: Custom fields provisioned in NetBox (hw_id, catalog_status, product_url, firmware_version, test_date, test_data, ai_notes, photo_urls)
+- [ ] **NB-03**: netbox-inventory plugin installed and configured for asset lifecycle tracking
+- [ ] **NB-04**: Location hierarchy created in NetBox (Site → Location → Rack per PRD section 7.6)
+- [ ] **NB-05**: Write-ahead queue buffers NetBox operations during network issues (DragonFlyDB available in homelab)
+- [ ] **NB-06**: Catalog quality gate enforced via catalog_status field (draft → indexed → needs_research → researched → complete)
+- [ ] **NB-07**: AI-generated tags synced to NetBox tag system
+
+### AI Pipeline
+
+- [ ] **AI-01**: oMLX installed on Mac Mini M4 with Gemma 4 model serving OpenAI-compatible API
+- [ ] **AI-02**: User can upload 1-3 photos and AI extracts serial number, model, manufacturer, specs via multimodal vision
+- [ ] **AI-03**: AI suggests category, tags, and location for each item
+- [ ] **AI-04**: AI calls SearXNG via function calling to research product specs and datasheets
+- [ ] **AI-05**: Orchestrator reviews Tier 1 output for completeness and flags gaps as needs_research
+- [ ] **AI-06**: Tier 2 research agent (OpenRouter) automatically enriches items flagged needs_research
+- [ ] **AI-07**: Quick add mode skips review screen for items with high AI confidence
+- [ ] **AI-08**: All AI tiers accessed via single OpenAI-compatible client with configurable base URLs
+- [ ] **AI-09**: Provider routing configured via JSON file — swap any tier without code changes
+
+### Label Printing
+
+- [ ] **LBL-01**: QR code generated for each item encoding URL (http://mac-mini.mg:8080/hw/XXXXX)
+- [ ] **LBL-02**: Label contains QR code, HW ID, item name, and key spec line
+- [ ] **LBL-03**: Cable-specific label template shows USB version, speed, wattage, test date
+- [ ] **LBL-04**: Labels printed via PRT Qutie thermal printer over USB serial
+- [ ] **LBL-05**: Label printing integrated as final step of AI intake workflow
+
+### Cable Testing
+
+- [ ] **CBL-01**: USB cable test data read from Treedix USB tester via USB serial (pin continuity, USB version, eMarker, PD, resistance)
+- [ ] **CBL-02**: DisplayPort cable test data read from Treedix DP tester
+- [ ] **CBL-03**: HDMI cable test data read from Treedix HDMI tester
+- [ ] **CBL-04**: FNIRSI FNB58 live voltage/current/PD protocol data read via USB or Bluetooth
+- [ ] **CBL-05**: Cable record auto-created in NetBox with structured test_data JSON
+- [ ] **CBL-06**: Rapid test → verify → print → next workflow in Cable Test Station view
+- [ ] **CBL-07**: Auto-detect which tester is connected via USB VID/PID enumeration
+
+### Dashboard & Search
+
+- [ ] **UI-01**: Inventory dashboard with grid/list toggle showing item cards (photo, name, HW ID, status, key specs)
+- [ ] **UI-02**: Filter inventory by category, tags, catalog status, and location
+- [ ] **UI-03**: AI-powered natural language search ("show me all free 10GbE NICs")
+- [ ] **UI-04**: Item detail view with photos, full specs, test data, and audit history
+- [ ] **UI-05**: Quick actions from dashboard: print label, view in NetBox, edit
+- [ ] **UI-06**: ClickHouse-inspired design system (pure black #000000, neon volt #faff69)
+
+### Lab Advisor
+
+- [ ] **ADV-01**: Chat interface for strategic homelab questions backed by Claude Opus via OpenRouter
+- [ ] **ADV-02**: Inventory context from NetBox pre-loaded into each conversation
+- [ ] **ADV-03**: Conversation history persisted locally in SQLite
+- [ ] **ADV-04**: Model selection dropdown (Opus default, configurable to other OpenRouter models)
+- [ ] **ADV-05**: Response streaming via SSE to chat UI
+
+### USB Device Management
+
+- [ ] **USB-01**: USB device manager discovers peripherals by VID/PID, not path
+- [ ] **USB-02**: Goroutine-per-device model with channel-based command/event pattern
+- [ ] **USB-03**: Graceful reconnect handling when devices are unplugged and replugged
+- [ ] **USB-04**: Device events pushed to frontend via SSE
+
+### Mobile / PWA
+
+- [ ] **PWA-01**: Progressive Web App installable on Android for QR code scanning
+- [ ] **PWA-02**: Item detail view accessible and usable on mobile screen sizes
+- [ ] **PWA-03**: Camera-based QR scanner to look up items by HW ID
+
+### Infrastructure
+
+- [ ] **INF-01**: Go backend serves React SPA via go:embed (single binary)
+- [ ] **INF-02**: Configuration via JSON file + environment variables
+- [ ] **INF-03**: HW-XXXXX sequential ID auto-assigned at intake, stored as NetBox asset_tag
+
+## v2 Requirements
+
+### Bulk Operations
+
+- **BULK-01**: Bulk import mode for high-volume scenarios (box of 50 cables)
+- **BULK-02**: Barcode scanner HID support for existing barcodes
+
+### Network Discovery
+
+- **NET-01**: SNMP/network discovery to auto-populate device inventory
+
+### Integrations
+
+- **INT-01**: Automated NetBox topology map updates from cable test endpoints
+- **INT-02**: Integration with homelab agent (LXC 102) for infrastructure-aware operations
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| Multi-user / RBAC | Solo operator tool — NetBox has RBAC if truly needed |
+| Real-time collaboration | Single-operator homelab; advisor chat is async single-session |
+| CSV bulk import bypassing AI | Creates data quality debt; use AI intake as canonical path |
+| Local LLM fine-tuning UI | Out of scope for inventory tool; prompt engineering + SearXNG sufficient |
+| Predictive failure / warranty alerts | Alert infrastructure disproportionate to homelab context |
+| Network topology auto-update | Topology inference from cable tests is ambiguous; manual updates |
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| NB-01 | — | Pending |
+| NB-02 | — | Pending |
+| NB-03 | — | Pending |
+| NB-04 | — | Pending |
+| NB-05 | — | Pending |
+| NB-06 | — | Pending |
+| NB-07 | — | Pending |
+| AI-01 | — | Pending |
+| AI-02 | — | Pending |
+| AI-03 | — | Pending |
+| AI-04 | — | Pending |
+| AI-05 | — | Pending |
+| AI-06 | — | Pending |
+| AI-07 | — | Pending |
+| AI-08 | — | Pending |
+| AI-09 | — | Pending |
+| LBL-01 | — | Pending |
+| LBL-02 | — | Pending |
+| LBL-03 | — | Pending |
+| LBL-04 | — | Pending |
+| LBL-05 | — | Pending |
+| CBL-01 | — | Pending |
+| CBL-02 | — | Pending |
+| CBL-03 | — | Pending |
+| CBL-04 | — | Pending |
+| CBL-05 | — | Pending |
+| CBL-06 | — | Pending |
+| CBL-07 | — | Pending |
+| UI-01 | — | Pending |
+| UI-02 | — | Pending |
+| UI-03 | — | Pending |
+| UI-04 | — | Pending |
+| UI-05 | — | Pending |
+| UI-06 | — | Pending |
+| ADV-01 | — | Pending |
+| ADV-02 | — | Pending |
+| ADV-03 | — | Pending |
+| ADV-04 | — | Pending |
+| ADV-05 | — | Pending |
+| USB-01 | — | Pending |
+| USB-02 | — | Pending |
+| USB-03 | — | Pending |
+| USB-04 | — | Pending |
+| PWA-01 | — | Pending |
+| PWA-02 | — | Pending |
+| PWA-03 | — | Pending |
+| INF-01 | — | Pending |
+| INF-02 | — | Pending |
+| INF-03 | — | Pending |
+
+**Coverage:**
+- v1 requirements: 46 total
+- Mapped to phases: 0
+- Unmapped: 46
+
+---
+*Requirements defined: 2026-04-09*
+*Last updated: 2026-04-09 after initial definition*