Refactor code structure for improved readability and maintainability
This commit is contained in:
359
custom/DOCUMENTATION_INDEX.md
Normal file
359
custom/DOCUMENTATION_INDEX.md
Normal file
@@ -0,0 +1,359 @@
|
||||
# 📚 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`
|
||||
Reference in New Issue
Block a user