# 📓 CrumbAPI Log Handbuch – Crumbforest Logging

🪵 **Stand:** 2025-06-09 13:17:03

---

## 🧭 Überblick

Dieses Handbuch beschreibt das Logging-Verhalten für Anfragen an die CrumbAPI, insbesondere den Endpunkt:

```
POST /crumbapi/blockly-terminal
```

---

## 🧾 Zweck des Loggings

- 🧒 Kindgerechte Terminalaktionen sollen **transparent nachvollziehbar** gespeichert werden.
- 💬 Gesendeter Blockly-Code (JavaScript) wird für spätere Analyse archiviert.
- 🪵 Format: **JSONL** (eine Zeile pro Eintrag, maschinenlesbar und append-fähig)

---

## 📍 Log-Speicherorte

### 🗃️ Aktuelles Blockly-Kommando
```
/var/www/html/tmp/blockly_terminal_input.json
```
→ enthält **immer nur den letzten gesendeten Blockcode**

### 🗂️ Verlauf aller Blockly-Kommandos
```
/var/www/html/tmp/blockly_terminal_log.jsonl
```
→ enthält **eine Zeile JSON pro gesendeter Anfrage**

---

## 🧩 Aufbau eines Logeintrags

Beispiel:
```json
{
  "timestamp": "2025-06-09T13:11:26+00:00",
  "source": "terminal",
  "user": "robot",
  "blockcode": "window.alert('wuuuuhuuuu');\n",
  "status": "received"
}
```

### Felder:
- `timestamp`: Zeitpunkt der Speicherung (ISO-8601)
- `source`: `"terminal"` (Herkunft)
- `user`: Benutzername, falls übergeben, sonst `"unknown"`
- `blockcode`: Der gesendete JavaScript-Code
- `status`: `"received"` (Standardstatus)

---

## 🔐 Dateiberechtigungen

Stelle sicher:
```bash
chmod 666 /var/www/html/tmp/blockly_terminal_log.jsonl
chown www-data:www-data /var/www/html/tmp/blockly_terminal_log.jsonl
chmod 777 /var/www/html/tmp
```

---

## 🧪 Test über Terminal

```bash
curl -X POST http://localhost/crumbapi/blockly-terminal \
     -H "Content-Type: application/json" \
     -d '{"blockcode": "window.alert(\"Test\")"}'
```

---

## 🛠 Fehlerbehandlung

Falls kein Eintrag geschrieben wird:
- Prüfe Route: `/crumbapi/blockly-terminal` muss im `CrumbapiController` landen.
- Fallback-Log:  
  ```
  /var/www/html/tmp/fallback_debug.log
  ```

---

## 🌳 Fazit

💾 Das Logsystem ist der Speicher der kindlichen Terminalaktionen im Crumbforest.  
✨ Jeder `alert()` ist ein kleiner Ruf in den Wald – und wird gehört.

---

🦉 *„Das Echo ist der Wald, der antwortet.“*

