360 lines
9.5 KiB
Markdown
360 lines
9.5 KiB
Markdown
# 📚 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)
|
||
- ✅ Workflow-Management
|
||
- ✅ Testing & Validierung
|
||
- ✅ Fehlerbehandlung & Troubleshooting
|
||
- ✅ Deployment-Prozess
|
||
|
||
**Wann verwenden:**
|
||
- Neuen AI Agent briefen
|
||
- Entity erstellen
|
||
- Relationship implementieren
|
||
- API-Endpoint entwickeln
|
||
- 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`
|