Refactor code structure for improved readability and maintainability

2026-03-09 23:07:05 +01:00
parent 3361cffb14
commit 2e9db78c6e
18 changed files with 2855 additions and 69 deletions
--- a/custom/docs/README.md
+++ b/custom/docs/README.md
@@ -0,0 +1,319 @@
+# EspoCRM Custom Development - Dokumentation
+
+**Zentrale Dokumentation für EspoCRM-Entwicklung mit KI-Support**
+
+---
+
+## 📂 Struktur
+
+```
+custom/docs/
+├── README.md                           # Diese Datei
+├── ESPOCRM_BEST_PRACTICES.md          # ⭐ HAUPTDOKUMENTATION
+├── TESTERGEBNISSE_JUNCTION_TABLE.md   # Junction Table Implementation
+├── ENTWICKLUNGSPLAN_ENTWICKLUNGEN.md  # Puls-System Spezifikation
+├── tools/                             # Tool-Dokumentation
+│   ├── QUICKSTART.md                  # Quick Start Guide
+│   ├── VALIDATION_TOOLS.md            # Validierungs-Tools
+│   ├── E2E_TESTS_README.md            # End-to-End Tests
+│   ├── KI_OVERVIEW_README.md          # KI-Projekt-Übersicht
+│   └── VALIDATOR_README.md            # Validator Details
+└── workflows/                         # Workflow-Dokumentation
+    └── README.md                      # Workflow-Format & Import/Export
+```
+
+---
+
+## 🚀 Für AI Code Agents - HIER STARTEN!
+
+### 1. Lies zuerst: ESPOCRM_BEST_PRACTICES.md
+
+**Das Hauptdokument enthält:**
+- ✅ Projekt-Übersicht & Architektur
+- ✅ Entity-Entwicklung (Naming, Templates, i18n)
+- ✅ Relationship-Patterns (One-to-Many, Many-to-Many, Junction Tables)
+- ✅ API-Entwicklung (REST Endpoints, Custom Actions)
+- ✅ Workflow-Management
+- ✅ Testing & Validierung
+- ✅ Fehlerbehandlung & Troubleshooting
+- ✅ Deployment-Prozess
+- ✅ Projekt-spezifische Entities
+
+**Befehl:**
+```bash
+cat custom/docs/ESPOCRM_BEST_PRACTICES.md
+```
+
+### 2. Projekt-Analyse abrufen
+
+**Für umfassenden aktuellen Projekt-Status:**
+```bash
+python3 custom/scripts/ki_project_overview.py > /tmp/project-overview.txt
+cat /tmp/project-overview.txt
+```
+
+**Output:** Alle Entities, Relationships, Custom Code, Workflows
+
+### 3. Validierung & Rebuild ausführen
+
+**Vor jeder Entwicklung:**
+```bash
+python3 custom/scripts/validate_and_rebuild.py
+```
+
+**Das Tool führt automatisch durch:**
+1. JSON-Syntax Check
+2. Relationship-Validierung
+3. i18n-Vollständigkeit
+4. Layout-Struktur
+5. Dateirechte
+6. CSS/JS/PHP Validierung
+7. EspoCRM Rebuild
+8. E2E-Tests
+9. **NEU:** Automatische Fehlerlog-Analyse bei Rebuild-Fehlern!
+
+---
+
+## 📖 Dokumentations-Guide
+
+### Hauptdokumentation
+
+#### ESPOCRM_BEST_PRACTICES.md
+**Vollständiges Entwickler-Handbuch**
+- Architektur-Prinzipien
+- Entity-Development mit Templates
+- Relationship-Patterns inkl. Junction Tables
+- API-Entwicklung (Controller, Service, REST)
+- Workflow-Management
+- Testing (Validierung, E2E)
+- Troubleshooting & Fehlerbehandlung
+
+**Verwende diese Datei für:**
+- Neuen Code-Agent briefen
+- Entwicklungsstandards nachschlagen
+- Entity-Templates kopieren
+- Fehler debuggen
+
+#### TESTERGEBNISSE_JUNCTION_TABLE.md
+**Junction Table Implementation Guide**
+- Many-to-Many mit additionalColumns
+- Junction Entity als API-Endpoint
+- Vollständige Code-Beispiele
+- API-Nutzung (CRUD, Filter, Sort)
+
+**Verwende diese Datei für:**
+- Many-to-Many Beziehungen mit Zusatzfeldern
+- API-only Access Pattern
+- Junction Entity Implementation
+
+#### ENTWICKLUNGSPLAN_ENTWICKLUNGEN.md
+**Puls-System (CPuls) Spezifikation**
+- Posteingangs-System mit KI-Analyse
+- Team-basierte Dokumenten-Workflows
+- First-Read-Closes Prinzip
+- Entity-Definitionen und Beziehungen
+
+**Verwende diese Datei für:**
+- CPuls-Entity Weiterentwicklung
+- Dokumenten-Workflow-Logik
+- KI-Integration-Patterns
+
+---
+
+## 🛠️ Tool-Dokumentation
+
+### tools/QUICKSTART.md
+**5-Minuten Quick Start für Validator**
+- Installation bereits fertig
+- Verwendung: `python3 custom/scripts/validate_and_rebuild.py`
+- Output-Interpretation
+
+### tools/VALIDATION_TOOLS.md
+**Technische Details zu Validierungs-Tools**
+- PHP-CLI (php -l)
+- CSSLint (csslint)
+- JSHint (jshint)
+- Integration im Validator
+
+### tools/E2E_TESTS_README.md
+**End-to-End Test Framework**
+- CRUD-Tests für Custom Entities
+- Relationship-Tests
+- Konfiguration & Ausführung
+
+### tools/KI_OVERVIEW_README.md
+**KI-Projekt-Übersicht Tool**
+- Automatische Projekt-Analyse
+- Output-Format für AI Agents
+- Verwendung: `python3 custom/scripts/ki_project_overview.py`
+
+### tools/VALIDATOR_README.md
+**Validator Details**
+- Alternative zu VALIDATION_TOOLS.md
+- Erweiterte Validator-Funktionalität
+
+---
+
+## 📋 Workflow-Dokumentation
+
+### workflows/README.md
+**Workflow-Format & Management**
+- Simple Workflow JSON-Format
+- BPM Flowchart Format
+- Import/Export mit `workflow_manager.php`
+- Trigger Types, Actions, Conditions
+
+**Befehle:**
+```bash
+# Workflows auflisten
+php custom/scripts/workflow_manager.php list
+
+# Workflow importieren
+php custom/scripts/workflow_manager.php import custom/workflows/my-workflow.json
+
+# Alle Workflows exportieren
+php custom/scripts/workflow_manager.php export
+```
+
+---
+
+## 🎯 Typische Workflows
+
+### Neue Entity entwickeln
+
+```bash
+# 1. Best Practices lesen
+cat custom/docs/ESPOCRM_BEST_PRACTICES.md | grep -A 50 "Entity Definition Template"
+
+# 2. Entity-Dateien erstellen (entityDefs, scopes, i18n de_DE + en_US)
+
+# 3. Validierung + Rebuild
+python3 custom/scripts/validate_and_rebuild.py
+```
+
+### Relationship implementieren
+
+```bash
+# 1. Relationship-Pattern nachschlagen
+cat custom/docs/ESPOCRM_BEST_PRACTICES.md | grep -A 100 "Relationship-Patterns"
+
+# 2. Links in beiden Entities konfigurieren
+
+# 3. Validierung (prüft bidirektionale Konsistenz)
+python3 custom/scripts/validate_and_rebuild.py
+```
+
+### Junction Table mit additionalColumns
+
+```bash
+# 1. Vollständige Anleitung lesen
+cat custom/docs/TESTERGEBNISSE_JUNCTION_TABLE.md
+
+# 2. Entity-Definitionen + Junction Entity erstellen
+
+# 3. Controller & Service für Junction Entity
+
+# 4. Validierung + Test
+python3 custom/scripts/validate_and_rebuild.py
+```
+
+### Fehler debuggen
+
+```bash
+# 1. Validierung ausführen (zeigt automatisch Fehlerlog bei Rebuild-Fehler)
+python3 custom/scripts/validate_and_rebuild.py
+
+# 2. Manuell Logs prüfen (falls nötig)
+tail -100 data/logs/espo-$(date +%Y-%m-%d).log | grep -i error
+
+# 3. Troubleshooting Guide
+cat custom/docs/ESPOCRM_BEST_PRACTICES.md | grep -A 200 "Troubleshooting"
+```
+
+---
+
+## 🔧 Entwicklungs-Tools Übersicht
+
+| Tool | Zweck | Befehl |
+|------|-------|--------|
+| **validate_and_rebuild.py** | Haupttool: Validierung + Rebuild + E2E | `python3 custom/scripts/validate_and_rebuild.py` |
+| **ki_project_overview.py** | Projekt-Analyse für AI | `python3 custom/scripts/ki_project_overview.py` |
+| **e2e_tests.py** | End-to-End CRUD Tests | `python3 custom/scripts/e2e_tests.py` |
+| **workflow_manager.php** | Workflow Import/Export | `php custom/scripts/workflow_manager.php list` |
+
+**Alle Tools dokumentiert in:** `custom/docs/tools/`
+
+---
+
+## 📚 Weitere Ressourcen
+
+### Projekt-spezifische Dokumente
+
+- `../README.md` - Custom Actions Blueprint
+- `../CUSTOM_DIRECTORY.md` - Verzeichnisstruktur-Übersicht
+
+### EspoCRM Offizielle Docs
+
+- **Main Docs:** https://docs.espocrm.com/
+- **API Reference:** https://docs.espocrm.com/development/api/
+- **Formula Functions:** https://docs.espocrm.com/administration/formula/
+
+---
+
+## 🎓 Best Practices Zusammenfassung
+
+### DO ✅
+
+- **IMMER beide Sprachen:** de_DE + en_US (en_US ist Fallback!)
+- **Bidirektionale Relationships:** `foreign` muss zurück zeigen
+- **Validierung vor Rebuild:** Nutze `validate_and_rebuild.py`
+- **Sprechende Namen:** `C{EntityName}` für Custom Entities
+- **Clean Code:** Kleine Funktionen, Type Hints, Kommentare
+- **Layouts mit {}:** EspoCRM 7.x+ erfordert `{}` statt `false`
+
+### DON'T ❌
+
+- **Keine fehlende i18n:** immer de_DE UND en_US
+- **Keine unidirektionalen Links:** immer foreign konfigurieren
+- **Keine komplexe Logik in Hooks:** nutze Services
+- **Keine direkten SQL-Queries:** nutze EntityManager
+- **Keine hard-coded Werte:** nutze Config
+
+---
+
+## 🆘 Support & Troubleshooting
+
+### Bei Problemen:
+
+1. **Fehlerlog-Analyse:**
+   ```bash
+   python3 custom/scripts/validate_and_rebuild.py
+   # → Zeigt automatisch Fehler bei Rebuild-Fehlern
+   ```
+
+2. **Troubleshooting Guide:**
+   ```bash
+   cat custom/docs/ESPOCRM_BEST_PRACTICES.md | grep -A 300 "Troubleshooting"
+   ```
+
+3. **Häufige Fehler:**
+   - Layout `false` → `{}` ändern
+   - i18n fehlt → beide Sprachen anlegen
+   - Relationship kaputt → bidirektional prüfen
+   - ACL 403 → Rechte in Admin UI
+
+---
+
+## 📊 System-Info
+
+- **EspoCRM Version:** 9.3.2
+- **PHP Version:** 8.2.30
+- **Database:** MariaDB 12.2.2
+- **Docker Container:** espocrm, espocrm-db
+- **Workspace:** `/var/lib/docker/volumes/vmh-espocrm_espocrm/_data`
+
+---
+
+**Letzte Aktualisierung:** 9. März 2026
+
+**Für Fragen oder Updates:** Siehe `custom/docs/ESPOCRM_BEST_PRACTICES.md`