# 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
```bash
# 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:

```bash
# 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
```javascript
// 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
```javascript
// 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!)
```javascript
// ✅ 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
```javascript
// 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
```sql
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
```javascript
// 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
```bash
# 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
```bash
# 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**
```bash
docker logs taskmate
docker ps -a | grep taskmate
netstat -tulpn | grep 3001
```

**Datenbank-Fehler**
```bash
# 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**
```javascript
// 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**
```javascript
// 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
```javascript
// Erfolg
res.json({ 
    success: true, 
    data: result 
});

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

### Store Update Pattern
```javascript
// Daten aktualisieren
store.updateTasks(tasks);

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

### Modal Pattern
```javascript
// 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
```bash
# 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.