docs: bootstrap tg-bot-jetson — board, ADRs, state, session-prompts

ROADMAP mit 7 Items (F-01…F-07) und DAG. STATE aktiviert. CONVENTIONS
projektspezifisch ergänzt. ADRs 0002-0004 (Stack, Whitelist, Spike-Gate).
Kaltstartfähige Prompts für F-01 (Skeleton) und F-02 (API-Spike) erzeugt.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-06-03 23:24:13 +02:00
parent 49cbd00677
commit b7b6766364
10 changed files with 288 additions and 13 deletions

View File

@@ -0,0 +1,15 @@
# 0002 — python-telegram-bot v21 als Bot-Framework
- **Status:** accepted
- **Kontext:** Das Projekt braucht ein Python-Telegram-Bot-Framework.
Alternativen: `aiogram`, `telebot` (pyTelegramBotAPI), `ntelegram`.
- **Entscheidung:** `python-telegram-bot` v21 mit nativem `asyncio` und `httpx`
als HTTP-Client für den Modell-Connector. `uv` als Paketmanager.
- **Gründe:**
- PTB v21 hat die breiteste Doku, Beispiel-Bibliothek und Community für Telegram.
- Asyncio-first: passt zum Streaming-Potenzial künftiger Modell-Antworten.
- `httpx` ist de-facto-Standard für async HTTP in Python 3.11+.
- `uv` ist schneller und reproduzierbarer als plain pip.
- **Konsequenz:** Gesamte Codebasis ist async-first. PTB-Filter-System
(`filters.User`) eignet sich direkt für die Whitelist (F-03).
Keine Sync-Wrapper nötig.

View File

@@ -0,0 +1,16 @@
# 0003 — User-Whitelist via Umgebungsvariable
- **Status:** accepted
- **Kontext:** Nur ausgewählte Telegram-User-IDs dürfen den Bot nutzen.
Optionen: Datenbank, Config-Datei, Env-Var, hardcodiert.
- **Entscheidung:** Env-Var `ALLOWED_USER_IDS` als komma-separierte Liste
ganzer Zahlen (z. B. `ALLOWED_USER_IDS=123456,789012`).
PTB-Filter `filters.User(user_ids=...)` erzwingt die Prüfung deklarativ.
- **Gründe:**
- Kein Deployment-Artefakt für die Liste nötig — reicht für v1.
- Änderung ohne Code-Deploy: Service neu starten genügt.
- Keine persistente Zustandsverwaltung, kein Datenbankrisiko.
- Leicht in `.env`-Datei und Docker/systemd-Unit einzutragen.
- **Konsequenz:** Für v2 (dynamisches Hinzufügen per Admin-Command) muss
ein Persistenz-Layer (SQLite o. ä.) ergänzt werden — das ist ein eigenes
Board-Item und ändert diese Entscheidung.

View File

@@ -0,0 +1,15 @@
# 0004 — Modell-API-Format: erst Spike, dann Connector
- **Status:** accepted
- **Kontext:** Der Jetson Orin Nano Super hostet ein lokales Modell. Das
Endpoint-Schema ist nicht festgelegt (mögliche Backends: Ollama,
llama.cpp-HTTP-Server, vLLM, custom FastAPI). Kein golden oracle.
- **Entscheidung:** F-02 (🔬 Spike) läuft **vor** F-05 (🔌 Connector).
Der Spike bestimmt das tatsächliche API-Schema und erzeugt eine
Mini-Spec (`spike/model-api/spec.md`). F-05 portiert gegen diese Spec.
- **GO-Kriterium:** Python-Skript sendet eine Test-Nachricht und empfängt
eine nicht-leere Antwort vom lokalen Server. Latenz < 30 s akzeptabel.
- **NO-GO-Kriterium:** Kein Endpoint erreichbar oder Antwort-Format
vollständig undokumentiert Human-Entscheid, welcher Backend aufzusetzen.
- **Konsequenz:** F-05 bleibt bis Spike + GO. Wenn NO-GO: blocked-extern.
Spike-Branch `spike/model-api` wird nach GO verworfen; Spec bleibt in `docs/`.