141 Zeilen
4.0 KiB
Markdown
141 Zeilen
4.0 KiB
Markdown
# 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 |