TaskMate/CLAUDE.md

# TaskMate - Projekt-Konfiguration
# YAML-Format fuer KI-Assistenten

PROJECT:
  name: TaskMate
  type: PRODUCTION
  url: https://taskmate.aegis-sight.de
  container: taskmate
  port_external: 3001
  port_internal: 3000
  gitea: https://gitea-undso.aegis-sight.de/AegisSight/TaskMate

USER_PROFILE:
  programming_skills: NONE
  support_level: FULL_SERVICE
  communication: SIMPLE_LANGUAGE

COMMUNICATION_RULES:
  do:
    - "Alle technischen Aufgaben vollstaendig uebernehmen"
    - "In einfachen Worten erklaeren was passiert"
    - "Alle Schritte selbststaendig ausfuehren"
    - "Status-Updates geben: Aenderung abgeschlossen, teste jetzt..."
  dont:
    - "NIEMALS nach technischen Details fragen"
    - "NIEMALS nach Code-Schnipseln fragen"
    - "NIEMALS Befehle zum Ausfuehren geben"
    - "NIEMALS nach Logs oder Console fragen"

CRITICAL_RULES:
  1_cache_version: "Nach Frontend-Aenderungen: frontend/sw.js CACHE_VERSION erhoehen"
  2_changelog_file: "Bei JEDER Aenderung: CHANGELOG.txt aktualisieren"
  3_changelog_db: "Bei JEDER Aenderung: Wissensdatenbank Changelog aktualisieren (siehe WORKFLOWS)"
  4_no_toISOString: "NIEMALS toISOString() fuer Datums-Operationen (UTC-Problem!)"
  5_realtime_updates: "User darf NIE F5 druecken muessen"
  6_docker_restart: "Nach Backend-Aenderungen: docker compose up -d --build (NICHT docker restart - das nutzt das alte Image!)"
  7_no_css_tricks: "Layout-Aenderungen immer ueber HTML-Struktur loesen, NIEMALS mit CSS-Tricks wie flex-wrap+order, negative margins oder aehnlichem. Wenn ein Element in eine eigene Zeile soll, muss es ein eigenes HTML-Element sein."

PROTECTED_DATA:
  project: "AegisSight"
  description: "Produktiv im Einsatz - NIEMALS loeschen oder aendern"
  protected_users:
    - admin
    - "Hendrik (hendrik_gebhardt@gmx.de)"
    - "Monami (momohomma@googlemail.com)"
  forbidden_actions:
    - "Nutzerdaten aendern"
    - "Passwoerter aendern"
    - "Datenbank-Resets ohne Anweisung"
    - "Testdaten in Produktivdaten"

COMMANDS:
  restart: "docker restart taskmate"
  rebuild: "cd /home/claude-dev/TaskMate && docker compose build --no-cache && docker compose up -d"
  logs: "docker logs taskmate -f --tail 100"
  health: "curl http://localhost:3000/api/health"
  copy_frontend: "docker cp frontend/js/ taskmate:/app/public/js/"
  copy_backend: "docker cp backend/routes/ taskmate:/app/routes/"

FILE_STRUCTURE:
  frontend:
    core:
      - "frontend/js/app.js - Hauptanwendung & View-Controller"
      - "frontend/js/store.js - State Management (Pub-Sub)"
      - "frontend/js/api.js - API Client mit Auth/CSRF"
      - "frontend/js/auth.js - Login/Token-Verwaltung"
      - "frontend/js/sync.js - Socket.io Echtzeit"
    views:
      - "frontend/js/board.js - Kanban-Board mit Drag&Drop"
      - "frontend/js/calendar.js - Kalender (Monat/Woche)"
      - "frontend/js/list.js - Listenansicht"
      - "frontend/js/dashboard.js - Statistik-Dashboard"
      - "frontend/js/proposals.js - Vorschlagssystem"
      - "frontend/js/knowledge.js - Wissensdatenbank"
      - "frontend/js/admin.js - Benutzerverwaltung"
    important:
      - "frontend/sw.js - Service Worker mit CACHE_VERSION"
      - "frontend/index.html - Haupt-HTML"
  backend:
    core:
      - "backend/server.js - Express Server mit Socket.io"
      - "backend/database.js - Datenbankschema (20+ Tabellen)"
    routes:
      - "/api/auth - Login/Logout"
      - "/api/tasks - Aufgaben CRUD"
      - "/api/projects - Projekte"
      - "/api/columns - Kanban-Spalten"
      - "/api/comments - Kommentare"
      - "/api/files - Datei-Upload"
      - "/api/proposals - Vorschlaege"
      - "/api/knowledge - Wissensdatenbank"
  other:
    - "CHANGELOG.txt - Aenderungsprotokoll"

DATABASE:
  type: SQLite
  path: "data/taskmate.db"
  tables:
    - users
    - projects
    - columns
    - tasks
    - task_labels
    - task_assignees
    - comments
    - attachments
    - proposals
    - notifications
    - knowledge_categories
    - knowledge_entries

CODE_PATTERNS:
  date_formatting:
    correct: |
      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}`;
    wrong: "date.toISOString().split('T')[0] // NIEMALS - UTC Problem!"

  toast_messages:
    correct: |
      window.dispatchEvent(new CustomEvent('toast:show', {
        detail: { message: 'Text', type: 'success' }
      }));
    wrong: "store.showMessage('Text', 'success') // existiert nicht"

  realtime_updates:
    required: |
      store.subscribe('tasks', () => renderTasks());
      window.addEventListener('app:refresh', () => updateView());

TROUBLESHOOTING:
  frontend_changes_not_visible:
    problem: "Frontend-Dateien werden beim Build kopiert, nicht live gemountet"
    solution_dev: "docker cp frontend/js/ taskmate:/app/public/js/"
    solution_prod: "cd /home/claude-dev/TaskMate && docker compose build --no-cache && docker compose up -d"

  401_unauthorized:
    problem: "Token abgelaufen"
    solution: "Neu einloggen"

  csrf_error:
    problem: "CSRF Token ungueltig"
    solution: "Browser-Cache/Cookies loeschen, neu einloggen"

  missing_data:
    problem: "Daten scheinen verschwunden"
    first_check: "docker logs taskmate - auf 401/403 Fehler pruefen"
    note: "NIEMALS sofort Backup/Restore - erst Auth pruefen"

WORKFLOWS:
  changelog_entry:
    description: "PFLICHT bei jeder Code-Aenderung"
    step_1:
      name: "CHANGELOG.txt aktualisieren"
      file: "/home/claude-dev/TaskMate/CHANGELOG.txt"
      format: "DD.MM.YYYY - vXXX - Kurzbeschreibung"
    step_2:
      name: "Wissensdatenbank Changelog aktualisieren"
      command: |
        docker exec taskmate node -e "
        const Database = require('better-sqlite3');
        const db = new Database('/app/data/taskmate.db');
        db.prepare(\`
          INSERT INTO knowledge_entries (category_id, title, notes, position, created_by)
          VALUES (15, 'DD.MM.YYYY - Beschreibung', 'Markdown-Inhalt', 0, 1)
        \`).run();
        console.log('Changelog erstellt');
        "
      category_id: 15
      title_format: "DD.MM.YYYY - Kurze Beschreibung"
      notes_format: "Markdown mit Details (Problem, Loesung, geaenderte Dateien)"

  deployment:
    steps:
      - "Cache-Version erhoehen: frontend/sw.js"
      - "CHANGELOG.txt aktualisieren"
      - "Wissensdatenbank Changelog aktualisieren"
      - "docker cp oder docker build"
      - "docker compose up -d (Container mit neuem Image starten)"
      - "Testen: https://taskmate.aegis-sight.de"
      - "Browser-Cache leeren (Strg+F5)"

CONVENTIONS:
  language_ui: Deutsch
  language_code: Englisch
  umlauts: "ae oe ue verwenden (ä ö ü)"
  emojis: "Nur in Dokumentation, nicht in Code/UI"
  auto_save: true

SECURITY:
  auth:
    type: JWT
    validity: 24h
    storage: localStorage
  csrf:
    header: "X-CSRF-Token"
    generated_at: login
  roles:
    admin: "Nur Benutzerverwaltung"
    user: "Alles ausser Admin-Bereich"

KNOWN_ISSUES:
  docker_rebuild:
    problem: "docker restart nutzt das ALTE Image - Code-Aenderungen werden NICHT uebernommen"
    wichtig: "docker build allein reicht auch nicht, da docker-compose den alten Container weiter nutzt"
    solution: "cd /home/claude-dev/TaskMate && docker compose build --no-cache && docker compose up -d"
    hinweis: "Immer mit --no-cache bauen, da Docker COPY-Layer cached auch wenn Dateien sich geaendert haben"
  svg_rendering:
    problem: "createElement() unterstuetzt kein SVG-Namespace"
    solution: "SVG mit innerHTML oder String-Template einfuegen"

  field_name_mismatch:
    problem: "Backend camelCase vs Frontend snake_case"
    solution: "Fallback-Pattern: data.originalName || data.original_name"

  file_upload:
    problem: "Multer Unexpected field Error"
    solution: "Konsistent 'files' (plural) verwenden"

ROLLBACK:
  backup_db: "cp data/taskmate.db data/taskmate.db.backup-$(date +%Y%m%d-%H%M%S)"
  backup_docker: "docker commit taskmate taskmate-backup-$(date +%Y%m%d-%H%M%S)"
  restore_code: "git stash && git checkout HEAD~1"

Last-Updated: 2026-03-19