# appRobotFileservice

Programm-/File-Handling-Service für den AppRobot. Speichert **G-Code-Programme**
(`.gcode` + `.json`-Sidecar), hält das **aktive Programm + Cursor** und unterstützt
**Teaching** (Pose aufnehmen), **Playback** (Programm abspielen) sowie einen
**Browser-basierten Datei-Browser** auf Port 2100.

## Rolle in der Architektur

```
Steuerungen → appRobotDriver → appRobotFileservice ← Browser (Port 2100)
(Joystick, …)   (Gateway)        (dieses Projekt)
                                       │
                     [Senden-Modus, lokales Netz]
                                       └──► appRobotDriver WS
```

- **Steuerungen** kennen nur den Driver. Datei-Befehle (**FCodes** wie `FList`,
  `FPoint`, `FPlus`) schickt die Steuerung an den Driver, der sie als REST-Aufrufe
  hierher weiterreicht.
- **Browser** spricht direkt mit dem Fileservice (Port 2100). Im **Senden-Modus**
  sendet der Fileservice die G-Code-Zeile server-seitig an den Driver — der Browser
  verbindet sich nie direkt mit dem Driver.
- **Playback**: dieser Service liefert die nächste Zeile **driver-nativ (Radian)**
  zurück; ausgeführt wird sie vom Driver.

## Einheiten (wichtig)

- **Gespeichert** wird in **Grad** (Standard-G-Code, lesbar): `a/b/c/e` in Grad,
  `x/y/z` in mm.
- **Am Wire / zum Driver** ist alles **driver-nativ**: `a/b/c/e` in **Radian**.
- Die Umrechnung passiert **ausschließlich hier** (`src/gcode/units.js`).

## Dateiformat

`.gcode` ist die **einzige verbindliche Positions-Abfolge** — reiner Standard-G-Code,
Zeitstempel und Cursor-Marker stehen im Kommentarfeld:

```
G90 G1 x0 y300 z0 a90.00 b-90.00 c0.00 e0.00 f1000 ;1759566014
G90 G1 x310 y444 z0.5 a90.00 b-90.00 c0.00 e6.88 f1000 ;1759566112!
```

- `;<epoch>` = Aufnahme-Zeitstempel.
- `;!` (Ausrufezeichen am Ende des Kommentars) = **Cursor-Marker**: zeigt die
  zuletzt angefahrene Zeile. Primäre Cursor-Quelle beim Lesen. Direkt im Texteditor
  sichtbar.
- `<id>.json` ist ein Sidecar mit Metadaten (Name, Zeiten, `lineCount`, `angleUnit`).
  `cursor` im Sidecar dient nur als Fallback für Altdateien ohne `;!`-Marker.

## Start

```
npm install
npm start          # http://localhost:2100
npm test           # jest
```

HTTP (kein TLS) — der Service ist intern. Konfiguration via Env-Variablen (s. u.).

## Konfiguration (Env)

| Variable | Default | Zweck |
|---|---|---|
| `FILE_SERVICE_PORT` | `2100` | Port |
| `STORAGE_DIR` | `./GCodeFiles` | Wurzel-Verzeichnis für `.gcode` + `.json` |
| `FILE_EXT` | `gcode` | `gcode` oder `ngc` |
| `STORE_ANGLE_UNIT` | `deg` | Speichereinheit der Winkel |
| `FILE_API_KEY` | – | Bearer-Token für Schreibzugriffe (fehlt → offen, Dev) |
| `DRIVER_WS_URL` | – | WS-URL des appRobotDriver (z. B. `wss://appRobotDriver:2095`); leer → Senden-Modus deaktiviert |
| `DRIVER_TIMEOUT_MS` | `10000` | Maximale Wartezeit auf Driver-Antwort (ms) |

## API (Kurzüberblick)

### Programme

| Endpoint | Methode | Zweck |
|---|---|---|
| `GET /api/programs?dir=` | GET | Programme auflisten |
| `POST /api/programs` | POST | Programm anlegen |
| `DELETE /api/programs/:id?dir=` | DELETE | Programm löschen |
| `GET /api/programs/:id/download` | GET | `.gcode`-Datei herunterladen |

### Ordner

| Endpoint | Methode | Zweck |
|---|---|---|
| `GET /api/folders?dir=` | GET | Unterordner auflisten |
| `POST /api/folders` | POST | Unterordner anlegen |
| `DELETE /api/folders/:name?dir=` | DELETE | Unterordner (rekursiv) löschen |

### Aktives Programm

| FCode (am Driver) | Endpoint | Hinweis |
|---|---|---|
| `FList` | `GET /api/programs` | |
| `FLoad <id>` | `PUT /api/active` | `{ id, dir }` |
| `FClear` | `POST /api/active/clear` | |
| `FPoint` | `POST /api/active/points` | |
| `FPlus` / `FMinus` | `POST /api/active/next` / `/prev` | `?execute=true` → auch an Driver senden |
| `FFirst` / `FLast` | `POST /api/active/first` / `/last` | `?execute=true` → auch an Driver senden |
| `FGoto <n>` | `POST /api/active/goto` | |
| `FPlay` / `FStop` | `POST /api/active/play` / `/stop` | |
| — | `DELETE /api/active/lines/:index` | Zeile löschen |

### Senden-Modus (`?execute=true`)

`POST /api/active/next?execute=true` bewegt den Cursor UND sendet die G-Code-Zeile
an den Driver (server-seitig). Der Endpoint wartet auf die Driver-Antwort:
- **Erfolg** (M114-Broadcast) → HTTP 200 `{ cursor, line, driverPos }`
- **Driver-Fehler** → HTTP 502 `{ error, message }`
- **Timeout** → HTTP 504

### Konfiguration

| Endpoint | Zweck |
|---|---|
| `GET /api/health` | Liveness-Check |
| `GET /api/config` | `{ driverConfigured: bool }` — ob `DRIVER_WS_URL` gesetzt ist |

## Projektstruktur

```
index.js                    Einstiegspunkt (startet den Server)
src/
  config.js                 Env-Konfiguration (inkl. driverWsUrl, driverTimeoutMs)
  server.js                 Express-App (createApp, /api/config, /api/health)
  errors.js                 Fehler-Envelope + Middleware
  auth.js                   Bearer-Auth (für Schreibzugriffe)
  driverClient.js           WS-Client zum Driver (Senden-Modus)
  gcode/units.js            Grad↔Radian, Zeilenformat, Cursor-Marker (;!)
  store/fileStore.js        .gcode + .json Persistenz (mit dir-Support, max. 5 Ebenen)
  active/activeState.js     Aktives Programm + Cursor (Singleton, ;!-Persistenz)
  routes/programs.js        /api/programs* inkl. /download
  routes/active.js          /api/active* inkl. ?execute=true
  routes/folders.js         /api/folders*
public/
  index.html                Browser-UI (Datei-Browser + Stepping + Senden-Modus)
  index.css                 Design-System (dark theme, CSS-Variablen)
test/
  units.test.js             Einheiten + Cursor-Marker-Funktionen
  fileStore.test.js         Persistenz-Tests (;!-Marker, dir-Support)
  activeState.test.js       ActiveState-Tests (Teaching, Stepping, Cursor-Persistenz)
  driverClient.test.js      WS-Client (Erfolg, Fehler, Timeout)
doc/
  fileBrowser.md            Browser-UI Ist-Zustand
  commandsFromGCodeFile.md  Senden-Modus Konzept + Implementierungsplan
  draft_filehandeling.md    Original-Konzept (historisch)
  draft_filehandeling_API.md Original-API-Entwurf (historisch)
GCodeFiles/                 Programm-Storage zur Laufzeit
```

## Status

Produktiv einsetzbar. Offen: Upload via Browser, Inline-Editor, Live-Updates via SSE
(statt 5s-Polling). Siehe [`doc/fileBrowser.md`](doc/fileBrowser.md).