# 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
   - Rebuild schlägt fehl mit "Column does not exist" → Index auf gelöschtes Feld prüfen

---

## 🆕 Neueste Patterns & Best Practices (März 2026)

### Junction Table UI-Integration

**Pattern:** `columnAttributeMap` + `notStorable` Felder

**Use Case:** Junction-Spalten (wie `hnr`, `syncstatus`, `lastSync`) im Relationship-Panel anzeigen.

**Implementierung:**
- notStorable Felder als UI-Placeholder
- columnAttributeMap für bidirektionales Mapping
- Custom List Layouts für Relationship-Panels
- Hooks für automatische Updates

**Dokumentiert in:** [ESPOCRM_BEST_PRACTICES.md](ESPOCRM_BEST_PRACTICES.md#junction-spalten-im-ui-anzeigen-columnattributemap--notstorable) & [TESTERGEBNISSE_JUNCTION_TABLE.md](TESTERGEBNISSE_JUNCTION_TABLE.md)

### Dokumenten-Propagierung mit Loop-Schutz

**Pattern:** AfterRelate/AfterUnrelate Hooks mit statischem Processing-Array

**Use Case:** Automatische Verknüpfung von Dokumenten zwischen hierarchisch verbundenen Entities.

**Hierarchie-Beispiel:**
```
Räumungsklage ←→ AdvowareAkten ←→ AIKnowledge
Mietinkasso   ←→ AdvowareAkten ←→ AIKnowledge
        ↓             ↓              ↓
           Dokumente (automatisch synchronisiert)
```

**Loop-Schutz:** Statisches Array mit Key `{EntityID}-{DokumentID}-{Aktion}` verhindert Endlos-Rekursion.

**Implementiert in:** `custom/Espo/Custom/Hooks/{CVmhRumungsklage,CMietinkasso,CAdvowareAkten,CAIKnowledge}/Propagate*.php`

**Dokumentiert in:** [ESPOCRM_BEST_PRACTICES.md - Hook-Entwicklung](ESPOCRM_BEST_PRACTICES.md#hook-pattern-dokumenten-propagierung-mit-loop-schutz)

### Sync-Status-Management

**Pattern:** Globaler + Junction-level Status mit automatischer Propagierung

**Struktur:**
- **Global (Parent):** `syncStatus` (synced/unclean), `lastSync`
- **Junction (pro Dokument):** `syncstatus` (new/unclean/synced/failed), `lastSync`

**Hooks:**
- **BeforeSave:** Berechnet globalen Status aus allen Junction-Einträgen
- **AfterRelate:** Setzt Junction-Status auf "new"
- **AfterSave (CDokumente):** Markiert alle Junction-Einträge als "unclean" bei Dokumentänderung

**Real-World:** CAdvowareAkten & CAIKnowledge tracken Sync-Status ihrer verknüpften Dokumente.

---

## 📊 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:** 11. März 2026  
**Version:** 2.3 (Junction Table UI-Integration, Dokumenten-Propagierung, Sync-Status-Management)

**Für Fragen oder Updates:** Siehe `custom/docs/ESPOCRM_BEST_PRACTICES.md`