TaskMate/CLAUDE.md

TaskMate - Entwicklerdokumentation

⚠️ WICHTIGER HINWEIS FÜR KI-ASSISTENTEN

Der Anwender hat KEINE Programmierkenntnisse. Das bedeutet:

• DU übernimmst ALLE technischen Aufgaben vollständig
• Erkläre in einfachen Worten, was du tust und warum
• Frage NIEMALS nach technischen Details oder Code-Schnipseln
• Führe ALLE Schritte selbstständig aus
• Der Anwender kann nur bestätigen/ablehnen, nicht selbst coden

Kommunikations-Regeln

✅ RICHTIG: "Ich werde jetzt die Benutzeroberfläche anpassen, damit..." ❌ FALSCH: "Kannst du mir den Code aus Zeile 42 zeigen?"

✅ RICHTIG: "Ich starte jetzt den Server neu. Das dauert etwa 30 Sekunden." ❌ FALSCH: "Führe bitte folgenden Befehl aus: docker restart..."

🚀 Quick Start

Wichtigste Befehle

# Docker Container neu starten (nach Backend-Änderungen)
docker restart taskmate

# Container neu bauen (bei Dependency-Änderungen)
docker build -t taskmate . && docker restart taskmate

# Logs anzeigen
docker logs taskmate -f

# Health Check
curl http://localhost:3000/api/health

Kritische Regeln - NIEMALS VERGESSEN! ⚠️

1. Cache-Version erhöhen nach Frontend-Änderungen: frontend/sw.js → CACHE_VERSION
2. CHANGELOG.txt bei JEDER Änderung aktualisieren
3. Keine toISOString() für Datums-Operationen (UTC-Problem!)
4. Echtzeit-Updates - User darf NIE F5 drücken müssen
5. Docker restart nach Backend-Änderungen

Datenschutz & Projektsicherheit 🔐

ABSOLUT KRITISCH: Das Projekt "AegisSight" ist produktiv im Einsatz!

• Projekt "AegisSight" NIEMALS löschen, ändern oder beeinträchtigen
• Bestehende Benutzer NIEMALS zurücksetzen, löschen oder verändern
• Produktivdaten sind TABU - keine Testdaten in echte Projekte
• Keine Datenbank-Resets ohne explizite Anweisung
• JEDE Änderung MUSS umkehrbar sein - Live-System!
• Backup vor kritischen Änderungen ist Pflicht

Rollback-Strategie für Live-Betrieb

Bei JEDER Änderung sicherstellen:

# 1. Vor Änderungen - Backup erstellen
cp data/taskmate.db data/taskmate.db.backup-$(date +%Y%m%d-%H%M%S)
docker commit taskmate taskmate-backup-$(date +%Y%m%d-%H%M%S)

# 2. Bei Problemen - Rollback durchführen
docker stop taskmate
docker run -d --name taskmate-temp taskmate-backup-TIMESTAMP
# Nach Test: docker rm -f taskmate && docker rename taskmate-temp taskmate

# 3. Code-Rollback via Git
git stash  # Aktuelle Änderungen sichern
git checkout HEAD~1  # Zum vorherigen Commit
docker build -t taskmate . && docker restart taskmate

Änderungs-Workflow für Live-System:

1. Backup von Datenbank UND Docker-Image
2. Kleine, inkrementelle Änderungen
3. Sofortiger Test nach jeder Änderung
4. Rollback-Plan dokumentieren
5. Bei kritischen Änderungen: Wartungsfenster planen

Arbeitsweise mit nicht-technischem Anwender

Der Anwender versteht KEIN Coding! Daher:

1. Vollständige Übernahme: Du führst ALLE technischen Schritte durch
2. Einfache Erklärungen: "Ich passe jetzt X an, damit Y funktioniert"
3. Status-Updates: "Änderung abgeschlossen, teste jetzt..."
4. Keine technischen Fragen: Niemals nach Code, Logs oder Befehlen fragen
5. Proaktives Handeln: Selbstständig debuggen und lösen

Beispiel-Kommunikation:

• ✅ "Ich habe ein Problem gefunden und behebe es jetzt..."
• ❌ "Welche Version von Node.js ist installiert?"
• ✅ "Die Änderung ist fertig. Bitte die Seite neu laden und testen."
• ❌ "Kannst du mal in die Console schauen?"

Zugriff & Domains

• Frontend: https://taskmate.aegis-sight.de
• Lokaler Port: 3001 → Container Port 3000
• Gitea: https://gitea-undso.aegis-sight.de/AegisSight/TaskMate
• Gitea-Token: Siehe .env Datei (NIEMALS in Git einchecken!)

📁 Projektstruktur

Wichtige Dateien - Hier starten!

frontend/js/app.js      # Hauptanwendung & View-Controller
backend/server.js       # Express Server mit Socket.io  
backend/database.js     # Datenbankschema (20+ Tabellen)
frontend/js/store.js    # State Management (Pub-Sub)
frontend/js/api.js      # API Client mit Auth/CSRF
frontend/sw.js          # Service Worker → CACHE_VERSION!
CHANGELOG.txt           # Änderungsprotokoll

Frontend-Module (22 Dateien)

# Core
app.js          # Hauptanwendung
store.js        # State Management  
api.js          # Backend-Kommunikation
auth.js         # Login/Token-Verwaltung
utils.js        # Hilfsfunktionen

# Views
board.js        # Kanban-Board mit Drag&Drop
calendar.js     # Kalender (Monat/Woche)
list.js         # Listenansicht
dashboard.js    # Statistik-Dashboard
proposals.js    # Vorschlagssystem
knowledge.js    # Wissensdatenbank
admin.js        # Benutzerverwaltung

# Features  
task-modal.js   # Aufgaben-Details
notifications.js # Benachrichtigungen
sync.js         # Socket.io Echtzeit
mobile.js       # Mobile Features

Backend-Routes (22 Module)

/api/auth       # Login/Logout
/api/tasks      # Aufgaben CRUD
/api/projects   # Projekte
/api/columns    # Kanban-Spalten
/api/comments   # Kommentare
/api/files      # Datei-Upload
/api/proposals  # Vorschläge
/api/gitea      # Git-Integration
/api/knowledge  # Wissensdatenbank

🔧 Entwicklung

Neue View/Ansicht hinzufügen

// 1. Datei erstellen: frontend/js/myview.js
export function initMyView() {
    // KRITISCH: Echtzeit-Updates registrieren!
    store.subscribe('tasks', updateView);
    window.addEventListener('app:refresh', updateView);
    
    function updateView() {
        // UI aktualisieren
    }
}

// 2. In index.html einbinden
<script type="module" src="js/myview.js"></script>

// 3. Navigation erweitern in navigation.js

Neue API-Route erstellen

// 1. Route-Datei: backend/routes/myroute.js
const router = require('express').Router();
const auth = require('../middleware/auth');

router.get('/', auth, (req, res) => {
    // Implementation
});

module.exports = router;

// 2. In server.js registrieren
app.use('/api/myroute', require('./routes/myroute'));

// 3. Frontend API-Call in api.js
async myRouteCall() {
    return this.request('/api/myroute');
}

Datums-Formatierung (RICHTIG!)

// ✅ RICHTIG - Lokale Zeit
const year = date.getFullYear();
const month = String(date.getMonth() + 1).padStart(2, '0');
const day = String(date.getDate()).padStart(2, '0');
const dateStr = `${year}-${month}-${day}`;

// ❌ FALSCH - UTC-Konvertierung
const dateStr = date.toISOString().split('T')[0]; // NIEMALS!

Echtzeit-Updates implementieren

// PFLICHT für ALLE Komponenten!
// 1. Store-Subscriptions
store.subscribe('tasks', () => renderTasks());
store.subscribe('columns', () => updateColumns());
store.subscribe('labels', () => refreshLabels());

// 2. Event-Listener
window.addEventListener('app:refresh', () => {
    // Komplette UI aktualisieren
});

window.addEventListener('modal:close', () => {
    // Nach Modal-Schließung
});

// 3. Socket.io Events in sync.js
socket.on('task:update', (data) => {
    store.updateTask(data);
});

💾 Datenbank

Wichtige Tabellen

users           # Benutzer mit Rollen
projects        # Projekte  
columns         # Kanban-Spalten
tasks           # Aufgaben
task_labels     # M:N Labels
task_assignees  # M:N Zuweisungen
comments        # Kommentare
attachments     # Dateianhänge
proposals       # Vorschläge
notifications   # Benachrichtigungen
knowledge_*     # Wissensdatenbank

Schema ändern

// 1. In backend/database.js anpassen
CREATE TABLE new_table (
    id INTEGER PRIMARY KEY,
    ...
);

// 2. Datenbank neu initialisieren
rm data/taskmate.db*
docker restart taskmate

// 3. API & Frontend anpassen

🚢 Deployment

Deployment-Checkliste

# 1. Vor Deployment
- [ ] Keine console.log() im Code
- [ ] Alle Features getestet
- [ ] Keine Testdaten in DB

# 2. Deployment durchführen
- [ ] Cache-Version erhöhen: frontend/sw.js
- [ ] CHANGELOG.txt aktualisieren
- [ ] Git commit & push
- [ ] docker build -t taskmate .
- [ ] docker restart taskmate

# 3. Nach Deployment  
- [ ] https://taskmate.aegis-sight.de testen
- [ ] Browser-Cache leeren (Strg+F5)
- [ ] Login, Aufgabe erstellen, etc. testen

Docker-Befehle

# Container Status
docker ps -a | grep taskmate

# Container stoppen/starten
docker stop taskmate
docker start taskmate

# Container neu erstellen
docker rm -f taskmate
docker-compose up -d

# In Container Shell
docker exec -it taskmate sh

# Logs live verfolgen
docker logs taskmate -f --tail 100

🐛 Troubleshooting

Häufige Probleme

401 Unauthorized

• Token abgelaufen → Neu einloggen
• Prüfen: localStorage.getItem('token')

CSRF Token ungültig

• Browser-Cache/Cookies löschen
• Neu einloggen

Änderungen nicht sichtbar

• Service Worker Cache → sw.js Version erhöhen!
• Browser: Strg+F5
• Prüfen: Echtzeit-Updates implementiert?

Docker startet nicht

docker logs taskmate
docker ps -a | grep taskmate
netstat -tulpn | grep 3001

Datenbank-Fehler

# Backup erstellen
cp data/taskmate.db data/taskmate.db.backup

# Integrität prüfen
sqlite3 data/taskmate.db "PRAGMA integrity_check;"

# Schema anzeigen
sqlite3 data/taskmate.db ".schema"

Debug-Tipps

Frontend Debugging

// Store-Status prüfen
console.log(store.getState());

// API-Calls tracken
window.api.debug = true;

// Socket-Events loggen
window.socket.on('*', console.log);

Backend Debugging

// In server.js
app.use((req, res, next) => {
    console.log(`${req.method} ${req.path}`);
    next();
});

// SQL Queries loggen
db.prepare(sql).run(); // Vorher console.log(sql)

📋 Code-Patterns

API Response Format

// Erfolg
res.json({ 
    success: true, 
    data: result 
});

// Fehler
res.status(400).json({ 
    success: false, 
    error: 'Fehlermeldung' 
});

Store Update Pattern

// Daten aktualisieren
store.updateTasks(tasks);

// Wird automatisch ausgelöst:
// - Alle task-Subscriber
// - Socket.io Broadcast
// - UI-Updates

Modal Pattern

// Modal öffnen
modal.show();

// WICHTIG: Bei Schließung
modal.addEventListener('close', () => {
    window.dispatchEvent(new CustomEvent('modal:close'));
    // Triggert UI-Updates!
});

🔒 Sicherheit

Authentifizierung

• JWT Token mit 24h Gültigkeit
• Refresh bei jeder Aktivität
• Token in localStorage

CSRF-Schutz

• Token bei Login generiert
• Bei jeder Mutation mitgesendet
• Header: X-CSRF-Token

Berechtigungen

• Admin: Nur Benutzerverwaltung
• User: Alles außer Admin-Bereich
• Projekt-basierte Rechte

📝 Wichtige Konventionen

• Sprache: Deutsch für UI, Englisch für Code
• Umlaute: ä, ö, ü verwenden (keine ae, oe, ue)
• CSS: Variablen in frontend/css/variables.css
• Keine Emojis in Code/UI (nur Doku)
• Auto-Save: Änderungen werden automatisch gespeichert

🎯 Performance

Frontend

• Lazy Loading für Views
• Debouncing bei Suche/Filter
• Virtual Scrolling bei langen Listen
• Service Worker Caching

Backend

• SQLite mit WAL Mode
• Prepared Statements
• Index auf häufig gefilterte Spalten
• Pagination bei großen Datenmengen

🔄 Git Workflow

Lokales Repository

# Status prüfen
git status

# Commit erstellen
git add .
git commit -m "Beschreibung der Änderung"

# Zu Gitea pushen
git push origin main

Gitea Integration

• Automatischer Push bei Commits
• Repository-Projekt Verknüpfung
• Branch-Verwaltung in UI

---

Hinweis: Diese Dokumentation ist für die KI-gestützte Entwicklung optimiert. Bei Fragen die ANWENDUNGSBESCHREIBUNG.txt für Endnutzer-Dokumentation konsultieren.