till/managarten
1
0
Fork 0
mirror of https://github.com/Memo-2023/mana-monorepo.git synced 2026-05-16 00:59:40 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

docs: add unified Telegram bots documentation

Browse source 
- Document all 3 existing bots (stats, ollama, project-doc)
- Include common architecture, environment variables, and deployment
- Add comprehensive plan for telegram-calendar-bot
- Cover features, commands, database schema, and message formatters

https://claude.ai/code/session_01LwmhvhKpEsvVtY1ZKhYu6f
This commit is contained in:
Claude 2026-01-27 19:22:40 +00:00
parent e72f3b7865
commit 48c5ff31dc
No known key found for this signature in database
1 changed files with 724 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

724
docs/TELEGRAM_BOTS.md Normal file
View file

@ -0,0 +1,724 @@
# Telegram Bots
Dokumentation aller Telegram-Bots im ManaCore Monorepo.
## Übersicht
| Bot | Port | Zweck | Status |
|-----|------|-------|--------|
| [telegram-stats-bot](#telegram-stats-bot) | 3300 | Analytics & Statistiken von Umami | ✅ Aktiv |
| [telegram-ollama-bot](#telegram-ollama-bot) | 3301 | Lokale LLM-Inferenz via Ollama | ✅ Aktiv |
| [telegram-project-doc-bot](#telegram-project-doc-bot) | 3302 | Projektdokumentation & Blogpost-Generierung | ✅ Aktiv |
| [telegram-calendar-bot](#telegram-calendar-bot) | 3303 | Kalender-Termine & Erinnerungen | 📋 Geplant |
## Gemeinsame Architektur
Alle Bots teilen dieselbe technische Basis:
```
┌─────────────────────────────────────────────────────────────┐
│ Telegram Bot Service │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ NestJS 10 │ │ Telegraf │ │ nestjs-telegraf │ │
│ │ Framework │ │ Library │ │ Integration │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Standard Module Structure │ │
│ │ ├── src/main.ts # Entry point │ │
│ │ ├── src/app.module.ts # Root module │ │
│ │ ├── src/health.controller.ts # /health endpoint │ │
│ │ ├── src/config/ # Configuration │ │
│ │ └── src/bot/ # Bot commands │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Gemeinsame Features
- **Health Endpoint**: Alle Bots haben `/health` für Monitoring
- **User-Beschränkung**: Optional via `TELEGRAM_ALLOWED_USERS`
- **Docker Support**: Dockerfile für Container-Deployment
- **Graceful Shutdown**: Sauberes Beenden bei SIGTERM
### Standard Environment Variables
```env
# Alle Bots
PORT=33xx # Port für Health-Endpoint
TELEGRAM_BOT_TOKEN=xxx # Bot Token von @BotFather
TELEGRAM_ALLOWED_USERS=123,456 # Optional: Erlaubte User IDs
NODE_ENV=production # Environment
```
---
## telegram-stats-bot
**Zweck:** Liefert Analytics und Statistiken von Umami (stats.mana.how) via Telegram.
### Features
- Übersicht aller App-Statistiken (30 Tage)
- Tägliche und wöchentliche Reports
- Echtzeit-Besucherzahlen
- Registrierte User-Statistiken
- Automatische geplante Reports
### Commands
| Command | Beschreibung |
|---------|--------------|
| `/start` | Hilfe anzeigen |
| `/stats` | Übersicht aller Apps (letzte 30 Tage) |
| `/today` | Heutige Statistiken |
| `/week` | Wochenstatistiken |
| `/realtime` | Aktive Besucher jetzt |
| `/users` | Registrierte User-Statistiken |
| `/help` | Verfügbare Commands anzeigen |
### Scheduled Reports
| Report | Schedule | Timezone |
|--------|----------|----------|
| Täglich | 09:00 | Europe/Berlin |
| Wöchentlich | Montag 09:00 | Europe/Berlin |
### Environment Variables
```env
PORT=3300
TZ=Europe/Berlin
# Telegram
TELEGRAM_BOT_TOKEN=xxx
TELEGRAM_CHAT_ID=xxx # Chat für automatische Reports
# Umami
UMAMI_API_URL=http://umami:3000
UMAMI_USERNAME=admin
UMAMI_PASSWORD=xxx
# Database (optional, für User-Counts)
DATABASE_URL=postgresql://...
```
### Projekt-Struktur
```
services/telegram-stats-bot/
├── src/
│ ├── main.ts
│ ├── app.module.ts
│ ├── health.controller.ts
│ ├── config/
│ │ └── configuration.ts # Website IDs
│ ├── bot/
│ │ ├── bot.module.ts
│ │ ├── bot.service.ts # Send messages
│ │ └── bot.update.ts # Command handlers
│ ├── umami/
│ │ └── umami.service.ts # Umami API client
│ ├── analytics/
│ │ ├── analytics.service.ts # Data aggregation
│ │ └── formatters.ts # Message formatters
│ ├── users/
│ │ └── users.service.ts # User count from auth DB
│ └── scheduler/
│ └── report.scheduler.ts # Cron jobs
└── Dockerfile
```
### Neue Website hinzufügen
In `src/config/configuration.ts`:
```typescript
export const WEBSITE_IDS: Record<string, string> = {
'new-app-webapp': 'uuid-from-umami',
};
export const DISPLAY_NAMES: Record<string, string> = {
'new-app-webapp': 'New App',
};
```
---
## telegram-ollama-bot
**Zweck:** Lokale LLM-Inferenz via Ollama auf dem Mac Mini Server.
### Features
- Chat mit lokalem LLM (Gemma 3 4B Standard)
- Mehrere Konversations-Modi
- Dynamischer Modell-Wechsel
- Chat-Verlauf (10 Nachrichten Kontext)
- Automatisches Message-Splitting bei langen Antworten
### Commands
| Command | Beschreibung |
|---------|--------------|
| `/start` | Hilfe anzeigen |
| `/help` | Hilfe anzeigen |
| `/models` | Verfügbare Modelle auflisten |
| `/model [name]` | Modell wechseln |
| `/mode [modus]` | System-Prompt ändern |
| `/clear` | Chat-Verlauf löschen |
| `/status` | Ollama-Status prüfen |
### Modi
| Modus | Beschreibung |
|-------|--------------|
| `default` | Allgemeiner Assistent |
| `classify` | Text-Klassifizierung |
| `summarize` | Zusammenfassungen |
| `translate` | Übersetzungen |
| `code` | Programmier-Hilfe |
### Environment Variables
```env
PORT=3301
# Telegram
TELEGRAM_BOT_TOKEN=xxx
TELEGRAM_ALLOWED_USERS=123,456 # Optional
# Ollama
OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=gemma3:4b
OLLAMA_TIMEOUT=120000 # Timeout in ms
```
### Projekt-Struktur
```
services/telegram-ollama-bot/
├── src/
│ ├── main.ts
│ ├── app.module.ts
│ ├── health.controller.ts
│ ├── config/
│ │ └── configuration.ts # System Prompts
│ ├── bot/
│ │ ├── bot.module.ts
│ │ └── bot.update.ts # Command handlers
│ └── ollama/
│ ├── ollama.module.ts
│ └── ollama.service.ts # Ollama API client
└── Dockerfile
```
### Deployment
**Option 1: Docker**
```yaml
telegram-ollama-bot:
image: ghcr.io/memo-2023/telegram-ollama-bot:latest
environment:
TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN}
OLLAMA_URL: http://host.docker.internal:11434
```
**Option 2: Nativ (empfohlen für Performance)**
```bash
cd ~/projects/manacore-monorepo/services/telegram-ollama-bot
pnpm build
TELEGRAM_BOT_TOKEN=xxx pnpm start:prod
```
---
## telegram-project-doc-bot
**Zweck:** Sammelt Projektdokumentation (Fotos, Sprachnotizen, Text) und generiert automatisch Blogbeiträge.
### Features
- Multi-Projekt-Verwaltung
- Foto-Speicherung in S3
- Automatische Voice-Transkription (Whisper)
- Text-Notizen
- AI-Blogpost-Generierung (mehrere Stile)
- Markdown-Export
### Commands
| Command | Beschreibung |
|---------|--------------|
| `/start` | Hilfe anzeigen |
| `/help` | Hilfe anzeigen |
| `/new [Name]` | Neues Projekt erstellen |
| `/projects` | Alle Projekte auflisten |
| `/switch [ID]` | Projekt wechseln |
| `/status` | Status des aktiven Projekts |
| `/archive` | Projekt archivieren |
| `/generate` | Blogbeitrag generieren |
| `/generate [Stil]` | Mit bestimmtem Stil generieren |
| `/styles` | Verfügbare Stile anzeigen |
| `/export` | Letzte Generierung als Datei |
### Blog-Stile
| Stil | Beschreibung |
|------|--------------|
| `casual` | Locker & persönlich |
| `formal` | Professionell & sachlich |
| `tutorial` | Anleitung mit Schritten |
| `diary` | Tagebuch-Stil |
### User Flow
```
1. /new Gartenhaus-Renovierung → Projekt erstellen
2. 📷 Foto senden → Wird gespeichert
3. 🎤 Sprachnotiz senden → Transkribiert + gespeichert
4. "Heute das Fundament gegossen" → Text-Notiz
5. /status → Übersicht
6. /generate tutorial → Blogbeitrag erstellen
7. /export → Als .md Datei
```
### Environment Variables
```env
PORT=3302
# Telegram
TELEGRAM_BOT_TOKEN=xxx
TELEGRAM_ALLOWED_USERS=123,456
# Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/projectdoc
# Storage (MinIO)
S3_ENDPOINT=http://localhost:9000
S3_REGION=us-east-1
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
S3_BUCKET=projectdoc-storage
# AI - Transcription
OPENAI_API_KEY=sk-xxx
# AI - Generation
LLM_PROVIDER=ollama # ollama oder openai
OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=gemma3:4b
```
### Projekt-Struktur
```
services/telegram-project-doc-bot/
├── src/
│ ├── main.ts
│ ├── app.module.ts
│ ├── health.controller.ts
│ ├── config/
│ │ └── configuration.ts # Blog-Stile
│ ├── database/
│ │ ├── database.module.ts
│ │ └── schema.ts # Drizzle schema
│ ├── bot/
│ │ ├── bot.module.ts
│ │ └── bot.update.ts # Command handlers
│ ├── project/
│ │ └── project.service.ts # Projekt CRUD
│ ├── media/
│ │ ├── media.service.ts # Foto/Voice/Text
│ │ └── storage.service.ts # S3 Upload/Download
│ ├── transcription/
│ │ └── transcription.service.ts # Whisper API
│ └── generation/
│ └── generation.service.ts # Blogpost AI
├── drizzle/
├── drizzle.config.ts
└── Dockerfile
```
### Datenbank-Schema
```
projects
├── id (UUID)
├── telegram_user_id (INT)
├── name (TEXT)
├── description (TEXT)
├── status (TEXT: active, archived, completed)
├── created_at, updated_at
media_items
├── id (UUID)
├── project_id (UUID FK)
├── type (TEXT: photo, voice, text)
├── storage_key (TEXT)
├── caption (TEXT)
├── transcription (TEXT)
├── ai_description (TEXT)
├── metadata (JSONB)
├── telegram_file_id (TEXT)
├── order_index (INT)
├── created_at
generations
├── id (UUID)
├── project_id (UUID FK)
├── style (TEXT)
├── content (TEXT - Markdown)
├── pdf_key (TEXT)
├── is_latest (BOOL)
├── created_at
```
---
## telegram-calendar-bot
**Zweck:** Telegram-Integration für die Calendar-App mit Termin-Abfragen, Quick-Add und Erinnerungen.
**Status:** 📋 Geplant
Siehe [Plan](#telegram-calendar-bot-plan) unten für Details.
---
## Entwicklung
### Neuen Bot erstellen
1. **Bot bei Telegram registrieren:**
- Öffne @BotFather in Telegram
- Sende `/newbot`
- Wähle Namen und Username
- Kopiere den Token
2. **Service erstellen:**
```bash
mkdir -p services/telegram-{name}-bot/src
cd services/telegram-{name}-bot
pnpm init
```
3. **Dependencies installieren:**
```bash
pnpm add @nestjs/core @nestjs/common @nestjs/config nestjs-telegraf telegraf
pnpm add -D @types/node typescript
```
4. **Standard-Struktur anlegen:**
```
src/
├── main.ts
├── app.module.ts
├── health.controller.ts
├── config/
│ └── configuration.ts
└── bot/
├── bot.module.ts
└── bot.update.ts
```
### Lokale Entwicklung
```bash
# Bot starten (aus dem Service-Verzeichnis)
pnpm start:dev
# Health Check testen
curl http://localhost:33xx/health
```
### Docker Build
```bash
# Aus dem Monorepo-Root
docker build -f services/telegram-{name}-bot/Dockerfile -t telegram-{name}-bot .
```
---
## Deployment
### Mac Mini Server
Alle Bots laufen auf dem Mac Mini Server. Status prüfen:
```bash
ssh mana-server
./scripts/mac-mini/status.sh
```
### Docker Compose
```yaml
# docker-compose.macmini.yml
services:
telegram-stats-bot:
image: ghcr.io/memo-2023/telegram-stats-bot:latest
restart: always
ports:
- "3300:3300"
environment:
PORT: 3300
TELEGRAM_BOT_TOKEN: ${TELEGRAM_STATS_BOT_TOKEN}
# ...
telegram-ollama-bot:
image: ghcr.io/memo-2023/telegram-ollama-bot:latest
restart: always
ports:
- "3301:3301"
environment:
PORT: 3301
TELEGRAM_BOT_TOKEN: ${TELEGRAM_OLLAMA_BOT_TOKEN}
OLLAMA_URL: http://host.docker.internal:11434
# ...
telegram-project-doc-bot:
image: ghcr.io/memo-2023/telegram-project-doc-bot:latest
restart: always
ports:
- "3302:3302"
environment:
PORT: 3302
TELEGRAM_BOT_TOKEN: ${TELEGRAM_PROJECT_DOC_BOT_TOKEN}
# ...
```
### Health Checks
```bash
# Alle Bots prüfen
curl http://localhost:3300/health # stats-bot
curl http://localhost:3301/health # ollama-bot
curl http://localhost:3302/health # project-doc-bot
```
---
## Monitoring
### Telegram Notifications
Bei Fehlern werden Benachrichtigungen via telegram-stats-bot gesendet:
```bash
# Health Check Script
./scripts/mac-mini/health-check.sh
```
### Logs
```bash
# Docker Logs
docker logs manacore-telegram-stats-bot -f
docker logs manacore-telegram-ollama-bot -f
docker logs manacore-telegram-project-doc-bot -f
# Native Service Logs
journalctl -u telegram-ollama-bot -f
```
---
## telegram-calendar-bot Plan
### Übersicht
Ein Telegram-Bot für die Calendar-App, der Termin-Abfragen, Quick-Add und Erinnerungen via Telegram ermöglicht.
### Geplante Commands
| Command | Beschreibung |
|---------|--------------|
| `/start` | Hilfe & Account-Verknüpfung |
| `/help` | Verfügbare Commands |
| `/today` | Heutige Termine |
| `/tomorrow` | Morgige Termine |
| `/week` | Wochenübersicht |
| `/next [n]` | Nächste n Termine (default: 5) |
| `/add [text]` | Schnell-Termin via natürliche Sprache |
| `/calendars` | Kalender-Übersicht |
| `/remind` | Erinnerungseinstellungen |
| `/link` | Account verknüpfen |
| `/unlink` | Account trennen |
### Geplante Features
1. **Termin-Abfragen**
- Tägliche/wöchentliche Übersicht
- Suche nach Terminen
- Kalender-Filter
2. **Quick-Add**
- Natürliche Spracheingabe: "Meeting morgen um 14 Uhr"
- Strukturiertes Format: `/add Meeting | 2024-12-20 14:00 | 1h`
- Kalender-Auswahl
3. **Erinnerungen via Telegram**
- Push-Notifications für anstehende Termine
- Konfigurierbare Vorlaufzeit
- Morgen-Briefing (tägliche Zusammenfassung)
4. **Account-Verknüpfung**
- OAuth oder Token-basierte Verknüpfung
- Mehrere Telegram-Accounts pro User möglich
### Technische Architektur
```
┌─────────────────────────────────────────────────────────────┐
│ telegram-calendar-bot (Port 3303) │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Bot │ │ Calendar │ │ Reminder │ │
│ │ Module │ │ Client │ │ Scheduler │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Calendar Backend API (Port 3016) │ │
│ │ GET /api/v1/events?start=...&end=... │ │
│ │ POST /api/v1/events │ │
│ │ GET /api/v1/calendars │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ PostgreSQL (calendar database) │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Environment Variables (geplant)
```env
PORT=3303
# Telegram
TELEGRAM_BOT_TOKEN=xxx
TELEGRAM_ALLOWED_USERS=123,456 # Optional
# Calendar Backend
CALENDAR_API_URL=http://localhost:3016
MANA_CORE_AUTH_URL=http://localhost:3001
# Database (für User-Verknüpfungen)
DATABASE_URL=postgresql://...
# Reminder Settings
REMINDER_CHECK_INTERVAL=60000 # Check every minute
MORNING_BRIEFING_TIME=07:00 # Daily briefing time
MORNING_BRIEFING_TIMEZONE=Europe/Berlin
```
### Projekt-Struktur (geplant)
```
services/telegram-calendar-bot/
├── src/
│ ├── main.ts
│ ├── app.module.ts
│ ├── health.controller.ts
│ ├── config/
│ │ └── configuration.ts
│ ├── database/
│ │ ├── database.module.ts
│ │ └── schema.ts # telegram_users Tabelle
│ ├── bot/
│ │ ├── bot.module.ts
│ │ └── bot.update.ts # Command handlers
│ ├── calendar/
│ │ ├── calendar.module.ts
│ │ └── calendar.client.ts # Calendar API client
│ ├── reminder/
│ │ ├── reminder.module.ts
│ │ └── reminder.scheduler.ts # Cron für Erinnerungen
│ └── nlp/
│ ├── nlp.module.ts
│ └── nlp.service.ts # Natürliche Spracheingabe
├── drizzle/
├── drizzle.config.ts
└── Dockerfile
```
### Datenbank-Schema (geplant)
```sql
-- telegram_users: Verknüpfung Telegram <-> ManaCore
CREATE TABLE telegram_users (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
telegram_user_id BIGINT UNIQUE NOT NULL,
telegram_username VARCHAR(255),
mana_user_id UUID NOT NULL,
access_token TEXT,
refresh_token TEXT,
token_expires_at TIMESTAMP WITH TIME ZONE,
settings JSONB DEFAULT '{}',
is_active BOOLEAN DEFAULT true,
linked_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- telegram_reminder_settings: User-spezifische Einstellungen
CREATE TABLE telegram_reminder_settings (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
telegram_user_id BIGINT REFERENCES telegram_users(telegram_user_id),
default_reminder_minutes INTEGER DEFAULT 15,
morning_briefing_enabled BOOLEAN DEFAULT false,
morning_briefing_time TIME DEFAULT '07:00',
timezone VARCHAR(100) DEFAULT 'Europe/Berlin',
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
```
### Message Formatters (Beispiele)
**Tagesübersicht:**
```
📅 Deine Termine für heute (Mo, 27. Januar)
🔵 09:00 - 10:00 | Team Standup
📍 Zoom Meeting
🟢 12:30 - 13:30 | Mittagessen mit Lisa
📍 Restaurant Bella
🔴 15:00 - 16:30 | Projekt Review
📍 Konferenzraum A
📝 Q4 Ergebnisse präsentieren
───────────────
3 Termine heute
```
**Quick-Add Bestätigung:**
```
✅ Termin erstellt!
📌 Meeting mit Team
📅 Morgen, 14:00 - 15:00
📍 Büro
🗓️ Kalender: Arbeit
/undo zum Rückgängig machen
```
**Erinnerung:**
```
⏰ Erinnerung in 15 Minuten
📌 Team Standup
⏱️ 09:00 - 10:00
📍 Zoom Meeting
[Zum Termin] [Verschieben] [Absagen]
```