Upload

2026-01-12 15:25:34 +00:00
parent 83bd89a25a
commit fc5a281e85
85 changed files with 3748 additions and 73 deletions
@@ -0,0 +1,56 @@
+# Klangkiste Dev Playbook
+
+## Purpose
+This playbook documents the "virtual box" development environment. It is a complete, hardware-free simulation that runs entirely inside the repo and lets you test setup, playback, and API flows end-to-end.
+
+Docs live in the repo-level `docs/` to keep all dev guidance in one predictable place for both Box and GUI contributors.
+
+## Prerequisites
+- Python 3
+- Node.js + npm
+- From repo root
+
+## Step-by-step
+Quickstart (3-5 minutes):
+1) Start everything:
+```
+./dev.sh
+```
+2) Open the WiFi setup UI:
+```
+http://127.0.0.1:9000/setup
+```
+3) Add a WiFi profile and submit.
+4) Check status:
+```
+curl http://127.0.0.1:8000/status
+```
+5) Start playback:
+```
+curl -X POST http://127.0.0.1:8000/command \
+  -H "Content-Type: application/json" \
+  -d '{"command":"nfc_on","payload":{"uid":"UID_1"}}'
+```
+
+## Troubleshooting
+- Box not starting:
+  - Ensure dependencies are installed and ports 8000/9000 are free.
+- GUI cannot reach API:
+  - Check `VITE_BOX_API_URL` and Box logs.
+
+## What Is Mock vs Real
+- Mock: WiFi, IP, Spotify, audio, hardware. These are logical simulations only.
+- Real: Box process, playback state machine, API, CLI, resume logic, media traversal.
+
+## Link Index
+- Dev workflow: `docs/dev-workflow.md`
+- Box lifecycle: `docs/box-lifecycle.md`
+- Setup WebGUI: `docs/setup-webgui.md`
+- HTTP API contract: `docs/api.md`
+- GUI control panel: `docs/gui-control-panel.md`
+- Playback testing: `docs/playback-testing.md`
+- Offline scenarios: `docs/offline-scenarios.md`
+- Security & storage: `docs/security-storage.md`
+- CLI reference: `docs/cli.md`
+- Virtual box notes: `docs/virtual-box.md`
+- Legacy storage notes: `docs/storage.md`