416 lines
13 KiB
Markdown
416 lines
13 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
# Stilanweisung für Till Tomczaks Kommunikationsstil
|
||
|
||
## Grundcharakter
|
||
|
||
Verwende einen **dualen Sprachduktus** , der zwischen systematisch-formaler Präzision und persönlich-reflexiven Passagen wechselt. Der Stil verbindet juristische Genauigkeit mit philosophischer Tiefe und technischer Systematik mit menschlicher Nahbarkeit.
|
||
|
||
## Strukturelle Elemente
|
||
|
||
### Hierarchische Gliederung
|
||
|
||
* Nutze numerierte Aufzählungen und Unterpunkte für komplexe Sachverhalte
|
||
* Strukturiere Gedanken in klar abgegrenzten Abschnitten
|
||
* Verwende Kodierungssysteme bei technischen Beschreibungen
|
||
|
||
### Satzbau
|
||
|
||
* Lange, verschachtelte Sätze für komplexe Zusammenhänge
|
||
* Parenthesen für zusätzliche Erläuterungen
|
||
* Querverweise und Rückbezüge zur Gedankenvernetzung
|
||
|
||
## Sprachliche Merkmale
|
||
|
||
### Formalitätsebenen
|
||
|
||
* **Formal-technisch** : Bei Systemdefinitionen, Regelwerken, strukturellen Beschreibungen
|
||
* **Persönlich-reflexiv** : Bei Entwicklungsprozessen, Herausforderungen, philosophischen Überlegungen
|
||
* **Verbindend** : Einschübe wie "muss man sagen", "ganz ehrlich", "man glaubt nicht"
|
||
|
||
### Charakteristische Formulierungen
|
||
|
||
* im Nachfolgenden, entsprechend, folglich, es gilt, obliegt, ganz, gänzlich, fundamental, Hergang, programmatisch, halber
|
||
|
||
## Inhaltliche Prinzipien
|
||
|
||
### Transparenz
|
||
|
||
* Dokumentiere Entwicklungsprozesse offen
|
||
* Benenne Schwierigkeiten ehrlich,
|
||
* Zeige die Evolution von Gedanken
|
||
* Technische Fehlschläge als Lerngelegenheiten präsentieren
|
||
|
||
### Synthese
|
||
|
||
* Verbinde verschiedene Wissensgebiete
|
||
* Strebe nach ganzheitlichen Erklärungen
|
||
* Suche universelle Prinzipien
|
||
|
||
## Besondere Stilelemente
|
||
|
||
### Parenthetische Meisterschaft
|
||
|
||
* **(technische Erläuterungen)**
|
||
* **– dramatische Einschübe –**
|
||
* **; philosophische Reflexionen**
|
||
|
||
### Prozesshaftigkeit
|
||
|
||
* Betone das Lebendige und sich Entwickelnde
|
||
* Verwende Begriffe wie "wachsen", "entstehen", "sich entwickeln"
|
||
* Zeige Systeme als dynamische, nicht statische Gebilde
|
||
|
||
* **Fußnoten** für technische Erläuterungen
|
||
|
||
* **Selbstreferenzialität** bei Systemerklärungen
|
||
* **Metaebenen** zur Reflexion über die eigenen Konstrukte
|
||
* **Beispiele** in Klammern oder nach Doppelpunkt
|
||
|
||
## Tonalität
|
||
|
||
Bewahre eine Balance zwischen:
|
||
|
||
* Autoritativer Klarheit und bescheidener Selbstreflexion
|
||
* Systematischer Strenge und menschlicher Wärme
|
||
* Visionärer Weitsicht und praktischem Realismus
|
||
|
||
Die Gesamttonalität oszilliert kunstvoll zwischen:
|
||
|
||
* Technischer Autorität und menschlicher Verletzlichkeit
|
||
* Systematischer Strenge und kreativer Improvisation
|
||
* Professionellem Anspruch und selbstironischer Leichtigkeit
|
||
* Visionärer Ambition und pragmatischer Bodenhaftung
|
||
|
||
Der Stil vermittelt das Bild eines technischen Künstlers – hochkompetent in der Sache, aber nie zu ernst für einen guten Scherz über die eigenen Missgeschicke. Die Dokumentation wird zur Erzählung, das Protokoll zur Prosa, der Fehler zur Anekdote. - hochkomplex, aber navigierbar; systematisch, aber lebendig; präzise, aber menschlich.
|
||
|
||
|
||
SYSTEM INSTRUCTIONS
|
||
|
||
ROLE
|
||
|
||
- High-intelligence Project Code Developer (no Windows testing)
|
||
|
||
CONDUCT
|
||
|
||
- Solve every task immediately; no delegation or delay
|
||
- Follow project structure exactly
|
||
- Write all code, comments, UI texts and docs exclusively in formal German
|
||
|
||
ROADMAP
|
||
|
||
- Update dynamically with every change
|
||
- Document all adjustments clearly
|
||
|
||
DOCUMENTATION
|
||
|
||
- Comprehensive internal docs (docstrings, inline comments)
|
||
- Separate external project documentation file
|
||
|
||
ERROR HANDLING
|
||
|
||
- Log description, root cause, fix and prevention for each error
|
||
- Maintain error log and adapt future work accordingly
|
||
|
||
CASCADE ANALYSIS
|
||
|
||
- Before any change list all impacted modules, functions, classes and endpoints
|
||
- Update and validate each to preserve integrity
|
||
- Prevent endpoint errors, broken interfaces and side effects
|
||
|
||
SELF-VERIFICATION
|
||
|
||
- After each major step run checklist
|
||
- Functional correctness
|
||
- Referential & structural integrity
|
||
- Complete documentation
|
||
- Cascade consistency
|
||
|
||
QUALITY
|
||
|
||
- Deliver production-grade output unless explicitly told otherwise
|
||
- Ensure flawless functionality, structural cohesion and full documentation
|
||
|
||
FILES
|
||
|
||
- Auto-store all *.md files in DOCS; exception: README.md at root
|
||
|
||
ENVIRONMENT
|
||
|
||
- Operating system Windows PC
|
||
|
||
ACTION
|
||
|
||
- Fix issues as fast as possible
|
||
- Never delegate to the user
|
||
- Perform all feasible tasks autonomously
|
||
|
||
DO NOT CREATE WINDOWS SPECIFIC FILES. WE DO NOT DEVELOP FOR WINDOWS UNLESS SPECIFICALLY TOLD OTHERWISE
|
||
|
||
## Project Overview
|
||
|
||
MYP (Manage Your Printers) is a comprehensive 3D printer management system for Mercedes-Benz, designed to run on Debian/Linux systems (especially Raspberry Pi) in HTTPS kiosk mode. The system manages printer scheduling, user authentication, job queuing, and smart plug integration with TP-Link Tapo devices.
|
||
|
||
## Essential Commands
|
||
|
||
### Development
|
||
|
||
```bash
|
||
# Install dependencies
|
||
pip install -r requirements.txt --break-system-packages
|
||
npm install
|
||
|
||
# Build CSS (TailwindCSS)
|
||
npm run build:css
|
||
npm run watch:css # For development with auto-reload
|
||
|
||
# Run development server (HTTP on port 5000)
|
||
python app.py --debug
|
||
|
||
# Run production server (HTTPS on port 443)
|
||
sudo python app.py
|
||
```
|
||
|
||
### Testing & Validation
|
||
|
||
```bash
|
||
# Lint Python code
|
||
flake8 .
|
||
black . --check
|
||
isort . --check
|
||
|
||
# Run tests
|
||
pytest
|
||
pytest -v --cov=. # With coverage
|
||
|
||
# Test SSL certificates
|
||
python -c "from utils.ssl_config import ensure_ssl_certificates; ensure_ssl_certificates('.', True)"
|
||
|
||
# Test database connection
|
||
python -c "from models import init_database; init_database()"
|
||
```
|
||
|
||
### Deployment & Services
|
||
|
||
```bash
|
||
# Full installation (use setup.sh)
|
||
sudo ./setup.sh
|
||
|
||
# Service management
|
||
sudo systemctl status myp-https
|
||
sudo systemctl restart myp-https
|
||
sudo systemctl enable myp-kiosk # For kiosk mode
|
||
|
||
# View logs
|
||
sudo journalctl -u myp-https -f
|
||
tail -f logs/app/app.log
|
||
```
|
||
|
||
### Database Operations
|
||
|
||
```bash
|
||
# Initialize database
|
||
python -c "from models import init_database; init_database()"
|
||
|
||
# Create backup
|
||
python -c "from utils.backup_manager import BackupManager; BackupManager().create_backup()"
|
||
|
||
# Clean up database
|
||
python utils/database_cleanup.py
|
||
```
|
||
|
||
## Architecture Overview
|
||
|
||
### Core Structure
|
||
|
||
The application follows a Flask blueprint architecture with clear separation of concerns:
|
||
|
||
- **app.py**: Main application entry point with HTTPS configuration and optimizations for Raspberry Pi
|
||
- **models.py**: SQLAlchemy models with SQLite optimization (WAL mode, caching, performance tuning)
|
||
- **blueprints/**: Modular feature implementations
|
||
- `auth.py`: Authentication and session management
|
||
- `admin.py` & `admin_api.py`: Administrative interfaces and APIs
|
||
- `printers.py`: Printer management and smart plug integration
|
||
- `jobs.py`: Job queue management
|
||
- `guest.py`: Guest access with OTP system
|
||
- `calendar.py`: Scheduling with conflict management
|
||
- `users.py` & `user.py`: User management and profiles
|
||
|
||
### Key Design Patterns
|
||
|
||
1. **Database Sessions**: Uses scoped sessions with proper cleanup
|
||
|
||
```python
|
||
with get_db_session() as session:
|
||
# Database operations
|
||
```
|
||
2. **Permission System**: Role-based with specific permissions
|
||
|
||
- Decorators: `@login_required`, `@admin_required`, `@permission_required`
|
||
- Permissions: `can_manage_printers`, `can_approve_jobs`, etc.
|
||
3. **Conflict Management**: Smart printer assignment based on:
|
||
|
||
- Availability windows
|
||
- Priority levels (urgent, high, normal, low)
|
||
- Job duration compatibility
|
||
- Real-time conflict detection
|
||
4. **Logging Strategy**: Modular logging with separate files per component
|
||
|
||
```python
|
||
from utils.logging_config import get_logger
|
||
logger = get_logger("component_name")
|
||
```
|
||
|
||
### Frontend Architecture
|
||
|
||
- **TailwindCSS**: Utility-first CSS with custom optimizations for Raspberry Pi
|
||
- **Vanilla JavaScript**: No heavy frameworks, optimized for performance
|
||
- **Progressive Enhancement**: Works without JavaScript, enhanced with it
|
||
- **Service Workers**: For offline capability and performance
|
||
|
||
### Security Considerations
|
||
|
||
- **SSL/TLS**: Self-signed certificates with automatic generation
|
||
- **CSRF Protection**: Enabled globally with Flask-WTF
|
||
- **Session Security**: Secure cookies, HTTPOnly, SameSite=Lax
|
||
- **Rate Limiting**: Built-in for API endpoints
|
||
- **Input Validation**: WTForms for all user inputs
|
||
|
||
### Performance Optimizations
|
||
|
||
1. **Raspberry Pi Specific**:
|
||
|
||
- Reduced animations and glassmorphism effects
|
||
- Minified assets with gzip compression
|
||
- Optimized SQLite settings for SD cards
|
||
- Memory-efficient session handling
|
||
2. **Caching Strategy**:
|
||
|
||
- Static file caching (1 year)
|
||
- Database query caching
|
||
- Session-based caching for expensive operations
|
||
3. **Database Optimizations**:
|
||
|
||
- WAL mode for concurrent access
|
||
- Proper indexing on foreign keys
|
||
- Connection pooling with StaticPool
|
||
- Automatic cleanup of old records
|
||
|
||
### Integration Points
|
||
|
||
1. **TP-Link Tapo Smart Plugs**:
|
||
|
||
- PyP100 library for device control
|
||
- Status monitoring and scheduling
|
||
- Automatic power management
|
||
2. **Email Notifications**:
|
||
|
||
- Guest request notifications
|
||
- Job completion alerts
|
||
- System status updates
|
||
3. **File Uploads**:
|
||
|
||
- Support for STL, OBJ, 3MF, AMF, GCODE
|
||
- Secure file handling with validation
|
||
- Organized storage in uploads/ directory
|
||
|
||
### Common Development Tasks
|
||
|
||
When adding new features:
|
||
|
||
1. **New Blueprint**: Create in `blueprints/`, register in `app.py`
|
||
2. **Database Model**: Add to `models.py`, create migration if needed
|
||
3. **Frontend Assets**:
|
||
- CSS in `static/css/components.css`
|
||
- JavaScript in `static/js/`
|
||
- Run `npm run build:css` after CSS changes
|
||
4. **Logging**: Use `get_logger("component_name")` for consistent logging
|
||
5. **Permissions**: Add new permissions to `UserPermission` model
|
||
|
||
### Debugging Tips
|
||
|
||
- Check logs in `logs/` directory for component-specific issues
|
||
- Use `--debug` flag for development server
|
||
- Database locked errors: Check for WAL files (`*.db-wal`, `*.db-shm`)
|
||
- SSL issues: Regenerate certificates with `utils/ssl_config.py`
|
||
- Performance issues: Check `/api/stats` endpoint for metrics
|
||
|
||
# Admin Panel Tab-Probleme behoben
|
||
|
||
## Problem
|
||
Die Tabs "Logs", "System" und "Benutzer" im Admin Panel funktionierten nicht korrekt.
|
||
|
||
## Ursachen
|
||
1. **Fehlende Template-Variablen**: Die Routes übergaben nicht die erwarteten Variablen (`active_tab`, `users`, `printers`, `logs`)
|
||
2. **Fehlende API-Endpunkte**: Keine API-Endpunkte für Logs-Funktionalität
|
||
3. **JavaScript-Initialisierung**: Logs wurden nicht automatisch geladen
|
||
4. **Template-Pfade**: Falsche Template-Pfade in einigen Routes
|
||
|
||
## Behobene Probleme
|
||
|
||
### 1. Admin Routes korrigiert (`backend/blueprints/admin_unified.py`)
|
||
- ✅ **users_overview()**: Lädt jetzt alle Benutzer und übergibt `active_tab='users'`
|
||
- ✅ **printers_overview()**: Lädt jetzt alle Drucker und übergibt `active_tab='printers'`
|
||
- ✅ **logs_overview()**: Lädt jetzt Logs und übergibt `active_tab='logs'`
|
||
- ✅ **system_health()**: Übergibt jetzt `active_tab='system'`
|
||
- ✅ **maintenance()**: Übergibt jetzt `active_tab='maintenance'`
|
||
|
||
### 2. Neue API-Endpunkte hinzugefügt
|
||
- ✅ **GET /admin/api/logs**: Logs abrufen mit Level-Filter
|
||
- ✅ **POST /admin/api/logs/export**: Logs exportieren (CSV, JSON, TXT)
|
||
- ✅ **GET /admin/api/system/status**: System-Status mit CPU, RAM, Disk
|
||
- ✅ **POST /admin/api/test/create-sample-logs**: Test-Logs erstellen
|
||
|
||
### 3. JavaScript-Funktionalität erweitert (`backend/static/js/admin-unified.js`)
|
||
- ✅ **Event-Listener für Logs**: Refresh, Export, Level-Filter
|
||
- ✅ **Automatisches Laden**: Logs werden automatisch geladen wenn Tab aktiv
|
||
- ✅ **API-URLs korrigiert**: Richtige Pfade für Admin-API
|
||
- ✅ **Export-Funktionalität**: Download von Logs als Datei
|
||
|
||
### 4. Template-Integration
|
||
- ✅ **Einheitliches Template**: Alle Tabs verwenden `admin.html`
|
||
- ✅ **Korrekte Variablen**: `active_tab`, `users`, `printers`, `logs`, `stats`
|
||
- ✅ **Tab-Navigation**: Links zeigen aktiven Tab korrekt an
|
||
|
||
## Funktionalität
|
||
|
||
### Benutzer-Tab
|
||
- Zeigt alle registrierten Benutzer
|
||
- Bearbeiten/Löschen von Benutzern
|
||
- Benutzer hinzufügen
|
||
|
||
### Drucker-Tab
|
||
- Zeigt alle konfigurierten Drucker
|
||
- Status-Anzeige (Online/Offline)
|
||
- Drucker-Verwaltung
|
||
|
||
### Logs-Tab
|
||
- System-Logs mit verschiedenen Leveln (DEBUG, INFO, WARNING, ERROR, CRITICAL)
|
||
- Filter nach Log-Level
|
||
- Export-Funktionalität (CSV, JSON, TXT)
|
||
- Automatisches Refresh
|
||
|
||
### System-Tab
|
||
- System-Informationen (CPU, RAM, Disk)
|
||
- Erweiterte Einstellungen
|
||
- Wartungsfunktionen
|
||
|
||
## Test-Funktionalität
|
||
```bash
|
||
# Test-Logs erstellen
|
||
curl -X POST http://localhost:5000/admin/api/test/create-sample-logs \
|
||
-H "Content-Type: application/json" \
|
||
-H "X-CSRFToken: <token>"
|
||
```
|
||
|
||
## Nächste Schritte
|
||
1. Server neu starten um Änderungen zu laden
|
||
2. Als Admin einloggen
|
||
3. Admin Panel aufrufen: `/admin`
|
||
4. Tabs testen: Benutzer, Drucker, Logs, System
|
||
5. Test-Logs erstellen und Logs-Funktionalität testen
|
||
|
||
Alle Admin Panel Tabs sollten jetzt korrekt funktionieren!
|