CLAUDE.md als Richtlinie

v2_adminpanel/CLAUDE.md

@@ -0,0 +1,141 @@
+# CLAUDE.md - AI Coding Assistant Guidelines
+
+## Core Principles
+- **Structured Code First**: Write code that is well-organized from the start to avoid future refactoring
+- **YAGNI (You Aren't Gonna Need It)**: Only implement what is currently needed, not what might be needed
+
+## Project Structure
+```
+v2_adminpanel/
+├── routes/          # Blueprint-based route handlers
+├── templates/       # Jinja2 templates
+├── utils/          # Utility modules
+├── leads/          # Leads module with own templates/routes
+└── core/           # Core functionality (error handlers, logging, monitoring)
+```
+
+## Database Schema Reference
+
+### license_heartbeats
+```sql
+- id BIGSERIAL
+- license_id INTEGER
+- hardware_id VARCHAR(255)
+- ip_address INET
+- user_agent VARCHAR(500)
+- app_version VARCHAR(50)
+- timestamp TIMESTAMP
+- session_data JSONB
+(NO response_time column!)
+```
+
+### Common Tables
+- `customers` - Customer records
+- `licenses` - License keys and configuration
+- `users` - Admin panel users
+- `anomaly_detections` - Security anomaly tracking
+- `audit_log` - System audit trail
+
+## Template Parameter Contracts
+
+### error.html
+```python
+render_template('error.html',
+    error='Error message',        # NOT error_message!
+    details='Optional details',   # Optional
+    error_code=404,              # Optional
+    request_id='uuid'            # Optional
+)
+```
+
+### Common Template Parameters
+- All templates expect `current_user` in session context
+- Use `error` not `error_message` for error displays
+- Flash messages use categories: 'success', 'error', 'warning', 'info'
+
+## Pre-Implementation Checklist
+
+### Before Writing Routes
+- [ ] Check if similar route exists with `grep -r "route_name" .`
+- [ ] Verify template exists and check expected parameters
+- [ ] Confirm all imported modules exist
+- [ ] Check if login_required decorator is needed
+
+### Before Database Queries
+- [ ] Verify table exists in init.sql
+- [ ] Confirm all column names with `grep "CREATE TABLE table_name" -A 20`
+- [ ] Check for required indexes
+- [ ] Consider partition requirements for time-series data
+
+### Before Modifying Templates
+- [ ] Check which routes use this template
+- [ ] Verify all passed parameters are used
+- [ ] Maintain consistent styling with existing templates
+
+## Common Patterns
+
+### Error Handling
+```python
+try:
+    # operation
+except Exception as e:
+    logger.error(f"Error in operation: {str(e)}")
+    return render_template('error.html', 
+                         error='Specific error message',
+                         details=str(e))
+```
+
+### Database Connections
+```python
+conn = get_db_connection()
+cur = conn.cursor(cursor_factory=RealDictCursor)
+try:
+    # queries
+    conn.commit()
+finally:
+    cur.close()
+    conn.close()
+```
+
+## Testing & Verification
+
+### Check Logs
+```bash
+docker-compose logs admin-panel | tail -50
+```
+
+### Verify Container Status
+```bash
+docker-compose ps
+```
+
+### Common Issues to Avoid
+1. **Parameter Mismatches**: Always verify template expectations
+2. **Missing Columns**: Check schema before writing queries
+3. **Import Errors**: Ensure utils/__init__.py exists
+4. **Transaction Errors**: Properly handle PostgreSQL transactions
+5. **Creating Unnecessary Files**: Check if functionality exists before creating new files
+
+## Docker Environment
+- Service name: `admin-panel` (not `adminpanel`)
+- Database host: `postgres`
+- Default port: 5000
+- Behind nginx proxy
+
+## Code Style Rules
+- NO comments unless explicitly requested
+- Follow existing patterns in the codebase
+- Use existing utilities before creating new ones
+- Maintain consistent error handling
+- Always use absolute paths for file operations
+
+## YAGNI Reminders
+- Don't add features "for the future"
+- Don't create generic solutions for single use cases
+- Don't add configuration options that aren't needed now
+- Don't abstract code that's only used once
+- Implement exactly what's requested, nothing more
+
+## Update Log
+- 2025-06-21: Created initial version after fixing monitoring parameter mismatch
+- 2025-06-21: Added response_time column issue to known problems