# 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

**⚠️ NUTZERDATEN-SCHUTZ - ABSOLUTES VERBOT**: 
- **KEINE Änderungen an Nutzerdaten oder Kennwörtern**
- **Geschützte Benutzer (NICHT modifizieren)**:
  - admin
  - Hendrik (hendrik_gebhardt@gmx.de)
  - Monami (momohomma@googlemail.com)
- **Diese Benutzer sind produktiv im Einsatz**
- **Keine Passwort-Resets oder Änderungen an diesen Accounts**
- **Bei Anmeldeproblemen: Nur Debugging, keine Datenänderung**

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

### KRITISCHES PROBLEM: Frontend-Änderungen werden nicht sichtbar

**Problem**: Frontend-Dateien (HTML, CSS, JS) werden beim Docker Build nach `/app/public/` kopiert und sind NICHT live gemountet. Änderungen in `/home/claude-dev/TaskMate/frontend/` werden daher nicht automatisch übernommen.

**Symptome**:
- CSS/JS-Änderungen funktionieren nicht trotz Browser-Cache-Löschung
- Service Worker Cache-Version Erhöhung hilft nicht
- Änderungen werden sporadisch nach längerer Zeit sichtbar

**Ursache**:
1. **Dockerfile kopiert Frontend-Dateien**: `COPY frontend/ ./public/`
2. **Express.js cached statische Dateien** mit ETags und Last-Modified Headers
3. **Mehrschichtiges Caching**: Service Worker + Browser + Express.js

**LÖSUNG A - Sofortige Änderungen (Development)**:
```bash
# Einzelne Datei kopieren
docker cp frontend/css/style.css taskmate:/app/public/css/style.css

# Mehrere Dateien kopieren
docker cp frontend/js/app.js taskmate:/app/public/js/app.js
docker cp frontend/index.html taskmate:/app/public/index.html

# CSS + JS zusammen kopieren
docker cp frontend/css/ taskmate:/app/public/css/
docker cp frontend/js/ taskmate:/app/public/js/
```

**LÖSUNG B - Vollständige Aktualisierung (Production)**:
```bash
# Docker Image neu bauen und Container ersetzen
docker build -t taskmate . && docker restart taskmate
```

**Express.js Caching deaktiviert**:
```javascript
// In server.js - statische Dateien ohne Caching
app.use(express.static(path.join(__dirname, 'public'), {
  etag: false,
  lastModified: false,
  cacheControl: false,
  setHeaders: (res, path) => {
    res.setHeader('Cache-Control', 'no-store, no-cache, must-revalidate');
  }
}));
```

**Debugging-Workflow**:
1. Prüfe Datei-Timestamps im Container: `docker exec taskmate ls -la /app/public/css/`
2. Vergleiche mit lokalen Dateien: `ls -la frontend/css/`
3. Bei Diskrepanz: Files mit `docker cp` aktualisieren
4. Bei JavaScript-Problemen: Browser-Console auf Fehler prüfen

**Warum passiert das**:
- Container-Pfad `/app/public/` = Static Files (nicht live)
- Container-Pfad `/app/taskmate-source/` = Git-Operationen (live gemountet)
- Frontend wird NUR beim Build-Time kopiert, nicht zur Laufzeit

## 🚨 KRITISCHE LEKTIONEN AUS PROBLEMEN

### ⚠️ Kontakte-Modul Implementation Probleme (07.01.2025)

**FEHLER 1: Backend API-Route nicht gefunden (404)**
- **Problem**: GET /api/contacts gibt 404 - Endpoint nicht gefunden
- **Ursache**: Backend-Dateien nicht im Docker-Container, Container nicht neu gestartet
- **Lösung**: Backend-Dateien kopieren und Container neu starten
- **Prävention**:
  ```bash
  # Backend-Änderungen: Alle Dateien kopieren
  docker cp backend/routes/contacts.js taskmate:/app/routes/
  docker cp backend/middleware/validation.js taskmate:/app/middleware/
  docker cp backend/server.js taskmate:/app/server.js
  docker restart taskmate  # IMMER nach Backend-Änderungen
  ```

**FEHLER 2: Database Table existiert nicht (500 Internal Server Error)**
- **Problem**: "no such table: contacts" - Tabelle wurde nicht erstellt
- **Ursache**: database.js Änderungen nicht übernommen, bestehende DB erweitert sich nicht automatisch
- **Lösung**: database.js kopieren + Tabelle manuell erstellen
- **Pattern für neue Tabellen**:
  ```bash
  docker cp backend/database.js taskmate:/app/database.js
  docker exec taskmate node -e "
    const Database = require('better-sqlite3');
    const db = new Database('/app/data/taskmate.db');
    db.exec('CREATE TABLE IF NOT EXISTS new_table (...);');
    console.log('Table created successfully');
  "
  ```

**FEHLER 3: store.showMessage ist undefined**
- **Problem**: `store.showMessage()` Funktion existiert nicht
- **Ursache**: Falsche API für Toast-Nachrichten
- **Lösung**: Verwende `window.dispatchEvent` mit `toast:show`
- **Pattern für Toast-Messages**:
  ```javascript
  // FALSCH: store.showMessage('Text', 'success')
  // RICHTIG:
  window.dispatchEvent(new CustomEvent('toast:show', {
    detail: { message: 'Text', type: 'success' }
  }));
  ```

**FEHLER 4: Event-Handler nicht gebunden**
- **Problem**: Button-Clicks funktionieren nicht trotz Event-Listener
- **Ursache**: Timing-Problem - DOM noch nicht bereit, Modal-Overlay fehlt
- **Lösung**: Korrekte Modal-Struktur + Overlay-Management
- **Debugging-Pattern**:
  ```javascript
  console.log('[Module] Element check:', this.buttonElement);
  if (this.buttonElement) {
    console.log('[Module] Binding event');
    this.buttonElement.addEventListener('click', () => {
      console.log('[Module] Button clicked!');
    });
  }
  ```

**FEHLER 5: Modal Design inkonsistent**
- **Problem**: Custom Modal-Styles passen nicht zum App-Design
- **Ursache**: Eigene CSS-Klassen statt Standard-Modal-Pattern
- **Lösung**: Standard Modal-Struktur verwenden
- **Standard Modal-Pattern**:
  ```html
  <div class="modal modal-medium hidden">
    <div class="modal-header">
      <h2>Title</h2>
      <button class="modal-close" data-close-modal>&times;</button>
    </div>
    <div class="modal-body"><!-- Content --></div>
    <div class="modal-footer"><!-- Buttons --></div>
  </div>
  ```

### ⚠️ Erinnerung-Implementation Probleme (06.01.2026)

**FEHLER 1: Syntax-Fehler in JavaScript blockierte Login**
- **Problem**: Missing closing brace in calendar.js verhinderte Login komplett
- **Ursache**: Unvollständige Code-Blöcke beim Multi-Edit
- **Lösung**: IMMER Syntax-Check nach JavaScript-Änderungen
- **Prävention**: 
  ```bash
  # Nach JS-Änderungen prüfen:
  node -c frontend/js/calendar.js
  docker logs taskmate --tail 20  # Auf Syntax-Fehler prüfen
  ```

**FEHLER 2: "Verschwundene" Projekte durch 401-Fehler**
- **Problem**: User dachte AegisSight-Projekt sei gelöscht
- **Ursache**: Authentifizierungs-Token abgelaufen, API gibt 401 zurück
- **Diagnose**: `docker logs taskmate` zeigt 401-Fehler
- **Lösung**: Einfach neu anmelden, Daten sind intakt
- **Prävention**: Bei "verschwundenen" Daten IMMER zuerst Auth prüfen

**FEHLER 3: Checkbox-Styling funktioniert nicht**
- **Problem**: CSS-Selektoren greifen nicht, komplexe Pseudo-Element-Struktur
- **Ursache**: Browser-CSS-Konflikte, CSS-Variable-Probleme
- **Lösung**: Direktes Styling nativer Checkboxes mit `appearance: none`
- **Lesson**: Bei CSS-Problemen: **Einfachster Ansatz zuerst**
  ```css
  /* FALSCH: Komplexe Pseudo-Struktur */
  input:checked + span::after { content: '✓'; }
  
  /* RICHTIG: Direktes Styling */
  input[type="checkbox"] {
    appearance: none;
    background: #3B82F6 when :checked;
  }
  ```

**FEHLER 4: Event-Handler Konflikte bei Modal-Updates**
- **Problem**: Dropdown-Handler werden überschrieben
- **Ursache**: Mehrfache Event-Binding ohne Cleanup
- **Lösung**: Element-Kloning für saubere Event-Handler
- **Pattern**:
  ```javascript
  // Event-Handler cleanup durch Klonen
  const newElement = element.cloneNode(true);
  element.parentNode.replaceChild(newElement, element);
  // Dann neue Handler binden
  ```

**FEHLER 5: Visuelle Darstellung unterbricht Funktionalität**
- **Problem**: Erinnerungen unterbrachen Aufgaben-Balken
- **Ursache**: Falsche Render-Reihenfolge (Erinnerungen vor Aufgaben)
- **Lösung**: Aufgaben zuerst, dann Erinnerungen
- **Lesson**: UI-Reihenfolge muss Funktionalität folgen, nicht umgekehrt

### 🔧 TROUBLESHOOTING-WORKFLOW

**Bei JavaScript-Fehlern:**
1. `docker logs taskmate --tail 50` prüfen
2. Browser-Console auf Syntax-Fehler prüfen
3. Node.js Syntax-Check: `node -c datei.js`

**Bei "verschwundenen" Daten:**
1. **NIEMALS** sofort Backup/Restore - erst debuggen!
2. API-Logs prüfen auf 401/403 Fehler
3. Auth-Status prüfen: `localStorage.getItem('token')`
4. Datenbank direkt prüfen: `sqlite3 data/taskmate.db "SELECT COUNT(*) FROM projects"`

**Bei CSS-Problemen:**
1. Simplest approach first - keine komplexen Selektoren
2. `!important` nur als letzter Ausweg
3. Browser-DevTools: Computed Styles prüfen
4. Cache leeren: `CACHE_VERSION++` in sw.js

**Bei neuen Modulen mit globaler Suche:**
1. Module in app.js setupSearch() registrieren:
   ```javascript
   } else if (currentView === 'mymodule') {
     import('./mymodule.js').then(module => {
       if (module.myManager) {
         module.myManager.searchQuery = value;
         module.myManager.filterData();
       }
     });
   ```
2. Manager-Instanz exportieren: `export { myManager }`
3. clearSearch() Funktion ebenfalls erweitern
4. Lokale Suchfelder entfernen - nur Header-Suche nutzen

## 🐛 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.