464 Zeilen
12 KiB
Markdown
464 Zeilen
12 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
|
|
|
|
### 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. |