# 📚 EspoCRM Dokumentations-Index

**Schneller Zugriff auf alle Dokumentations-Ressourcen**

---

## 🎯 Quick Links für AI Agents

### START HIER ⭐
1. **[docs/ESPOCRM_BEST_PRACTICES.md](docs/ESPOCRM_BEST_PRACTICES.md)** - Vollständiges Entwickler-Handbuch
2. **[docs/README.md](docs/README.md)** - Dokumentations-Navigation & Workflow-Guide
3. `python3 custom/scripts/ki_project_overview.py` - Aktueller Projekt-Status für AI

### Essentials
- **[docs/tools/QUICKSTART.md](docs/tools/QUICKSTART.md)** - 5-Minuten Quick Start
- **[custom/scripts/validate_and_rebuild.py](custom/scripts/validate_and_rebuild.py)** - Haupt-Validierungs-Tool
- **Validierung ausführen:** `python3 custom/scripts/validate_and_rebuild.py`

---

## 📁 Dokumentations-Struktur

```
custom/
├── README.md                          ← Custom Actions Blueprint (Architektur)
├── CUSTOM_DIRECTORY.md                ← Verzeichnisstruktur-Übersicht
│
├── docs/                              ← 🆕 ZENTRALE DOKUMENTATION
│   ├── README.md                      ← Dokumentations-Navigation (START)
│   ├── ESPOCRM_BEST_PRACTICES.md     ← ⭐ HAUPTDOKUMENTATION
│   ├── TESTERGEBNISSE_JUNCTION_TABLE.md  ← Junction Table Guide
│   ├── ENTWICKLUNGSPLAN_ENTWICKLUNGEN.md ← Puls-System Spezifikation
│   │
│   ├── tools/                         ← Tool-Dokumentation
│   │   ├── QUICKSTART.md
│   │   ├── VALIDATION_TOOLS.md
│   │   ├── E2E_TESTS_README.md
│   │   ├── KI_OVERVIEW_README.md
│   │   └── VALIDATOR_README.md
│   │
│   └── workflows/                     ← Workflow-Dokumentation
│       └── README.md
│
├── scripts/                           ← Entwicklungs-Tools
│   ├── validate_and_rebuild.py       ← Haupt-Validierungs-Tool
│   ├── e2e_tests.py                  ← End-to-End Tests
│   ├── ki_project_overview.py        ← Projekt-Analyse für AI
│   ├── espocrm_api_client.py         ← API Client Library
│   ├── ki-overview.sh                ← Legacy Overview Script
│   ├── run_e2e_tests.sh              ← E2E Test Runner
│   └── junctiontabletests/           ← Junction Table Tests
│
└── workflows/                         ← Workflow JSON-Definitionen
    └── README.md                     ← Workflow-Befehle
```

---

## 📖 Dokumentations-Kategorien

### 1️⃣ Entwickler-Handbuch

#### [docs/ESPOCRM_BEST_PRACTICES.md](docs/ESPOCRM_BEST_PRACTICES.md) ⭐
**Das Hauptdokument - Start hier!**

**Inhalt:**
- ✅ Projekt-Übersicht & System-Architektur
- ✅ Architektur-Prinzipien (Clean Code, 3-Schichten)
- ✅ Entity-Entwicklung (Templates, Naming, i18n)
- ✅ Relationship-Patterns (One-to-Many, Many-to-Many, Junction)
- ✅ API-Entwicklung (REST, Custom Endpoints)
- ✅ Hook-Entwicklung (Entity Lifecycle Events)
- ✅ Workflow-Management
- ✅ Testing & Validierung
- ✅ Fehlerbehandlung & Troubleshooting
- ✅ Deployment-Prozess

**Wann verwenden:**
- Neuen AI Agent briefen
- Entity erstellen
- Relationship implementieren
- API-Endpoint entwickeln
- Hook für Validierung/Berechnung erstellen
- Fehler debuggen

---

### 2️⃣ Spezial-Themen

#### [docs/TESTERGEBNISSE_JUNCTION_TABLE.md](docs/TESTERGEBNISSE_JUNCTION_TABLE.md)
**Junction Tables mit additionalColumns**

**Inhalt:**
- Many-to-Many Relationships mit Zusatzfeldern
- Junction Entity als API-Endpoint
- API-CRUD Operationen
- Vollständige Code-Beispiele
- ⚠️ UI-Panel Warnung (405 Fehler)

**Wann verwenden:**
- Many-to-Many mit Zusatzfeldern implementieren
- Junction Entity API nutzen
- additionalColumns verstehen

---

#### [docs/ENTWICKLUNGSPLAN_ENTWICKLUNGEN.md](docs/ENTWICKLUNGSPLAN_ENTWICKLUNGEN.md)
**Puls-System (CPuls) Spezifikation**

**Inhalt:**
- Posteingangs-System mit KI-Analyse
- Team-basierte Dokumenten-Workflows
- First-Read-Closes Prinzip
- Entity-Definitionen CPuls, CPulsTeamZuordnung
- Middleware-Architektur

**Wann verwenden:**
- CPuls-Entity weiterentwickeln
- Dokumenten-Workflow verstehen
- KI-Integration planen

---

### 3️⃣ Architektur & Struktur

#### [README.md](README.md)
**Custom Actions - Implementierungsprinzip**

**Inhalt:**
- Drei-Schichten-Architektur
- Custom Button Actions Blueprint
- Entity-Erstellung mit Relationen
- Code-Templates
- Sicherheit & ACL

**Wann verwenden:**
- Custom Button Action erstellen
- Controller/Service Pattern verstehen
- Architektur-Overview benötigen

---

#### [CUSTOM_DIRECTORY.md](CUSTOM_DIRECTORY.md)
**Verzeichnisstruktur-Übersicht**

**Inhalt:**
- Vollständige custom/ Struktur
- Backend (Espo/Custom/)
- Frontend (client/custom/)
- Metadata-Organisation
- Scripts & Workflows

**Wann verwenden:**
- Datei-Platzierung nachschlagen
- Verzeichnis-Organisation verstehen
- Neue Dateien korrekt anlegen

---

### 4️⃣ Tool-Dokumentation

#### [docs/tools/QUICKSTART.md](docs/tools/QUICKSTART.md)
**5-Minuten Quick Start**

```bash
python3 custom/scripts/validate_and_rebuild.py
```

---

#### [docs/tools/VALIDATION_TOOLS.md](docs/tools/VALIDATION_TOOLS.md)
**Validierungs-Tools Details**
- PHP-CLI (php -l)
- CSSLint
- JSHint
- Integration

---

#### [docs/tools/E2E_TESTS_README.md](docs/tools/E2E_TESTS_README.md)
**End-to-End Test Framework**
- CRUD-Tests
- Relationship-Tests
- Konfiguration

---

#### [docs/tools/KI_OVERVIEW_README.md](docs/tools/KI_OVERVIEW_README.md)
**KI-Projekt-Übersicht Tool**

```bash
python3 custom/scripts/ki_project_overview.py > /tmp/project-overview.txt
```

---

### 5️⃣ Workflow-Management

#### [docs/workflows/README.md](docs/workflows/README.md)
**Workflow-Format & Management**

**Befehle:**
```bash
# Liste
php custom/scripts/workflow_manager.php list

# Import
php custom/scripts/workflow_manager.php import custom/workflows/my-workflow.json

# Export
php custom/scripts/workflow_manager.php export
```

---

## 🛠️ Wichtigste Tools

| Tool | Zweck | Befehl |
|------|-------|--------|
| **validate_and_rebuild.py** | 🎯 Validierung + Rebuild + E2E + Fehlerlog | `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` |

**NEU in validate_and_rebuild.py:**
- ✅ Automatische Fehlerlog-Analyse bei Rebuild-Fehlern
- ✅ Zeigt letzte 50 Log-Zeilen
- ✅ Filtert ERROR/WARNING/EXCEPTION
- ✅ Gibt Log-File-Pfad aus

---

## 🎓 Typische Workflows

### 1. Neuen AI Agent briefen

```bash
# 1. Hauptdokumentation lesen
cat custom/docs/ESPOCRM_BEST_PRACTICES.md

# 2. Aktuellen Projekt-Status holen
python3 custom/scripts/ki_project_overview.py > /tmp/project-overview.txt

# 3. Dokumentations-Navigation
cat custom/docs/README.md
```

---

### 2. Neue Entity entwickeln

```bash
# 1. Template nachschlagen
cat custom/docs/ESPOCRM_BEST_PRACTICES.md | grep -A 50 "Entity Definition Template"

# 2. Entity-Dateien erstellen (entityDefs, scopes, i18n)

# 3. Validierung + Rebuild
python3 custom/scripts/validate_and_rebuild.py
```

---

### 3. Relationship implementieren

```bash
# 1. Pattern nachschlagen
cat custom/docs/ESPOCRM_BEST_PRACTICES.md | grep -A 100 "Relationship-Patterns"

# 2. Links konfigurieren

# 3. Validierung (prüft bidirektionale Konsistenz)
python3 custom/scripts/validate_and_rebuild.py
```

---

### 4. Junction Table mit additionalColumns

```bash
# 1. Vollständige Anleitung
cat custom/docs/TESTERGEBNISSE_JUNCTION_TABLE.md

# 2. Implementierung (Entity + Controller + Service)

# 3. Validierung
python3 custom/scripts/validate_and_rebuild.py
```

---

### 5. Fehler debuggen

```bash
# 1. Validierung ausführen (zeigt automatisch Fehlerlog)
python3 custom/scripts/validate_and_rebuild.py

# 2. Troubleshooting Guide
cat custom/docs/ESPOCRM_BEST_PRACTICES.md | grep -A 200 "Troubleshooting"
```

---

## 🆘 Support & Hilfe

### Bei Problemen:

1. **Fehlerlog-Analyse:**
   ```bash
   python3 custom/scripts/validate_and_rebuild.py
   # → Zeigt automatisch Fehlerlog 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 (de_DE + en_US) anlegen
   - Relationship kaputt → bidirektional prüfen (foreign)
   - ACL 403 → Rechte in Admin UI setzen
   - 405 Fehler → Keine additionalColumns in UI-Panels!

---

## 📊 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`

---

## 🔄 Reorganisation (9. März 2026)

**Änderungen:**
- ✅ Alle Dokumentation zentralisiert in `custom/docs/`
- ✅ Tool-Dokumentation in `custom/docs/tools/`
- ✅ Workflow-Dokumentation in `custom/docs/workflows/`
- ✅ Neue Hauptdokumentation: `ESPOCRM_BEST_PRACTICES.md`
- ✅ Test-Scripts organisiert in `custom/scripts/junctiontabletests/`
- ✅ validate_and_rebuild.py erweitert um automatische Fehlerlog-Ausgabe

**Migration:**
- `scripts/KI_OVERVIEW_README.md` → `docs/tools/`
- `scripts/VALIDATION_TOOLS.md` → `docs/tools/`
- `scripts/E2E_TESTS_README.md` → `docs/tools/`
- `scripts/QUICKSTART.md` → `docs/tools/`
- `scripts/VALIDATOR_README.md` → `docs/tools/`
- `workflows/README.md` → `docs/workflows/`
- `TESTERGEBNISSE_JUNCTION_TABLE.md` → `docs/`
- `ENTWICKLUNGSPLAN_ENTWICKLUNGEN.md` → `docs/`

---

**Letzte Aktualisierung:** 9. März 2026

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