AegisSight/TaskMate

Fork 0

Files

hendrik_gebhardt@gmx.de 7d67557be4 Kontakt-Modul

2026-01-06 21:49:26 +00:00

21 KiB

Originalformat Blame Verlauf

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! ⚠️

Cache-Version erhöhen nach Frontend-Änderungen: frontend/sw.js → CACHE_VERSION
CHANGELOG.txt bei JEDER Änderung aktualisieren
Keine toISOString() für Datums-Operationen (UTC-Problem!)
Echtzeit-Updates - User darf NIE F5 drücken müssen
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:

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

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

Arbeitsweise mit nicht-technischem Anwender

Der Anwender versteht KEIN Coding! Daher:

Vollständige Übernahme: Du führst ALLE technischen Schritte durch
Einfache Erklärungen: "Ich passe jetzt X an, damit Y funktioniert"
Status-Updates: "Änderung abgeschlossen, teste jetzt..."
Keine technischen Fragen: Niemals nach Code, Logs oder Befehlen fragen
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

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:

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

LÖSUNG A - Sofortige Änderungen (Development):

# 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):

# Docker Image neu bauen und Container ersetzen
docker build -t taskmate . && docker restart taskmate

Express.js Caching deaktiviert:

// 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:

Prüfe Datei-Timestamps im Container: docker exec taskmate ls -la /app/public/css/
Vergleiche mit lokalen Dateien: ls -la frontend/css/
Bei Diskrepanz: Files mit docker cp aktualisieren
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:

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

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:

// 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:

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:

<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:

# 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

/* 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:

// 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:

docker logs taskmate --tail 50 prüfen
Browser-Console auf Syntax-Fehler prüfen
Node.js Syntax-Check: node -c datei.js

Bei "verschwundenen" Daten:

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

Bei CSS-Problemen:

Simplest approach first - keine komplexen Selektoren
!important nur als letzter Ausweg
Browser-DevTools: Computed Styles prüfen
Cache leeren: CACHE_VERSION++ in sw.js

Bei neuen Modulen mit globaler Suche:

Module in app.js setupSearch() registrieren:

} else if (currentView === 'mymodule') {
  import('./mymodule.js').then(module => {
    if (module.myManager) {
      module.myManager.searchQuery = value;
      module.myManager.filterData();
    }
  });

Manager-Instanz exportieren: export { myManager }
clearSearch() Funktion ebenfalls erweitern
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

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 ö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.

21 KiB Originalformat Blame Verlauf