287 lines
7.9 KiB
Markdown
287 lines
7.9 KiB
Markdown
# Dokumentations-Update: Hook-Entwicklung & Entity-Übersicht
|
|
|
|
**Datum:** 9. März 2026
|
|
**Version:** ESPOCRM_BEST_PRACTICES.md 2.0 → 2.1
|
|
**Durchgeführt von:** EspoCRM Docs Maintainer Agent
|
|
|
|
---
|
|
|
|
## Zusammenfassung
|
|
|
|
Umfassende Überarbeitung der Dokumentation mit Fokus auf:
|
|
1. **Hook-Entwicklung** - Neuer Haupt-Abschnitt
|
|
2. **Entity-Übersicht** - Vollständige Liste aller Custom Entities
|
|
3. **Bekannte Probleme** - i18n-Warnungen dokumentiert
|
|
|
|
---
|
|
|
|
## Änderungen im Detail
|
|
|
|
### 1. Neuer Abschnitt: Hook-Entwicklung
|
|
|
|
**Datei:** [custom/docs/ESPOCRM_BEST_PRACTICES.md](custom/docs/ESPOCRM_BEST_PRACTICES.md#hook-entwicklung)
|
|
|
|
**Umfang:** ~600 Zeilen neue Dokumentation
|
|
|
|
**Inhalt:**
|
|
|
|
#### Überblick & Patterns
|
|
- ✅ Hook-Typen-Übersicht (BeforeSave, AfterSave, BeforeRemove, etc.)
|
|
- ✅ Moderne Interface-basierte Hooks (EspoCRM 9.x)
|
|
- ✅ Legacy Hook-Pattern (EspoCRM < 7.0)
|
|
- ✅ Dependency Injection mit Constructor
|
|
- ✅ Verfügbare Services (EntityManager, Config, Language, etc.)
|
|
|
|
#### Praxis-Beispiele aus dem Projekt
|
|
|
|
**Beispiel 1: CBankverbindungen/BankdatenValidation.php**
|
|
- IBAN-Validierung mit Modulo-97-Algorithmus
|
|
- BIC-Format-Prüfung (8 oder 11 Zeichen)
|
|
- Normalisierung (Großbuchstaben, Leerzeichen entfernen)
|
|
- i18n für Fehlermeldungen
|
|
- BadRequest Exception-Handling
|
|
|
|
**Beispiel 2: CDokumente/CDokumente.php**
|
|
- Automatische MD5/SHA256-Hash-Berechnung
|
|
- File-Upload-Erkennung
|
|
- Status-Management (new/changed/synced)
|
|
- API-Limitationen dokumentiert
|
|
|
|
**Beispiel 3: CPuls/UpdateTeamStats.php**
|
|
- Moderne Interface-basierte Implementation (BeforeSave)
|
|
- Construction Injection für EntityManager
|
|
- Statistik-Berechnung für verwandte Entities
|
|
- Performance-Optimierung mit Conditions
|
|
|
|
#### Best Practices
|
|
|
|
**✅ DO:**
|
|
- Interface-basierte Hooks (EspoCRM 9.x)
|
|
- Constructor Injection
|
|
- Validierung in beforeSave
|
|
- Exception-werfen bei Fehlern
|
|
- i18n für Fehlermeldungen
|
|
- Performance-Optimierung mit `isAttributeChanged()`
|
|
|
|
**❌ DON'T:**
|
|
- Komplexe Business-Logic in Hooks
|
|
- Direkte SQL-Queries
|
|
- Externe API-Calls in beforeSave
|
|
- Circular Dependencies
|
|
- UI-Logic in Hooks
|
|
|
|
#### Debugging & Troubleshooting
|
|
- Log-Output-Patterns
|
|
- Cache-Clear & Rebuild-Workflow
|
|
- Circular Dependency Detection
|
|
- Hook-Reihenfolge (Lifecycle)
|
|
|
|
---
|
|
|
|
### 2. Custom Entities Übersicht
|
|
|
|
**Datei:** [custom/docs/ESPOCRM_BEST_PRACTICES.md](custom/docs/ESPOCRM_BEST_PRACTICES.md#custom-entities-übersicht)
|
|
|
|
**Neu hinzugefügt:**
|
|
|
|
#### Tabelle aller 19 Custom Entities
|
|
| Entity | Beschreibung | Hooks | Typ |
|
|
|--------|--------------|-------|-----|
|
|
| CAdressen | Adressen-Verwaltung | - | Base |
|
|
| CAICollections | AI-Dokumenten-Sammlungen | - | Base |
|
|
| CAICollectionCDokumente | Junction: Collections ↔ Dokumente | - | Junction |
|
|
| CBankverbindungen | Bankdaten (IBAN/BIC) | ✅ Validierung | Base |
|
|
| CBeteiligte | Beteiligte Personen | - | Base |
|
|
| CCallQueues | Call-Warteschlangen | - | Base |
|
|
| CDokumente | Dokumenten-Management | ✅ Hash-Berechnung | Base |
|
|
| CKuendigung | Kündigungen | - | Base |
|
|
| CMietinkasso | Mietinkasso-Fälle | - | Base |
|
|
| CMietobjekt | Mietobjekte | - | Base |
|
|
| CPuls | Posteingangs-System | ✅ Statistik | Base |
|
|
| CPulsTeamZuordnung | Puls-Team-Zuordnungen | - | Base |
|
|
| CVMHBeteiligte | VMH-spezifische Beteiligte | - | Base |
|
|
| CVmhErstgespraech | Erstgespräche | - | Base |
|
|
| CVmhMietverhltnis | Mietverhältnisse | - | Base |
|
|
| CVmhRumungsklage | Räumungsklagen | - | Base |
|
|
| CVmhVermieter | Vermieter | - | Base |
|
|
|
|
#### Erweiterte Standard-Entities
|
|
- Contact, Call, User, Meeting, Email, Task
|
|
- PhoneNumber, Team, BpmnUserTask
|
|
|
|
#### Implementierte Hooks (Übersicht)
|
|
1. CBankverbindungen/BankdatenValidation
|
|
2. CDokumente/CDokumente
|
|
3. CPuls/UpdateTeamStats
|
|
|
|
---
|
|
|
|
### 3. Bekannte i18n-Warnungen dokumentiert
|
|
|
|
**Datei:** [custom/docs/ESPOCRM_BEST_PRACTICES.md](custom/docs/ESPOCRM_BEST_PRACTICES.md#bekannte-i18n-warnungen-nicht-kritisch)
|
|
|
|
**Neu im Troubleshooting-Abschnitt:**
|
|
|
|
#### Dokumentierte Warnungen
|
|
```
|
|
⚠ CDokumente (en_US): Link 'cAICollections' fehlt in i18n
|
|
⚠ CAICollections (de_DE): Link 'meetings' fehlt in i18n
|
|
⚠ CAICollections (de_DE): Link 'cDokumente' fehlt in i18n
|
|
⚠ CAICollections (en_US): Link 'cDokumente' fehlt in i18n
|
|
```
|
|
|
|
**Status:** Funktional keine Auswirkung
|
|
|
|
**Behebung:** JSON-Snippets für alle 4 fehlenden i18n-Einträge bereitgestellt
|
|
|
|
---
|
|
|
|
### 4. Inhaltsverzeichnis aktualisiert
|
|
|
|
**Dateien:**
|
|
- [custom/docs/ESPOCRM_BEST_PRACTICES.md](custom/docs/ESPOCRM_BEST_PRACTICES.md#-inhaltsverzeichnis)
|
|
- [custom/DOCUMENTATION_INDEX.md](custom/DOCUMENTATION_INDEX.md)
|
|
|
|
**Änderungen:**
|
|
- ✅ Neuer Punkt 6: "Hook-Entwicklung"
|
|
- ✅ Nummerierung angepasst (Workflow-Management: 6 → 7)
|
|
- ✅ Index aktualisiert mit Hook-Entwicklung
|
|
|
|
---
|
|
|
|
### 5. Architektur-Prinzipien erweitert
|
|
|
|
**Datei:** [custom/docs/ESPOCRM_BEST_PRACTICES.md](custom/docs/ESPOCRM_BEST_PRACTICES.md#architektur-prinzipien)
|
|
|
|
**Änderung:**
|
|
```
|
|
DON'T:
|
|
- ❌ Keine komplexe Business-Logic in Hooks (nutze Services)
|
|
```
|
|
|
|
**Vorher:**
|
|
```
|
|
- ❌ Keine komplexe Logik in Hooks
|
|
```
|
|
|
|
---
|
|
|
|
## Validierung
|
|
|
|
### Ausgeführt
|
|
```bash
|
|
python3 custom/scripts/validate_and_rebuild.py --dry-run
|
|
```
|
|
|
|
### Ergebnisse
|
|
```
|
|
✓ Alle 702 JSON-Dateien syntaktisch korrekt
|
|
✓ 45 Relationships geprüft - alle konsistent
|
|
✓ 7 Formula-Definitionen korrekt platziert
|
|
⚠ 4 unvollständige i18n-Definitionen (dokumentiert)
|
|
✓ 15 Layout-Dateien geprüft, keine Fehler
|
|
✓ Alle Dateirechte korrekt (www-data:www-data)
|
|
✓ Alle 2 CSS-Dateien syntaktisch korrekt
|
|
✓ Alle 11 JavaScript-Dateien syntaktisch korrekt
|
|
✓ Alle 348 PHP-Dateien syntaktisch korrekt
|
|
```
|
|
|
|
**Status:** ✅ Alle Validierungen erfolgreich
|
|
|
|
---
|
|
|
|
## Statistiken
|
|
|
|
### Dokumentationsgröße
|
|
- **Zeilen:** 1698 (vorher: ~1100)
|
|
- **Zunahme:** ~600 Zeilen (+54%)
|
|
- **Abschnitte:** 74 (## Überschriften)
|
|
|
|
### Code-Beispiele
|
|
- **Neue Hook-Beispiele:** 3 vollständige Implementierungen
|
|
- **Code-Blocks:** ~20 neue PHP/JSON-Snippets
|
|
- **Best-Practice-Regeln:** 12 DO's, 5 DON'Ts
|
|
|
|
---
|
|
|
|
## Für AI Agents
|
|
|
|
### Neue Fähigkeiten nach diesem Update
|
|
|
|
**Agents können jetzt:**
|
|
1. ✅ Hook-Code mit modernen Interfaces schreiben
|
|
2. ✅ IBAN-Validierung mit Modulo-97 implementieren
|
|
3. ✅ File-Upload-Hashes automatisch berechnen
|
|
4. ✅ Statistik-Felder automatisch aktualisieren
|
|
5. ✅ Dependency Injection korrekt nutzen
|
|
6. ✅ Circular Dependencies vermeiden
|
|
7. ✅ Alle 19 Custom Entities überblicken
|
|
8. ✅ i18n-Warnungen verstehen und beheben
|
|
|
|
### Verwendung
|
|
|
|
**Neuer Agent briefen:**
|
|
```bash
|
|
python3 custom/scripts/ki_project_overview.py > overview.txt
|
|
cat custom/docs/ESPOCRM_BEST_PRACTICES.md
|
|
```
|
|
|
|
**Hook entwickeln:**
|
|
1. Lies Abschnitt "Hook-Entwicklung" (Zeile ~670-1270)
|
|
2. Wähle passendes Beispiel (Validierung/Hash/Statistik)
|
|
3. Implementiere mit modernem Interface-Pattern
|
|
4. Teste mit validate_and_rebuild.py
|
|
|
|
---
|
|
|
|
## Nächste Schritte (optional)
|
|
|
|
### Optionale Verbesserungen
|
|
|
|
1. **i18n-Warnungen beheben**
|
|
- 4 fehlende Link-Labels hinzufügen
|
|
- JSON-Snippets sind bereitgestellt
|
|
|
|
2. **Weitere Hooks dokumentieren**
|
|
- Falls zukünftig neue Hooks hinzukommen
|
|
- AfterSave, BeforeRemove, AfterRelate Beispiele
|
|
|
|
3. **Tool-Dokumentation erweitern**
|
|
- validate_and_rebuild.py Features dokumentieren
|
|
- Hook-spezifische Validierungen hinzufügen
|
|
|
|
4. **Testing erweitern**
|
|
- Hook-spezifische Unit Tests
|
|
- Circular Dependency Detection Tests
|
|
|
|
---
|
|
|
|
## Dateien geändert
|
|
|
|
1. ✅ `custom/docs/ESPOCRM_BEST_PRACTICES.md` (Version 2.0 → 2.1)
|
|
2. ✅ `custom/DOCUMENTATION_INDEX.md`
|
|
3. ✅ `custom/docs/CHANGELOG_2026-03-09.md` (NEU)
|
|
|
|
**Kein Code geändert** - Nur Dokumentation!
|
|
|
|
---
|
|
|
|
## Verifikation
|
|
|
|
### Dokumentations-Links
|
|
- [ESPOCRM_BEST_PRACTICES.md](custom/docs/ESPOCRM_BEST_PRACTICES.md)
|
|
- [DOCUMENTATION_INDEX.md](custom/DOCUMENTATION_INDEX.md)
|
|
- [Hook-Entwicklung](custom/docs/ESPOCRM_BEST_PRACTICES.md#hook-entwicklung)
|
|
|
|
### Git Diff (falls verfügbar)
|
|
```bash
|
|
git diff custom/docs/ESPOCRM_BEST_PRACTICES.md
|
|
git diff custom/DOCUMENTATION_INDEX.md
|
|
```
|
|
|
|
---
|
|
|
|
**Ende des Updates**
|
|
|
|
Dokumentation ist nun vollständig auf dem neuesten Stand mit umfassender Hook-Entwicklung-Dokumentation und Entity-Übersicht.
|