777 Zeilen
24 KiB
Markdown
777 Zeilen
24 KiB
Markdown
# 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>×</button>
|
|
</div>
|
|
<div class="modal-body"><!-- Content --></div>
|
|
<div class="modal-footer"><!-- Buttons --></div>
|
|
</div>
|
|
```
|
|
|
|
### ⚠️ SVG Icon-Rendering Probleme (07.01.2025)
|
|
|
|
**FEHLER: SVG Icons werden nicht angezeigt**
|
|
- **Problem**: SVG-Icons verschwinden oder zeigen nicht korrekt an
|
|
- **Ursache**: `createElement()` unterstützt kein SVG-Namespace
|
|
- **Lösung**: SVG mit `innerHTML` oder als String-Template einfügen
|
|
- **Pattern**:
|
|
```javascript
|
|
// FALSCH - SVG wird nicht gerendert
|
|
const icon = createElement('svg', { viewBox: '0 0 24 24' });
|
|
|
|
// RICHTIG - SVG als HTML-String
|
|
element.innerHTML = `<svg viewBox="0 0 24 24">...</svg>`;
|
|
```
|
|
- **Prävention**: Bei dynamischen SVGs immer innerHTML oder DOMParser nutzen
|
|
|
|
### ⚠️ API Field Name Mismatches (07.01.2025)
|
|
|
|
**FEHLER: Frontend/Backend Feldnamen-Diskrepanz**
|
|
- **Problem**: Daten werden mit 0 Bytes oder leer angezeigt
|
|
- **Ursache**: Backend sendet camelCase, Frontend erwartet snake_case
|
|
- **Beispiel**: `originalName` vs `original_name`, `sizeBytes` vs `size_bytes`
|
|
- **Lösung**: Fallback-Pattern für beide Schreibweisen
|
|
- **Pattern**:
|
|
```javascript
|
|
// Robuste Feldabfrage mit Fallback
|
|
const fileName = data.originalName || data.original_name || '';
|
|
const fileSize = data.sizeBytes || data.size_bytes || 0;
|
|
```
|
|
- **Prävention**: API-Dokumentation prüfen, einheitliche Naming-Convention
|
|
|
|
### ⚠️ File Upload Field Names (07.01.2025)
|
|
|
|
**FEHLER: Multer "Unexpected field" Error**
|
|
- **Problem**: 500 Error bei File-Upload
|
|
- **Ursache**: Frontend sendet 'files' (plural), Backend erwartet 'file' (singular)
|
|
- **Lösung**: Backend-Konsistenz herstellen
|
|
- **Pattern**:
|
|
```javascript
|
|
// Backend - Konsistent 'files' verwenden
|
|
upload.single('files') // NICHT 'file'
|
|
|
|
// Frontend - FormData immer mit 'files'
|
|
formData.append('files', file);
|
|
```
|
|
- **Prävention**: Einheitliche Field-Names über alle Upload-Endpoints
|
|
|
|
### ⚠️ 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
|
|
|
|
### ⚠️ Dropdown-Transparenz-Probleme (09.01.2026)
|
|
|
|
**FEHLER: Dropdown-Menüs haben unerwünschte Transparenz**
|
|
- **Problem**: Dropdown-Menüs zeigen durchscheinenden Hintergrund, besonders bei dunklen Themes
|
|
- **Symptome**:
|
|
- Text schwer lesbar durch transparenten Hintergrund
|
|
- Inhalte dahinter scheinen durch
|
|
- Besonders auffällig bei Kontakte-Modul und anderen Dropdown-Menüs
|
|
- **Ursache**: CSS-Variablen für Hintergründe verwenden `rgba()` mit Transparenz
|
|
- **Lösung**: Explizite, nicht-transparente Hintergrundfarben für Dropdowns setzen
|
|
- **Pattern**:
|
|
```css
|
|
/* FALSCH - Transparente Hintergründe */
|
|
.dropdown {
|
|
background: var(--bg-secondary); /* rgba mit 0.95 opacity */
|
|
}
|
|
|
|
/* RICHTIG - Solide Hintergründe für Dropdowns */
|
|
.dropdown {
|
|
background: #ffffff; /* Hell-Theme */
|
|
background: #1a1a1a; /* Dunkel-Theme */
|
|
}
|
|
```
|
|
- **Prävention**:
|
|
- Dropdown-Komponenten immer mit soliden Hintergründen
|
|
- Keine CSS-Variablen mit Transparenz für interaktive Elemente
|
|
- Bei Theme-Support: Explizite Farben ohne Alpha-Kanal
|
|
|
|
### 🔧 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
|
|
|
|
**Bei File-Upload Problemen:**
|
|
1. Prüfe ob Entry/Task bereits gespeichert ist (ID vorhanden)
|
|
2. Bei neuen Einträgen: Erst speichern, dann Upload
|
|
3. Field-Name Konsistenz prüfen: 'files' (plural) überall
|
|
4. `docker logs taskmate` für Multer-Errors checken
|
|
|
|
## 🐛 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. |