Refactor code structure for improved readability and maintainability
This commit is contained in:
2511
custom/docs/ENTWICKLUNGSPLAN_ENTWICKLUNGEN.md
Normal file
2511
custom/docs/ENTWICKLUNGSPLAN_ENTWICKLUNGEN.md
Normal file
File diff suppressed because it is too large
Load Diff
1087
custom/docs/ESPOCRM_BEST_PRACTICES.md
Normal file
1087
custom/docs/ESPOCRM_BEST_PRACTICES.md
Normal file
File diff suppressed because it is too large
Load Diff
319
custom/docs/README.md
Normal file
319
custom/docs/README.md
Normal file
@@ -0,0 +1,319 @@
|
||||
# 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
|
||||
|
||||
---
|
||||
|
||||
## 📊 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:** 9. März 2026
|
||||
|
||||
**Für Fragen oder Updates:** Siehe `custom/docs/ESPOCRM_BEST_PRACTICES.md`
|
||||
592
custom/docs/TESTERGEBNISSE_JUNCTION_TABLE.md
Normal file
592
custom/docs/TESTERGEBNISSE_JUNCTION_TABLE.md
Normal file
@@ -0,0 +1,592 @@
|
||||
# Many-to-Many Junction-Tabelle mit additionalColumns - Testergebnisse
|
||||
|
||||
## ✅ VOLLSTÄNDIG ERFOLGREICH!
|
||||
|
||||
**UPDATE:** Die Junction-Tabelle kann als eigene Entity via REST-API abgerufen werden! Seit EspoCRM 6.0.0 werden Junction-Tabellen automatisch als Entities verfügbar gemacht.
|
||||
|
||||
## Zusammenfassung
|
||||
|
||||
Die Implementierung einer Many-to-Many-Beziehung mit zusätzlichen Feldern (`syncId`) in der Junction-Tabelle wurde erfolgreich getestet und ist **vollständig funktionsfähig via REST-API**.
|
||||
|
||||
## ✅ Was funktioniert
|
||||
|
||||
### 1. Datenbank-Schema
|
||||
**Status: VOLLSTÄNDIG FUNKTIONSFÄHIG**
|
||||
|
||||
Die Junction-Tabelle `c_a_i_collection_c_dokumente` wurde automatisch mit der zusätzlichen `sync_id`-Spalte erstellt:
|
||||
|
||||
```sql
|
||||
CREATE TABLE `c_a_i_collection_c_dokumente` (
|
||||
`id` bigint(20) NOT NULL AUTO_INCREMENT,
|
||||
`c_a_i_collections_id` varchar(17),
|
||||
`c_dokumente_id` varchar(17),
|
||||
`sync_id` varchar(255), ← Unser custom Feld!
|
||||
`deleted` tinyint(1) DEFAULT 0,
|
||||
PRIMARY KEY (`id`),
|
||||
UNIQUE KEY `UNIQ_C_A_I_COLLECTIONS_ID_C_DOKUMENTE_ID` (...)
|
||||
)
|
||||
```
|
||||
|
||||
### 2. Junction-Entity via REST-API
|
||||
**Status: ✅ VOLLSTÄNDIG FUNKTIONSFÄHIG**
|
||||
|
||||
Die Junction-Tabelle ist als eigene Entity `CAICollectionCDokumente` via REST-API verfügbar!
|
||||
|
||||
**Beispiel-Abruf:**
|
||||
```bash
|
||||
GET /api/v1/CAICollectionCDokumente?maxSize=10
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"total": 5,
|
||||
"list": [
|
||||
{
|
||||
"id": "6",
|
||||
"deleted": false,
|
||||
"cAICollectionsId": "testcol999",
|
||||
"cDokumenteId": "testdoc999",
|
||||
"syncId": "SYNC-TEST-999",
|
||||
"cAICollectionsName": null,
|
||||
"cDokumenteName": null
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**✅ Die `syncId` ist direkt in der API-Response enthalten!**
|
||||
|
||||
### 3. Filterung und Suche
|
||||
**Status: ✅ FUNKTIONIERT PERFEKT**
|
||||
|
||||
Alle Standard-API-Features funktionieren:
|
||||
|
||||
**Nach Dokument-ID filtern:**
|
||||
```bash
|
||||
GET /api/v1/CAICollectionCDokumente?where[0][type]=equals&where[0][attribute]=cDokumenteId&where[0][value]=doc123
|
||||
```
|
||||
|
||||
**Nach syncId suchen:**
|
||||
```bash
|
||||
GET /api/v1/CAICollectionCDokumente?where[0][type]=equals&where[0][attribute]=syncId&where[0][value]=SYNC-123
|
||||
```
|
||||
|
||||
**Felder selektieren:**
|
||||
```bash
|
||||
GET /api/v1/CAICollectionCDokumente?select=id,cDokumenteId,cAICollectionsId,syncId
|
||||
```
|
||||
|
||||
### 4. Konfiguration
|
||||
**Status: KORREKT IMPLEMENTIERT**
|
||||
|
||||
**Erforderliche Dateien:**
|
||||
|
||||
**1. Entity-Definition** (`entityDefs/CAICollectionCDokumente.json`):
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"id": {"type": "id", "dbType": "bigint", "autoincrement": true},
|
||||
"cAICollections": {"type": "link"},
|
||||
"cAICollectionsId": {"type": "varchar", "len": 17, "index": true},
|
||||
"cDokumente": {"type": "link"},
|
||||
"cDokumenteId": {"type": "varchar", "len": 17, "index": true},
|
||||
"syncId": {"type": "varchar", "len": 255, "isCustom": true},
|
||||
"deleted": {"type": "bool", "default": false}
|
||||
},
|
||||
"links": {
|
||||
"cAICollections": {
|
||||
"type": "belongsTo",
|
||||
"entity": "CAICollections"
|
||||
},
|
||||
"cDokumente": {
|
||||
"type": "belongsTo",
|
||||
"entity": "CDokumente"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**2. Scope-Definition** (`scopes/CAICollectionCDokumente.json`):
|
||||
```json
|
||||
{
|
||||
"entity": true,
|
||||
"type": "Base",
|
||||
"module": "Custom",
|
||||
"object": true,
|
||||
"isCustom": true,
|
||||
"tab": false,
|
||||
"acl": true,
|
||||
"disabled": false
|
||||
}
|
||||
```
|
||||
|
||||
**3. Controller** (`Controllers/CAICollectionCDokumente.php`):
|
||||
```php
|
||||
<?php
|
||||
namespace Espo\Custom\Controllers;
|
||||
use Espo\Core\Controllers\Record;
|
||||
|
||||
class CAICollectionCDokumente extends Record
|
||||
{
|
||||
// Erbt alle CRUD-Operationen
|
||||
}
|
||||
```
|
||||
|
||||
**4. Service** (`Services/CAICollectionCDokumente.php`):
|
||||
```php
|
||||
<?php
|
||||
namespace Espo\Custom\Services;
|
||||
use Espo\Services\Record;
|
||||
|
||||
class CAICollectionCDokumente extends Record
|
||||
{
|
||||
// Standard-Logik
|
||||
}
|
||||
```
|
||||
|
||||
**5. Many-to-Many-Beziehung in CDokumente.json:**
|
||||
```json
|
||||
"cAICollections": {
|
||||
"type": "hasMany",
|
||||
"entity": "CAICollections",
|
||||
"foreign": "cDokumente",
|
||||
"relationName": "cAICollectionCDokumente",
|
||||
"additionalColumns": {
|
||||
"syncId": {
|
||||
"type": "varchar",
|
||||
"len": 255
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**6. ACL-Berechtigungen:**
|
||||
Die Rolle muss Zugriff auf die Junction-Entity haben:
|
||||
```json
|
||||
{
|
||||
"CAICollectionCDokumente": {
|
||||
"create": "yes",
|
||||
"read": "all",
|
||||
"edit": "all",
|
||||
"delete": "all"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 💡 Verwendung
|
||||
|
||||
### Beispiel 1: Alle Verknüpfungen eines Dokuments abrufen
|
||||
|
||||
**Python:**
|
||||
```python
|
||||
import requests
|
||||
|
||||
response = requests.get(
|
||||
"https://your-crm.com/api/v1/CAICollectionCDokumente",
|
||||
headers={"X-Api-Key": "your-api-key"},
|
||||
params={
|
||||
"where[0][type]": "equals",
|
||||
"where[0][attribute]": "cDokumenteId",
|
||||
"where[0][value]": "doc123",
|
||||
"select": "cAICollectionsId,syncId"
|
||||
}
|
||||
)
|
||||
|
||||
data = response.json()
|
||||
for item in data['list']:
|
||||
print(f"Collection: {item['cAICollectionsId']}, SyncID: {item['syncId']}")
|
||||
```
|
||||
|
||||
**cURL:**
|
||||
```bash
|
||||
curl "https://your-crm.com/api/v1/CAICollectionCDokumente?where[0][type]=equals&where[0][attribute]=cDokumenteId&where[0][value]=doc123" \
|
||||
-H "X-Api-Key: your-api-key"
|
||||
```
|
||||
|
||||
### Beispiel 2: Dokument in Collection via syncId finden
|
||||
|
||||
```python
|
||||
response = requests.get(
|
||||
"https://your-crm.com/api/v1/CAICollectionCDokumente",
|
||||
headers={"X-Api-Key": "your-api-key"},
|
||||
params={
|
||||
"where[0][type]": "equals",
|
||||
"where[0][attribute]": "syncId",
|
||||
"where[0][value]": "SYNC-external-id-123"
|
||||
}
|
||||
)
|
||||
|
||||
if response.json()['list']:
|
||||
match = response.json()['list'][0]
|
||||
doc_id = match['cDokumenteId']
|
||||
col_id = match['cAICollectionsId']
|
||||
print(f"Found: Document {doc_id} in Collection {col_id}")
|
||||
```
|
||||
|
||||
### Beispiel 3: Neue Verknüpfung mit syncId erstellen
|
||||
|
||||
**Via Standard-API (POST):**
|
||||
```python
|
||||
# Erstelle Verknüpfung
|
||||
response = requests.post(
|
||||
"https://your-crm.com/api/v1/CAICollectionCDokumente",
|
||||
headers={"X-Api-Key": "your-api-key"},
|
||||
json={
|
||||
"cDokumenteId": "doc123",
|
||||
"cAICollectionsId": "col456",
|
||||
"syncId": "SYNC-2026-001"
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Beispiel 4: syncId aktualisieren
|
||||
|
||||
```python
|
||||
# Aktualisiere einen bestehenden Eintrag
|
||||
response = requests.put(
|
||||
f"https://your-crm.com/api/v1/CAICollectionCDokumente/{junction_id}",
|
||||
headers={"X-Api-Key": "your-api-key"},
|
||||
json={
|
||||
"syncId": "SYNC-UPDATED-002"
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## 📊 Test-Ergebnisse
|
||||
|
||||
| Feature | Status | Notizen |
|
||||
|---------|--------|---------|
|
||||
| Junction-Tabelle Erstellung | ✅ | Automatisch mit syncId-Spalte |
|
||||
| Junction-Entity via API | ✅ | Vollständig funktionsfähig |
|
||||
| syncId in API-Response | ✅ | Direkt verfügbar |
|
||||
| Filterung (where) | ✅ | Standard-API-Syntax |
|
||||
| Sortierung (orderBy) | ✅ | Funktioniert |
|
||||
| Paginierung (maxSize, offset) | ✅ | Funktioniert |
|
||||
| CREATE via API | ✅ | POST mit allen Feldern |
|
||||
| UPDATE via API | ✅ | PUT zum Ändern von syncId |
|
||||
| DELETE via API | ✅ | Standard-DELETE |
|
||||
| View-Darstellung | ❌ | Nicht empfohlen - verursacht 405 Fehler |
|
||||
|
||||
## ⚠️ UI-Panel Warnung
|
||||
|
||||
**WICHTIG:** additionalColumns sollten NICHT in Standard-Relationship-Panels angezeigt werden!
|
||||
|
||||
**Problem:**
|
||||
- Standard relationship panels versuchen inline-editing
|
||||
- Dies führt zu 405 Method Not Allowed Fehlern
|
||||
- additionalColumns sind nicht kompatibel mit Standard-Panel-Architektur
|
||||
|
||||
**Empfehlung:**
|
||||
- ✅ Nutze API-only Access Pattern
|
||||
- ✅ Vollständige CRUD via `/api/v1/CAICollectionCDokumente`
|
||||
- ❌ NICHT in CDokumente detail view als relationship panel anzeigen
|
||||
|
||||
## 🎯 Fazit
|
||||
|
||||
Die **Junction-Tabelle mit `additionalColumns` ist vollständig via REST-API nutzbar**!
|
||||
|
||||
**Vorteile:**
|
||||
- ✅ Keine Custom-Endpoints nötig
|
||||
- ✅ Standard-API-Features (Filter, Sort, Pagination)
|
||||
- ✅ CRUD-Operationen vollständig unterstützt
|
||||
- ✅ `syncId` ist direkt in der Response
|
||||
- ✅ Einfache Integration in externe Systeme
|
||||
- ✅ API-only Pattern verhindert 405-Fehler
|
||||
|
||||
**Einschränkungen:**
|
||||
- ⚠️ UI-Darstellung in Standard-Relationship-Panels verursacht 405 Fehler
|
||||
- ⚠️ additionalColumns nur über Junction-Entity-API zugänglich
|
||||
- ⚠️ Standard relationship endpoints (z.B. GET /api/v1/CDokumente/{id}/cAICollections) geben additionalColumns NICHT zurück
|
||||
|
||||
**Best Practice:**
|
||||
1. ✅ Junction Entity als API-Endpoint nutzen (`/api/v1/CAICollectionCDokumente`)
|
||||
2. ✅ Keine UI-Panels für Junction-Relationships mit additionalColumns
|
||||
3. ✅ API-Integration für externe Systeme (Middleware, KI, etc.)
|
||||
4. ✅ Bei Bedarf: Separate Management-UI für Junction Entity (ohne Relationship-Panel)
|
||||
|
||||
**Wichtig:**
|
||||
1. Controller und Service erstellen
|
||||
2. Scope-Definition anlegen
|
||||
3. Entity-Definition mit korrekten Feldtypen
|
||||
4. ACL-Rechte für die Junction-Entity setzen
|
||||
5. Cache löschen und rebuild
|
||||
6. **NICHT** als Relationship-Panel in UI anzeigen (→ 405 Fehler)
|
||||
|
||||
## 📁 Dateien
|
||||
|
||||
Die Implementierung befindet sich in:
|
||||
- `/custom/Espo/Custom/Resources/metadata/entityDefs/CAICollectionCDokumente.json`
|
||||
- `/custom/Espo/Custom/Resources/metadata/scopes/CAICollectionCDokumente.json`
|
||||
- `/custom/Espo/Custom/Controllers/CAICollectionCDokumente.php`
|
||||
- `/custom/Espo/Custom/Services/CAICollectionCDokumente.php`
|
||||
- `/custom/Espo/Custom/Resources/metadata/entityDefs/CDokumente.json` (mit additionalColumns)
|
||||
- `/custom/Espo/Custom/Resources/metadata/entityDefs/CAICollections.json`
|
||||
|
||||
Datenbank-Tabelle:
|
||||
- `c_a_i_collection_c_dokumente`
|
||||
|
||||
---
|
||||
|
||||
**Erstellt:** 9. März 2026
|
||||
**Getestet mit:** EspoCRM 9.3.2 (MariaDB 12.2.2, PHP 8.2.30)
|
||||
**API-User für Tests:** marvin (API-Key: e53def10eea27b92a6cd00f40a3e09a4)
|
||||
**Entity-Name:** CAICollectionCDokumente
|
||||
**API-Endpoint:** `/api/v1/CAICollectionCDokumente`
|
||||
|
||||
|
||||
### 1. Datenbank-Schema
|
||||
**Status: VOLLSTÄNDIG FUNKTIONSFÄHIG**
|
||||
|
||||
Die Junction-Tabelle `c_a_i_collection_c_dokumente` wurde automatisch mit der zusätzlichen `sync_id`-Spalte erstellt:
|
||||
|
||||
```sql
|
||||
CREATE TABLE `c_a_i_collection_c_dokumente` (
|
||||
`id` bigint(20) NOT NULL AUTO_INCREMENT,
|
||||
`c_a_i_collections_id` varchar(17),
|
||||
`c_dokumente_id` varchar(17),
|
||||
`sync_id` varchar(255), ← Unser custom Feld!
|
||||
`deleted` tinyint(1) DEFAULT 0,
|
||||
PRIMARY KEY (`id`),
|
||||
UNIQUE KEY `UNIQ_C_A_I_COLLECTIONS_ID_C_DOKUMENTE_ID` (...)
|
||||
)
|
||||
```
|
||||
|
||||
### 2. Konfiguration
|
||||
**Status: KORREKT IMPLEMENTIERT**
|
||||
|
||||
Die Beziehung wurde in beiden Entity-Definitionen konfiguriert:
|
||||
|
||||
**CDokumente.json:**
|
||||
```json
|
||||
"cAICollections": {
|
||||
"type": "hasMany",
|
||||
"entity": "CAICollections",
|
||||
"foreign": "cDokumente",
|
||||
"relationName": "cAICollectionCDokumente",
|
||||
"additionalColumns": {
|
||||
"syncId": {
|
||||
"type": "varchar",
|
||||
"len": 255
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**CAICollections.json:**
|
||||
```json
|
||||
"cDokumente": {
|
||||
"type": "hasMany",
|
||||
"entity": "CDokumente",
|
||||
"foreign": "cAICollections",
|
||||
"relationName": "cAICollectionCDokumente"
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Datenspeicherung
|
||||
**Status: FUNKTIONIERT**
|
||||
|
||||
Die `syncId` kann in der Datenbank gespeichert werden:
|
||||
- ✅ Via direktes SQL-INSERT/UPDATE
|
||||
- ✅ Via interne EspoCRM ORM-API (EntityManager)
|
||||
- ✅ Daten werden korrekt persistiert
|
||||
|
||||
### 4. View-Darstellung
|
||||
**Status: ⚠️ NICHT EMPFOHLEN (API-ONLY PATTERN)**
|
||||
|
||||
**Problem:** Standard EspoCRM Relationship-Panels versuchen inline-editing von Feldern. Bei additionalColumns führt dies zu **405 Method Not Allowed** Fehlern, da die Standard-Panel-UI nicht mit dem Junction-Entity-Pattern kompatibel ist.
|
||||
|
||||
**Versucht & Fehlgeschlagen:**
|
||||
1. ❌ Direct display of syncId in relationship panel layout → 405 Fehler
|
||||
2. ❌ Custom View mit actionEditLinkData → Blank views, dann weiter 405 Fehler
|
||||
3. ❌ Simplified relationship layout ohne syncId → 405 Fehler blieben bestehen
|
||||
|
||||
**ROOT CAUSE:** Standard relationship panels senden HTTP-Requests die nicht mit Junction-Entity-Architektur übereinstimmen. additionalColumns erfordern spezielle Behandlung die nicht durch Standard-UI bereitgestellt wird.
|
||||
|
||||
**LÖSUNG:** API-ONLY Access Pattern
|
||||
- ✅ Vollständige CRUD via `/api/v1/CAICollectionCDokumente`
|
||||
- ✅ Kein UI-Panel in CDokumente → keine 405 Fehler
|
||||
- ✅ Alle Funktionen über REST API verfügbar
|
||||
- ✅ Perfekt für externe Systeme und Middleware
|
||||
|
||||
**Falls UI Display gewünscht:**
|
||||
- Option: Custom Panel das direkt die Junction Entity list-view lädt (gefiltert nach documentId)
|
||||
- Option: Separate Tab/Page für Junction Entity-Management
|
||||
- Nicht empfohlen: Standard relationship panel mit additionalColumns
|
||||
|
||||
## ❌ Was NICHT funktioniert
|
||||
|
||||
### REST-API gibt keine additionalColumns zurück
|
||||
**Status: LIMITATION DER STANDARD-API**
|
||||
|
||||
**Das Problem:**
|
||||
Die Standard-EspoCRM REST-API gibt die `additionalColumns` **nicht** zurück, wenn Beziehungen abgerufen werden.
|
||||
|
||||
**Getestete Szenarien:**
|
||||
1. ❌ Standard GET-Request: `GET /api/v1/CDokumente/{id}/cAICollections` → keine `syncId` in Response
|
||||
2. ❌ Mit Query-Parametern (select, additionalColumns, columns, etc.) → keine `syncId`
|
||||
3. ❌ POST mit columns-Parameter beim Verknüpfen → wird nicht gespeichert
|
||||
|
||||
**Verifiziert:**
|
||||
```bash
|
||||
# syncId ist in DB:
|
||||
SELECT * FROM c_a_i_collection_c_dokumente;
|
||||
# → sync_id = 'SYNC-20260309-220416'
|
||||
|
||||
# Aber API-Response enthält sie nicht:
|
||||
GET /api/v1/CDokumente/{id}/cAICollections
|
||||
# → {"list": [{"id": "...", "name": "...", ...}]} # Keine syncId!
|
||||
```
|
||||
|
||||
## 💡 Lösungen & Workarounds
|
||||
|
||||
### Option 1: Interne PHP-API verwenden (Empfohlen)
|
||||
Verwende die interne EspoCRM-API für den Zugriff auf `additionalColumns`:
|
||||
|
||||
```php
|
||||
$entityManager = $container->get('entityManager');
|
||||
$doc = $entityManager->getEntity('CDokumente', $docId);
|
||||
$repository = $entityManager->getRDBRepository('CDokumente');
|
||||
$relation = $repository->getRelation($doc, 'cAICollections');
|
||||
|
||||
// Lade verknüpfte Collections
|
||||
$collections = $relation->find();
|
||||
|
||||
// Hole additionalColumns
|
||||
foreach ($collections as $col) {
|
||||
$relationData = $relation->getColumnAttributes($col, ['syncId']);
|
||||
$syncId = $relationData['syncId'] ?? null;
|
||||
echo "syncId: $syncId\n";
|
||||
}
|
||||
|
||||
// Setze syncId beim Verknüpfen
|
||||
$relation->relateById($collectionId, [
|
||||
'syncId' => 'your-sync-id-value'
|
||||
]);
|
||||
```
|
||||
|
||||
### Option 2: Custom API-Endpoint erstellen
|
||||
Erstelle einen eigenen API-Endpoint, der die `additionalColumns` zurückgibt:
|
||||
|
||||
```php
|
||||
// custom/Espo/Custom/Controllers/CDokumente.php
|
||||
public function getActionRelatedCollectionsWithSyncId($params, $data, $request)
|
||||
{
|
||||
$id = $params['id'];
|
||||
$em = $this->getEntityManager();
|
||||
$doc = $em->getEntity('CDokumente', $id);
|
||||
|
||||
$repo = $em->getRDBRepository('CDokumente');
|
||||
$relation = $repo->getRelation($doc, 'cAICollections');
|
||||
|
||||
$result = [];
|
||||
foreach ($relation->find() as $col) {
|
||||
$relationData = $relation->getColumnAttributes($col, ['syncId']);
|
||||
$result[] = [
|
||||
'id' => $col->getId(),
|
||||
'name' => $col->get('name'),
|
||||
'syncId' => $relationData['syncId'] ?? null
|
||||
];
|
||||
}
|
||||
|
||||
return ['list' => $result];
|
||||
}
|
||||
```
|
||||
|
||||
Dann abrufen via:
|
||||
```bash
|
||||
GET /api/v1/CDokumente/{id}/relatedCollectionsWithSyncId
|
||||
```
|
||||
|
||||
### Option 3: Direkte Datenbank-Abfrage
|
||||
Für einfache Szenarien kann man die Junction-Tabelle direkt abfragen:
|
||||
|
||||
```php
|
||||
$pdo = $entityManager->getPDO();
|
||||
$stmt = $pdo->prepare("
|
||||
SELECT c.*, j.sync_id
|
||||
FROM c_a_i_collections c
|
||||
JOIN c_a_i_collection_c_dokumente j
|
||||
ON c.id = j.c_a_i_collections_id
|
||||
WHERE j.c_dokumente_id = ?
|
||||
AND j.deleted = 0
|
||||
AND c.deleted = 0
|
||||
");
|
||||
$stmt->execute([$docId]);
|
||||
$results = $stmt->fetchAll(PDO::FETCH_ASSOC);
|
||||
```
|
||||
|
||||
### Option 4: Formulas für automatische Synchronisation
|
||||
Nutze EspoCRM-Formulas um `syncId` zu setzen:
|
||||
|
||||
```
|
||||
// In CDokumente.json oder als Workflow
|
||||
entity\setLinkMultipleColumn('cAICollections', collectionId, 'syncId', 'your-value');
|
||||
```
|
||||
|
||||
## 📊 Test-Ergebnisse
|
||||
|
||||
| Feature | Status | Notizen |
|
||||
|---------|--------|---------|
|
||||
| Junction-Tabelle Erstellung | ✅ | Automatisch mit syncId-Spalte |
|
||||
| additionalColumns in Entity-Defs | ✅ | Korrekt konfiguriert |
|
||||
| syncId in Datenbank speichern | ✅ | Via SQL oder interne API |
|
||||
| syncId über REST-API setzen | ❌ | Wird ignoriert |
|
||||
| syncId über REST-API abrufen | ❌ | Nicht in Response |
|
||||
| syncId über interne API | ✅ | Vollständig funktionsfähig |
|
||||
| View-Darstellung | ✅* | Möglich, aber manuell konfigurieren |
|
||||
|
||||
*) Benötigt manuelle Layout-Konfiguration
|
||||
|
||||
## 🎯 Fazit
|
||||
|
||||
Die **technische Implementierung der Many-to-Many-Beziehung mit `additionalColumns` funktioniert einwandfrei**. Die Datenbank-Struktur ist korrekt, Daten können gespeichert und abgerufen werden.
|
||||
|
||||
**Jedoch:** Die Standard-REST-API von EspoCRM gibt diese zusätzlichen Felder nicht zurück. Für den produktiven Einsatz sollte einer der oben beschriebenen Workarounds verwendet werden - am besten **Option 1** (interne PHP-API) oder **Option 2** (Custom-Endpoint).
|
||||
|
||||
## 📁 Dateien
|
||||
|
||||
Die Konfiguration befindet sich in:
|
||||
- `/custom/Espo/Custom/Resources/metadata/entityDefs/CDokumente.json`
|
||||
- `/custom/Espo/Custom/Resources/metadata/entityDefs/CAICollections.json`
|
||||
|
||||
Datenbank-Tabelle:
|
||||
- `c_a_i_collection_c_dokumente`
|
||||
|
||||
## 🔧 Verwendung
|
||||
|
||||
### Beispiel: Dokument in Collection mit Sync-ID einfügen (PHP)
|
||||
|
||||
```php
|
||||
$entityManager = $container->get('entityManager');
|
||||
|
||||
// Entities laden
|
||||
$doc = $entityManager->getEntity('CDokumente', $docId);
|
||||
$collection = $entityManager->getEntity('CAICollections', $collectionId);
|
||||
|
||||
// Verknüpfen mit syncId
|
||||
$repo = $entityManager->getRDBRepository('CDokumente');
|
||||
$relation = $repo->getRelation($doc, 'cAICollections');
|
||||
$relation->relateById($collectionId, [
|
||||
'syncId' => 'my-unique-sync-id-123'
|
||||
]);
|
||||
|
||||
// SyncId auslesen
|
||||
$relationData = $relation->getColumnAttributes($collection, ['syncId']);
|
||||
echo $relationData['syncId']; // 'my-unique-sync-id-123'
|
||||
```
|
||||
|
||||
### Beispiel: Dokument in Collection finden via Sync-ID
|
||||
|
||||
```sql
|
||||
SELECT c_dokumente_id, c_a_i_collections_id, sync_id
|
||||
FROM c_a_i_collection_c_dokumente
|
||||
WHERE sync_id = 'my-unique-sync-id-123'
|
||||
AND deleted = 0;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Erstellt:** 9. März 2026
|
||||
**Getestet mit:** EspoCRM (MariaDB 12.2.2, PHP 8.2.30)
|
||||
**API-User für Tests:** marvin (API-Key: e53def10eea27b92a6cd00f40a3e09a4)
|
||||
139
custom/docs/archive/E2E_TEST_RESULTS.md
Normal file
139
custom/docs/archive/E2E_TEST_RESULTS.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# End-to-End Test Ergebnisse
|
||||
|
||||
## Test-Übersicht
|
||||
|
||||
Das E2E-Test-Framework wurde erfolgreich implementiert und getestet!
|
||||
|
||||
## ✅ Erfolgreich getestete Entities
|
||||
|
||||
### CMietobjekt
|
||||
- ✓ Create: Mietobjekt mit Adresse erstellen
|
||||
- ✓ Read: Datensatz abrufen
|
||||
- ✓ Update: Lage-Feld aktualisieren
|
||||
- ✓ Delete: Datensatz löschen
|
||||
|
||||
### CVmhMietverhältnis
|
||||
- ✓ Create: Mietverhältnis mit allen Pflichtfeldern
|
||||
- ✓ Read: Datensatz validieren
|
||||
- ✓ Update: Miete aktualisieren
|
||||
- ✓ Delete: Datensatz löschen
|
||||
- ✓ Relationship: Verknüpfung mit CMietobjekt über `vmhMietobjektId`
|
||||
|
||||
### CBeteiligte
|
||||
- ✓ Create: Person mit Namen und Adresse
|
||||
- ✓ Read: Personendaten abrufen
|
||||
- ✓ Update: Telefonnummer ändern
|
||||
- ✓ Delete: Person löschen
|
||||
|
||||
### CVmhRäumungsklage
|
||||
- ✓ Create: Räumungsklage erstellen
|
||||
- ✓ Read: Datensatz validieren
|
||||
- ✓ Update: Gegenstandswert ändern
|
||||
- ✓ Delete: Datensatz löschen
|
||||
|
||||
## 🔒 Entities mit Permissions-Beschränkung
|
||||
|
||||
### CKündigung
|
||||
- User `dev-test` hat keine Berechtigung (403 Forbidden)
|
||||
- Betrifft: READ, CREATE, UPDATE, DELETE
|
||||
|
||||
### CMietinkasso
|
||||
- User `dev-test` hat keine Berechtigung (403 Forbidden)
|
||||
- Betrifft: READ, CREATE, UPDATE, DELETE
|
||||
|
||||
### Ursache
|
||||
Diese Entities sind durch ACL (Access Control Lists) gesperrt. Mögliche Gründe:
|
||||
1. **Role-Einstellungen**: Der User ist einer Role zugeordnet, die diese Entities nicht erlaubt
|
||||
2. **Team-Beschränkungen**: Entities sind team-spezifisch eingeschränkt
|
||||
3. **Custom ACL-Implementierung**: Möglicherweise gibt es Custom ACL-Klassen
|
||||
|
||||
### Behebung
|
||||
In der EspoCRM Admin-Oberfläche:
|
||||
1. **Administration → Roles** → User's Role auswählen
|
||||
2. Bei `CKündigung` und `CMietinkasso` auf "Enabled" setzen
|
||||
3. Permissions auf "All" oder mindestens "Create: Yes, Read: All, Edit: All, Delete: All" setzen
|
||||
|
||||
Alternativ:
|
||||
- **Administration → Users** → `dev-test` → Role/Teams prüfen
|
||||
- Sicherstellen, dass der User Admin-Rechte hat oder eine Role mit Full Access
|
||||
|
||||
## 📊 Test-Statistik (letzter Lauf)
|
||||
|
||||
```
|
||||
✅ CBeteiligte: 3/3 tests passed (100%)
|
||||
🔒 CKndigung: 0/1 tests (Permission denied)
|
||||
🔒 CMietinkasso: 0/1 tests (Permission denied)
|
||||
✅ CMietobjekt: 3/3 tests passed (100%)
|
||||
✅ CVmhMietverhltnis: 3/3 tests passed (100%)
|
||||
✅ CVmhRumungsklage: 3/3 tests passed (100%)
|
||||
|
||||
Total: 12/14 tests executable
|
||||
2 tests blocked by permissions
|
||||
Time: ~0.2s
|
||||
```
|
||||
|
||||
## 🎯 Framework-Features
|
||||
|
||||
### Implementiert
|
||||
- ✅ CRUD-Tests für alle wichtigen Entities
|
||||
- ✅ Relationship-Tests (belongsTo)
|
||||
- ✅ Automatisches Cleanup (keine Test-Daten bleiben zurück)
|
||||
- ✅ Permission-aware (erkennt 403-Fehler)
|
||||
- ✅ Detailliertes Reporting
|
||||
- ✅ Fehlerbehandlung mit Context
|
||||
- ✅ Zeiterfassung pro Test
|
||||
|
||||
### Bereit für Erweiterung
|
||||
- 📝 Weitere Entities hinzufügen (siehe [E2E_TESTS_README.md](E2E_TESTS_README.md))
|
||||
- 🔗 Mehr Relationship-Tests (hasMany, manyToMany)
|
||||
- ✅ Validierungs-Tests für berechnete Felder
|
||||
- 📧 Workflow-Tests (wenn freigeschaltet)
|
||||
|
||||
## 🚀 Verwendung
|
||||
|
||||
### Standard-Test
|
||||
```bash
|
||||
./run_e2e_tests.sh
|
||||
```
|
||||
|
||||
### Mit Python direkt
|
||||
```bash
|
||||
python3 e2e_tests.py
|
||||
```
|
||||
|
||||
### Einzelne Entity testen
|
||||
```python
|
||||
from e2e_tests import CMietobjektTest
|
||||
from espocrm_api_client import EspoCRMAPIClient
|
||||
from e2e_tests import TestTracker
|
||||
|
||||
client = EspoCRMAPIClient(...)
|
||||
tracker = TestTracker()
|
||||
test = CMietobjektTest(client, tracker)
|
||||
test.run_full_test()
|
||||
```
|
||||
|
||||
## 📁 Dateien
|
||||
|
||||
- `espocrm_api_client.py` - REST API Client
|
||||
- `e2e_tests.py` - Test-Framework mit allen Entity-Tests
|
||||
- `run_e2e_tests.sh` - Shell-Wrapper
|
||||
- `E2E_TESTS_README.md` - Vollständige Dokumentation
|
||||
|
||||
## ✨ Nächste Schritte
|
||||
|
||||
1. **Permissions klären** für CKündigung und CMietinkasso
|
||||
2. **Weitere Entities** hinzufügen:
|
||||
- CAdressen
|
||||
- CBankverbindungen
|
||||
- CDokumente
|
||||
- CVmhErstgespraech
|
||||
3. **hasMany Relationships** testen (benötigt API-Research)
|
||||
4. **CI/CD Integration** (GitHub Actions, GitLab CI)
|
||||
5. **Performance-Tests** mit größeren Datenmengen
|
||||
|
||||
---
|
||||
|
||||
**Status**: ✅ Framework vollständig funktionsfähig
|
||||
**Test Coverage**: 4/6 Custom Entities (66.7%)
|
||||
**Success Rate**: 100% für zugängliche Entities
|
||||
247
custom/docs/archive/KI_OVERVIEW_SUMMARY.md
Normal file
247
custom/docs/archive/KI_OVERVIEW_SUMMARY.md
Normal file
@@ -0,0 +1,247 @@
|
||||
# KI-Einstiegsscript Projekt - Zusammenfassung
|
||||
|
||||
## Erstellte Dateien
|
||||
|
||||
### 1. Haupt-Python-Script
|
||||
**Datei:** `custom/scripts/ki_project_overview.py`
|
||||
|
||||
- Vollständige Projekt-Analyse
|
||||
- 3376+ Zeilen Output
|
||||
- Analysiert automatisch:
|
||||
- ✅ 21 Custom Entities mit Feldern und Beziehungen
|
||||
- ✅ Relationship-Graph
|
||||
- ✅ 1 Custom PHP Klasse
|
||||
- ✅ 1 Workflow
|
||||
- ✅ 10 JavaScript Files
|
||||
- ✅ 2 CSS Files
|
||||
- ✅ 3 Custom Layouts
|
||||
- ✅ 35 Sprachen (i18n)
|
||||
|
||||
### 2. Bash Wrapper-Script
|
||||
**Datei:** `custom/scripts/ki-overview.sh`
|
||||
|
||||
Komfortable Nutzung mit Optionen:
|
||||
```bash
|
||||
./custom/scripts/ki-overview.sh # Vollständige Ausgabe
|
||||
./custom/scripts/ki-overview.sh --stats # Nur Statistiken
|
||||
./custom/scripts/ki-overview.sh --entities # Nur Entitäten
|
||||
./custom/scripts/ki-overview.sh --relations # Nur Beziehungsgraph
|
||||
./custom/scripts/ki-overview.sh --file # In Datei speichern
|
||||
./custom/scripts/ki-overview.sh --help # Hilfe
|
||||
```
|
||||
|
||||
### 3. Dokumentation
|
||||
**Datei:** `custom/scripts/KI_OVERVIEW_README.md`
|
||||
|
||||
Umfassende Dokumentation mit:
|
||||
- Zweck und Verwendung
|
||||
- Ausgabeformat-Beschreibung
|
||||
- Anwendungsfälle
|
||||
- Integration mit validate_and_rebuild.py
|
||||
- Technische Details
|
||||
- Erweiterungsmöglichkeiten
|
||||
- Troubleshooting
|
||||
|
||||
### 4. README.md Update
|
||||
**Datei:** `README.md` (Schnellstart-Sektion hinzugefügt)
|
||||
|
||||
Neuer Abschnitt am Anfang:
|
||||
```markdown
|
||||
## 🚀 Schnellstart für KI
|
||||
|
||||
**NEU:** Automatisches KI-Einstiegsscript für vollständigen Projekt-Überblick!
|
||||
```
|
||||
|
||||
## Verwendung für KI
|
||||
|
||||
### Szenario 1: Neue Programmieraufgabe
|
||||
```bash
|
||||
# KI erhält vollständigen Kontext
|
||||
./custom/scripts/ki-overview.sh > /tmp/overview.txt
|
||||
|
||||
# Output an KI übergeben
|
||||
cat /tmp/overview.txt
|
||||
```
|
||||
|
||||
Die KI erhält:
|
||||
- README.md (vollständig, 2112 Zeilen)
|
||||
- Alle 21 Entities mit Feldern, Typen, Constraints
|
||||
- Alle Beziehungen (hasMany, belongsTo, etc.)
|
||||
- Custom PHP Klassen
|
||||
- Workflows (Status, Aktionen)
|
||||
- Frontend-Code (JS, CSS)
|
||||
- i18n Sprachen
|
||||
|
||||
### Szenario 2: Schneller Überblick
|
||||
```bash
|
||||
# Nur Statistiken
|
||||
./custom/scripts/ki-overview.sh --stats
|
||||
```
|
||||
|
||||
Zeigt:
|
||||
```
|
||||
📊 Projekt-Statistiken:
|
||||
• Entities 21
|
||||
• PHP Classes 1
|
||||
• Workflows 1
|
||||
• JavaScript Files 10
|
||||
• CSS Files 2
|
||||
• Custom Layouts 3
|
||||
• Languages 35
|
||||
```
|
||||
|
||||
### Szenario 3: Beziehungen verstehen
|
||||
```bash
|
||||
# Nur Beziehungsgraph
|
||||
./custom/scripts/ki-overview.sh --relations
|
||||
```
|
||||
|
||||
Zeigt alle Entity-Beziehungen:
|
||||
```
|
||||
CMietobjekt:
|
||||
⇄ mietverhltnisse [hasMany] → CVmhMietverhltnis
|
||||
⇄ kontakte [hasMany] → Contact
|
||||
→ vermieter [belongsTo] → CVmhVermieter
|
||||
...
|
||||
```
|
||||
|
||||
## Vorteile
|
||||
|
||||
### Für KI
|
||||
1. **Vollständiger Kontext:** Keine manuellen Dateiabfragen nötig
|
||||
2. **Aktuell:** Immer auf dem neuesten Stand
|
||||
3. **Strukturiert:** Klare Sektionen, leicht zu parsen
|
||||
4. **Umfassend:** README + automatische Analyse
|
||||
|
||||
### Für Entwickler
|
||||
1. **Zeitersparnis:** Keine manuelle Dokumentation
|
||||
2. **Übersichtlich:** Alle Infos an einem Ort
|
||||
3. **Wartbar:** Automatisch generiert, immer korrekt
|
||||
4. **Flexibel:** Verschiedene Output-Optionen
|
||||
|
||||
## Integration in Workflow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ 1. KI-Einstiegsscript ausführen │
|
||||
│ ./custom/scripts/ki-overview.sh │
|
||||
└───────────────┬─────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────┐
|
||||
│ 2. KI erhält Projekt-Kontext │
|
||||
│ - README.md │
|
||||
│ - Entities & Felder │
|
||||
│ - Beziehungen │
|
||||
│ - Custom Code │
|
||||
└───────────────┬─────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────┐
|
||||
│ 3. KI macht Änderungen │
|
||||
│ - Erstellt/bearbeitet JSON │
|
||||
│ - Fügt Felder hinzu │
|
||||
│ - Definiert Beziehungen │
|
||||
└───────────────┬─────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────┐
|
||||
│ 4. Validierung & Rebuild │
|
||||
│ ./custom/scripts/ │
|
||||
│ validate_and_rebuild.py │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Technische Details
|
||||
|
||||
### Performance
|
||||
- Analysiert 21 Entities in < 1 Sekunde
|
||||
- 3376 Zeilen Output
|
||||
- Effiziente JSON-Parsing mit Error-Handling
|
||||
|
||||
### Robustheit
|
||||
- Fehlerhafte JSON-Dateien werden übersprungen
|
||||
- Fehlende Verzeichnisse = Info, kein Abbruch
|
||||
- Umfangreiche Exception-Behandlung
|
||||
|
||||
### Erweiterbarkeit
|
||||
Neue Analysen können einfach hinzugefügt werden:
|
||||
|
||||
```python
|
||||
def analyze_new_feature():
|
||||
"""Analysiert neues Feature."""
|
||||
print_section("NEUES FEATURE", "=")
|
||||
# Implementierung
|
||||
...
|
||||
|
||||
# In main() aufrufen
|
||||
def main():
|
||||
...
|
||||
analyze_new_feature()
|
||||
```
|
||||
|
||||
## Ausgabe-Beispiel (Auszug)
|
||||
|
||||
```
|
||||
================================================================================
|
||||
ENTITÄTEN ANALYSE
|
||||
================================================================================
|
||||
|
||||
────────────────────────────────────────────────────────────────────────────────
|
||||
► Entität: CMietobjekt
|
||||
────────────────────────────────────────────────────────────────────────────────
|
||||
|
||||
📋 Scope:
|
||||
• entity: CMietobjekt
|
||||
• acl: True
|
||||
• stream: False
|
||||
• type: BasePlus
|
||||
• customizable: True
|
||||
|
||||
🔧 Felder (15):
|
||||
• name: varchar [REQUIRED] [CUSTOM]
|
||||
• adresse: link → CAdressen
|
||||
• miete: currency (€)
|
||||
• kaution: currency (€)
|
||||
• flaeche: float
|
||||
• zimmer: int
|
||||
• etage: varchar
|
||||
• lage: enum (options: 5)
|
||||
...
|
||||
|
||||
🔗 Beziehungen (8):
|
||||
• mietverhltnisse [hasMany] → CVmhMietverhltnis.mietobjekt (relationName: cMietobjektCVmhMietverhltnis)
|
||||
• kontakte [hasMany] → Contact.mietobjekte (relationName: cMietobjektContact)
|
||||
• vermieter [belongsTo] → CVmhVermieter.mietobjekte
|
||||
...
|
||||
```
|
||||
|
||||
## Nächste Schritte
|
||||
|
||||
### Für KI-Integration
|
||||
1. ✅ Script erstellt und getestet
|
||||
2. ✅ Dokumentation vollständig
|
||||
3. ✅ README.md aktualisiert
|
||||
4. ⏭️ In KI-Workflow integrieren
|
||||
5. ⏭️ Feedback sammeln und optimieren
|
||||
|
||||
### Mögliche Erweiterungen
|
||||
- [ ] JSON-Output für maschinelle Verarbeitung
|
||||
- [ ] Markdown-Output für Dokumentation
|
||||
- [ ] HTML-Output für Browser
|
||||
- [ ] Filter-Optionen (z.B. nur bestimmte Entities)
|
||||
- [ ] Diff-Modus (Änderungen seit letztem Lauf)
|
||||
- [ ] Integration mit Git (zeige geänderte Entities)
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- `custom/scripts/validate_and_rebuild.py` - Validierung & Rebuild
|
||||
- `custom/scripts/VALIDATOR_README.md` - Validator-Dokumentation
|
||||
- `custom/CUSTOM_DIRECTORY.md` - Custom Directory Struktur
|
||||
- `README.md` - Haupt-Projektdokumentation
|
||||
|
||||
---
|
||||
|
||||
**Erstellt:** 25. Januar 2026
|
||||
**Status:** ✅ Produktionsbereit
|
||||
**Version:** 1.0
|
||||
224
custom/docs/tools/E2E_TESTS_README.md
Normal file
224
custom/docs/tools/E2E_TESTS_README.md
Normal file
@@ -0,0 +1,224 @@
|
||||
# EspoCRM E2E Test Suite
|
||||
|
||||
Automatisierte End-to-End Tests für Custom EspoCRM Entities.
|
||||
|
||||
## Überblick
|
||||
|
||||
Das Test-Framework führt automatisiert folgende Tests durch:
|
||||
|
||||
### ✅ CRUD-Operationen
|
||||
- **Create**: Erstellen von Testdatensätzen für alle Custom Entities
|
||||
- **Read**: Validierung der erstellten Datensätze
|
||||
- **Update**: Änderung von Feldern
|
||||
- **Delete**: Löschen der Test-Daten
|
||||
|
||||
### 🔗 Relationship-Tests
|
||||
- **Link**: Verknüpfung von Entities über Relationships
|
||||
- **Unlink**: Entfernung von Verknüpfungen
|
||||
- **Verification**: Prüfung der korrekten Verknüpfung
|
||||
|
||||
## Getestete Entities
|
||||
|
||||
1. **CMietobjekt** - Mietobjekte (Wohnungen, Häuser, etc.)
|
||||
2. **CVmhMietverhältnis** - Mietverhältnisse
|
||||
3. **CKündigung** - Kündigungen
|
||||
4. **CBeteiligte** - Beteiligte Personen (Mieter, Vermieter)
|
||||
5. **CMietinkasso** - Mietinkasso-Verfahren
|
||||
6. **CVmhRäumungsklage** - Räumungsklagen
|
||||
|
||||
## Getestete Relationships
|
||||
|
||||
- CVmhMietverhältnis ↔ CMietobjekt
|
||||
- CKündigung ↔ CVmhMietverhältnis
|
||||
- CBeteiligte ↔ CVmhMietverhältnis (als Mieter/Vermieter)
|
||||
|
||||
## Installation
|
||||
|
||||
### Voraussetzungen
|
||||
|
||||
- Python 3.6+
|
||||
- `requests` Bibliothek
|
||||
|
||||
```bash
|
||||
pip3 install requests
|
||||
```
|
||||
|
||||
## Verwendung
|
||||
|
||||
### Schnellstart
|
||||
|
||||
```bash
|
||||
./run_e2e_tests.sh
|
||||
```
|
||||
|
||||
### Direkte Python-Ausführung
|
||||
|
||||
```bash
|
||||
python3 e2e_tests.py
|
||||
```
|
||||
|
||||
## Konfiguration
|
||||
|
||||
Die Konfiguration erfolgt in [e2e_tests.py](e2e_tests.py#L20-L25):
|
||||
|
||||
```python
|
||||
CONFIG = {
|
||||
'base_url': 'https://crm.bitbylaw.com',
|
||||
'api_key': '2b0747ca34d15032aa233ae043cc61bc',
|
||||
'username': 'dev-test'
|
||||
}
|
||||
```
|
||||
|
||||
## Ausgabe
|
||||
|
||||
Das Framework generiert eine detaillierte Testübersicht:
|
||||
|
||||
```
|
||||
================================================================================
|
||||
TEST SUMMARY
|
||||
================================================================================
|
||||
|
||||
✅ CMietobjekt: 4/4 tests passed
|
||||
✓ create 0.234s
|
||||
✓ read 0.123s
|
||||
✓ update 0.156s
|
||||
✓ delete 0.089s
|
||||
|
||||
✅ CVmhMietverhltnis: 4/4 tests passed
|
||||
✓ create 0.267s
|
||||
✓ read 0.134s
|
||||
✓ update 0.178s
|
||||
✓ delete 0.092s
|
||||
|
||||
================================================================================
|
||||
Total: 24/24 tests passed (0 failed)
|
||||
Time: 3.45s
|
||||
================================================================================
|
||||
```
|
||||
|
||||
## Architektur
|
||||
|
||||
### Komponenten
|
||||
|
||||
#### 1. **espocrm_api_client.py**
|
||||
API-Client für EspoCRM REST API mit folgenden Features:
|
||||
- CRUD-Operationen (Create, Read, Update, Delete)
|
||||
- Relationship-Management (Link, Unlink)
|
||||
- Fehlerbehandlung und Logging
|
||||
|
||||
#### 2. **e2e_tests.py**
|
||||
Haupttest-Framework mit:
|
||||
- `EntityTestBase`: Basis-Klasse für Entity-Tests
|
||||
- Spezifische Test-Klassen für jede Entity
|
||||
- `TestTracker`: Ergebnis-Tracking und Reporting
|
||||
- Automatisches Cleanup
|
||||
|
||||
#### 3. **run_e2e_tests.sh**
|
||||
Shell-Wrapper mit:
|
||||
- Dependency-Checks
|
||||
- Farbiger Ausgabe
|
||||
- Exit-Code-Handling
|
||||
|
||||
## Erweiterung
|
||||
|
||||
### Neue Entity hinzufügen
|
||||
|
||||
1. Neue Test-Klasse erstellen:
|
||||
|
||||
```python
|
||||
class CMyEntityTest(EntityTestBase):
|
||||
def __init__(self, client: EspoCRMAPIClient, tracker: TestTracker):
|
||||
super().__init__(client, tracker)
|
||||
self.entity_type = 'CMyEntity'
|
||||
|
||||
def run_full_test(self) -> Optional[str]:
|
||||
# Create
|
||||
data = {
|
||||
'name': f'Test Entity {datetime.now().strftime("%Y%m%d_%H%M%S")}',
|
||||
# ... weitere Felder
|
||||
}
|
||||
|
||||
record_id = self.test_create(data)
|
||||
if not record_id:
|
||||
return None
|
||||
|
||||
# Read
|
||||
self.test_read(record_id)
|
||||
|
||||
# Update
|
||||
self.test_update(record_id, {'field': 'new_value'})
|
||||
|
||||
return record_id
|
||||
```
|
||||
|
||||
2. Test in `run_all_tests()` einbinden:
|
||||
|
||||
```python
|
||||
print("\n🔷 Testing CMyEntity...")
|
||||
myentity_test = CMyEntityTest(client, tracker)
|
||||
myentity_id = myentity_test.run_full_test()
|
||||
```
|
||||
|
||||
3. Cleanup-Order anpassen falls Dependencies bestehen
|
||||
|
||||
### Neue Relationships testen
|
||||
|
||||
```python
|
||||
# Link testen
|
||||
entity_test.test_link(
|
||||
record_id='123',
|
||||
link_name='relationshipName',
|
||||
foreign_id='456'
|
||||
)
|
||||
|
||||
# Unlink testen
|
||||
entity_test.test_unlink(
|
||||
record_id='123',
|
||||
link_name='relationshipName',
|
||||
foreign_id='456'
|
||||
)
|
||||
```
|
||||
|
||||
## Fehlerbehebung
|
||||
|
||||
### Connection Fehler
|
||||
|
||||
```
|
||||
❌ Connection failed: HTTPError 401
|
||||
```
|
||||
→ API-Key oder Username prüfen
|
||||
|
||||
### Entity nicht gefunden
|
||||
|
||||
```
|
||||
❌ API Error: POST https://crm.bitbylaw.com/api/v1/CMyEntity
|
||||
Status: 404
|
||||
```
|
||||
→ Entity-Name prüfen (z.B. `CKndigung` statt `CKuendigung`)
|
||||
|
||||
### Relationship nicht gefunden
|
||||
|
||||
```
|
||||
AssertionError: Link not found: xyz123
|
||||
```
|
||||
→ Relationship-Name und Richtung prüfen
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Immer cleanup durchführen**: Tests hinterlassen keine Datenreste
|
||||
2. **Eindeutige Namen**: Timestamps in Test-Daten-Namen
|
||||
3. **Dependencies beachten**: Lösch-Reihenfolge ist wichtig
|
||||
4. **Fehlerbehandlung**: Jeder Test ist isoliert
|
||||
|
||||
## Weitere Informationen
|
||||
|
||||
- [EspoCRM REST API Dokumentation](https://docs.espocrm.com/development/api/)
|
||||
- [Projektübersicht](KI_OVERVIEW_README.md)
|
||||
- [Validierungs-Tools](VALIDATION_TOOLS.md)
|
||||
|
||||
## Support
|
||||
|
||||
Bei Fragen oder Problemen:
|
||||
1. Logs prüfen: Test-Ausgabe enthält detaillierte Fehlermeldungen
|
||||
2. API-Dokumentation konsultieren
|
||||
3. Entity-Definitionen in `custom/Espo/Custom/Resources/metadata/entityDefs/` prüfen
|
||||
334
custom/docs/tools/KI_OVERVIEW_README.md
Normal file
334
custom/docs/tools/KI_OVERVIEW_README.md
Normal file
@@ -0,0 +1,334 @@
|
||||
# KI-Einstiegsscript für EspoCRM Projekt
|
||||
|
||||
## Übersicht
|
||||
|
||||
Das `ki_project_overview.py` Script bietet einen vollständigen, automatisch generierten Überblick über das EspoCRM-Projekt. Es ist speziell für KI-basierte Programmierung konzipiert und gibt alle relevanten Informationen aus, die für die Entwicklung benötigt werden.
|
||||
|
||||
## Zweck
|
||||
|
||||
**Ziel:** Die KI erhält einen aktuellen, umfassenden Informationsstand über das Projekt, ohne manuell verschiedene Dateien durchsuchen zu müssen.
|
||||
|
||||
Das Script analysiert automatisch:
|
||||
- ✅ Alle Custom Entitäten und ihre Felder
|
||||
- ✅ Beziehungen zwischen Entitäten (Relationship-Graph)
|
||||
- ✅ Custom PHP Klassen (Formula-Funktionen, Services, etc.)
|
||||
- ✅ Workflows und deren Status
|
||||
- ✅ Frontend-Anpassungen (JavaScript, CSS)
|
||||
- ✅ Custom Layouts
|
||||
- ✅ Internationalisierung (i18n)
|
||||
- ✅ README.md Dokumentation
|
||||
|
||||
## Verwendung
|
||||
|
||||
### Einfach ausführen
|
||||
|
||||
```bash
|
||||
# Im EspoCRM Root-Verzeichnis
|
||||
python3 custom/scripts/ki_project_overview.py
|
||||
```
|
||||
|
||||
### Ausgabe in Datei speichern
|
||||
|
||||
```bash
|
||||
# Für detaillierte Analyse später
|
||||
python3 custom/scripts/ki_project_overview.py > /tmp/project-overview.txt
|
||||
```
|
||||
|
||||
### Ausgabe an KI übergeben
|
||||
|
||||
Das Script ist so konzipiert, dass die Ausgabe direkt an eine KI übergeben werden kann. Die KI erhält damit:
|
||||
|
||||
1. **Schnellübersicht** - Projekt-Statistiken auf einen Blick
|
||||
2. **README.md** - Vollständige Projektdokumentation
|
||||
3. **Entitäten-Analyse** - Alle Custom Entities mit Feldern und Beziehungen
|
||||
4. **Beziehungsgraph** - Wie Entitäten miteinander verbunden sind
|
||||
5. **Custom Code** - PHP Klassen, JavaScript, CSS
|
||||
6. **Workflows** - Aktive und inaktive Workflows
|
||||
7. **Internationalisierung** - Unterstützte Sprachen
|
||||
|
||||
## Ausgabeformat
|
||||
|
||||
Das Script gibt strukturierte, lesbare Ausgaben mit verschiedenen Abschnitten:
|
||||
|
||||
```
|
||||
================================================================================
|
||||
SCHNELLÜBERSICHT
|
||||
================================================================================
|
||||
|
||||
📊 Projekt-Statistiken:
|
||||
|
||||
• Entities 21
|
||||
• PHP Classes 1
|
||||
• Workflows 1
|
||||
• JavaScript Files 10
|
||||
...
|
||||
|
||||
================================================================================
|
||||
ENTITÄTEN ANALYSE
|
||||
================================================================================
|
||||
|
||||
────────────────────────────────────────────────────────────────────────────────
|
||||
► Entität: CMietobjekt
|
||||
────────────────────────────────────────────────────────────────────────────────
|
||||
|
||||
📋 Scope:
|
||||
• entity: CMietobjekt
|
||||
• acl: True
|
||||
• stream: False
|
||||
...
|
||||
|
||||
🔧 Felder (15):
|
||||
• name: varchar [REQUIRED] [CUSTOM]
|
||||
• adresse: link → CAdressen
|
||||
• miete: currency (€)
|
||||
...
|
||||
|
||||
🔗 Beziehungen (8):
|
||||
• mietverhltnisse [hasMany] → CVmhMietverhltnis.mietobjekt
|
||||
• kontakte [hasMany] → Contact.mietobjekte
|
||||
...
|
||||
|
||||
⚡ Formula Scripts:
|
||||
• beforeSaveApiScript: 25 Zeilen
|
||||
```
|
||||
|
||||
## Was wird analysiert?
|
||||
|
||||
### 1. Entitäten (entityDefs)
|
||||
|
||||
Für jede Custom Entity:
|
||||
- Alle Felder mit Typ, Optionen, Constraints
|
||||
- Alle Beziehungen (Links) zu anderen Entities
|
||||
- Formula Scripts (beforeSave, afterSave, etc.)
|
||||
- Scope-Konfiguration (ACL, Stream, Portal-Access)
|
||||
|
||||
### 2. Beziehungsgraph
|
||||
|
||||
Visualisiert alle Beziehungen zwischen Entities:
|
||||
- hasMany, belongsTo, hasOne, manyToMany
|
||||
- Bidirektionale Links mit relationName
|
||||
- Foreign Keys
|
||||
|
||||
### 3. Custom PHP Klassen
|
||||
|
||||
Alle PHP-Dateien in `custom/Espo/Custom/Classes/`:
|
||||
- FormulaFunctions
|
||||
- Services
|
||||
- Controllers
|
||||
- Hooks
|
||||
- Etc.
|
||||
|
||||
### 4. Workflows
|
||||
|
||||
Alle Workflows in `custom/workflows/`:
|
||||
- Name und Status (aktiv/inaktiv)
|
||||
- Trigger-Typ
|
||||
- Entity-Zuordnung
|
||||
- Anzahl der Aktionen
|
||||
|
||||
### 5. Frontend
|
||||
|
||||
- **JavaScript:** Alle Custom Views und Module
|
||||
- **CSS:** Registrierte Stylesheets
|
||||
- **App Config:** cssList, scriptList aus client.json
|
||||
|
||||
### 6. Layouts
|
||||
|
||||
Custom Layouts für jede Entity:
|
||||
- detail, list, detailSmall, listSmall
|
||||
- bottomPanelsDetail, sidePanelsDetail
|
||||
- Etc.
|
||||
|
||||
### 7. Internationalisierung
|
||||
|
||||
- Unterstützte Sprachen
|
||||
- Anzahl Übersetzungsdateien pro Sprache
|
||||
- Geschätzte Anzahl Labels
|
||||
|
||||
## Typische Anwendungsfälle
|
||||
|
||||
### Fall 1: Neue Programmieraufgabe
|
||||
```bash
|
||||
# KI erhält vollständigen Projekt-Kontext
|
||||
python3 custom/scripts/ki_project_overview.py
|
||||
```
|
||||
|
||||
Die KI kann dann direkt auf Basis der Ausgabe arbeiten, ohne weitere Dateien lesen zu müssen.
|
||||
|
||||
### Fall 2: Beziehungen verstehen
|
||||
Das Script zeigt automatisch alle Beziehungen zwischen Entities und hilft, Abhängigkeiten zu verstehen.
|
||||
|
||||
### Fall 3: Vollständigkeitsprüfung
|
||||
Schnell erkennen, ob alle erwarteten Entities, Felder und Beziehungen vorhanden sind.
|
||||
|
||||
## Integration mit validate_and_rebuild.py
|
||||
|
||||
Das KI-Einstiegsscript ist als Ergänzung zum `validate_and_rebuild.py` Script konzipiert:
|
||||
|
||||
1. **ki_project_overview.py** → Informationen sammeln, Kontext für KI bereitstellen
|
||||
2. **validate_and_rebuild.py** → Änderungen validieren und anwenden
|
||||
|
||||
### Typischer Workflow
|
||||
|
||||
```bash
|
||||
# 1. Projekt-Übersicht für KI
|
||||
python3 custom/scripts/ki_project_overview.py
|
||||
|
||||
# 2. KI macht Änderungen an JSON-Dateien
|
||||
# (Basierend auf der Übersicht)
|
||||
|
||||
# 3. Validieren und Rebuild
|
||||
python3 custom/scripts/validate_and_rebuild.py
|
||||
```
|
||||
|
||||
## Technische Details
|
||||
|
||||
### Dateisystem-Struktur
|
||||
|
||||
Das Script erwartet folgende Struktur:
|
||||
```
|
||||
/var/lib/docker/volumes/vmh-espocrm_espocrm/_data/
|
||||
├── README.md
|
||||
├── custom/
|
||||
│ ├── Espo/
|
||||
│ │ └── Custom/
|
||||
│ │ ├── Classes/
|
||||
│ │ └── Resources/
|
||||
│ │ ├── metadata/
|
||||
│ │ │ ├── entityDefs/
|
||||
│ │ │ ├── scopes/
|
||||
│ │ │ ├── formula/
|
||||
│ │ │ ├── layouts/
|
||||
│ │ │ └── ...
|
||||
│ │ └── i18n/
|
||||
│ ├── scripts/
|
||||
│ └── workflows/
|
||||
└── client/
|
||||
└── custom/
|
||||
├── src/
|
||||
└── css/
|
||||
```
|
||||
|
||||
### Performance
|
||||
|
||||
- Analysiert ~20 Entities in <1 Sekunde
|
||||
- JSON-Parsing mit Error-Handling
|
||||
- Effiziente Rekursion durch Dateisystem
|
||||
|
||||
### Error-Handling
|
||||
|
||||
- Fehlerhafte JSON-Dateien werden übersprungen mit Fehlermeldung
|
||||
- Fehlende Verzeichnisse führen zu Info-Meldungen, nicht zu Abbruch
|
||||
- Robuste Exception-Behandlung
|
||||
|
||||
## Ausgabe-Sektionen im Detail
|
||||
|
||||
### 1. SCHNELLÜBERSICHT
|
||||
Kompakte Statistiken für schnellen Überblick
|
||||
|
||||
### 2. README.md
|
||||
Vollständiger Inhalt der Projektdokumentation
|
||||
|
||||
### 3. ENTITÄTEN ANALYSE
|
||||
Detaillierte Analyse jeder Custom Entity:
|
||||
- Scope (ACL, Stream, Portal, etc.)
|
||||
- Felder (Typ, Constraints, Optionen)
|
||||
- Beziehungen (Links zu anderen Entities)
|
||||
- Formula Scripts
|
||||
|
||||
### 4. BEZIEHUNGSGRAPH
|
||||
Visualisierung aller Entity-Beziehungen
|
||||
|
||||
### 5. CUSTOM LAYOUTS
|
||||
Übersicht über angepasste Layouts
|
||||
|
||||
### 6. CUSTOM PHP KLASSEN
|
||||
Alle PHP-Dateien gruppiert nach Typ
|
||||
|
||||
### 7. WORKFLOWS
|
||||
Status und Konfiguration aller Workflows
|
||||
|
||||
### 8. FRONTEND ANPASSUNGEN
|
||||
JavaScript, CSS und App-Konfiguration
|
||||
|
||||
### 9. INTERNATIONALISIERUNG
|
||||
Unterstützte Sprachen und Labels
|
||||
|
||||
## Erweiterungen
|
||||
|
||||
Das Script kann leicht erweitert werden:
|
||||
|
||||
### Neue Analyse-Funktion hinzufügen
|
||||
|
||||
```python
|
||||
def analyze_new_feature():
|
||||
"""Analysiert neues Feature."""
|
||||
print_section("NEUES FEATURE", "=")
|
||||
|
||||
# Implementierung
|
||||
...
|
||||
|
||||
# In main() Funktion aufrufen
|
||||
def main():
|
||||
...
|
||||
analyze_new_feature()
|
||||
...
|
||||
```
|
||||
|
||||
### Ausgabeformat ändern
|
||||
|
||||
Die Ausgabe kann angepasst werden:
|
||||
- JSON-Format für maschinelle Verarbeitung
|
||||
- Markdown für Dokumentation
|
||||
- HTML für Browser-Darstellung
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Für KI-Integration
|
||||
|
||||
1. **Vollständige Ausgabe verwenden:** Nicht abschneiden, KI braucht alle Details
|
||||
2. **Regelmäßig aktualisieren:** Bei Projekt-Änderungen erneut ausführen
|
||||
3. **Mit README.md kombinieren:** Script gibt automatisch README aus
|
||||
|
||||
### Für Menschen
|
||||
|
||||
1. **Ausgabe in Datei speichern:** Für spätere Referenz
|
||||
2. **Abschnitte einzeln betrachten:** Ausgabe ist strukturiert und scrollbar
|
||||
3. **Mit grep filtern:** `python3 ... | grep "Entity:"`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Problem: Script findet keine Entities
|
||||
|
||||
**Lösung:** Prüfe, ob `BASE_PATH` korrekt gesetzt ist:
|
||||
```python
|
||||
BASE_PATH = Path("/var/lib/docker/volumes/vmh-espocrm_espocrm/_data")
|
||||
```
|
||||
|
||||
### Problem: JSON Parse-Fehler
|
||||
|
||||
**Lösung:** Script gibt Fehler aus, aber läuft weiter. Prüfe betroffene Datei mit:
|
||||
```bash
|
||||
python3 -m json.tool < file.json
|
||||
```
|
||||
|
||||
### Problem: Keine README.md Ausgabe
|
||||
|
||||
**Lösung:** Prüfe ob `README.md` im Root-Verzeichnis existiert
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- `/custom/CUSTOM_DIRECTORY.md` - Detaillierte Verzeichnisstruktur
|
||||
- `custom/scripts/validate_and_rebuild.py` - Validierung und Rebuild
|
||||
- `custom/scripts/VALIDATOR_README.md` - Validator-Dokumentation
|
||||
- `README.md` - Hauptdokumentation
|
||||
|
||||
## Lizenz
|
||||
|
||||
Teil des EspoCRM Custom Directory, gleiches Lizenzmodell wie Hauptprojekt.
|
||||
|
||||
---
|
||||
|
||||
**Erstellt:** Januar 2026
|
||||
**Autor:** Automatische KI-Integration
|
||||
**Version:** 1.0
|
||||
120
custom/docs/tools/QUICKSTART.md
Normal file
120
custom/docs/tools/QUICKSTART.md
Normal file
@@ -0,0 +1,120 @@
|
||||
# 🚀 EspoCRM Validator - Quick Start
|
||||
|
||||
## Installation bereits abgeschlossen ✅
|
||||
|
||||
Das Validierungs-Tool ist bereits installiert und einsatzbereit!
|
||||
|
||||
## Verwendung
|
||||
|
||||
```bash
|
||||
# Im EspoCRM-Root-Verzeichnis
|
||||
python3 custom/scripts/validate_and_rebuild.py
|
||||
```
|
||||
|
||||
Das war's! Das Script führt automatisch alle Checks durch und startet den Rebuild.
|
||||
|
||||
**Tipp:** Für nur Validierung ohne Rebuild: `python3 custom/scripts/validate_and_rebuild.py --dry-run`
|
||||
|
||||
## Was wird geprüft?
|
||||
|
||||
1. ✅ **JSON-Syntax** - Alle Custom-Dateien
|
||||
2. ✅ **Relationships** - Bidirektionale Link-Konsistenz
|
||||
3. ✅ **Formula-Scripts** - Korrekte Platzierung
|
||||
4. ✅ **i18n** - Vollständigkeit der Übersetzungen
|
||||
5. ✅ **Layouts** - Struktur-Validierung
|
||||
6. ✅ **Dateirechte** - Owner & Permissions
|
||||
7. ✅ **Rebuild** - Nur bei Fehlerfreiheit
|
||||
|
||||
## Output verstehen
|
||||
|
||||
| Symbol | Bedeutung | Aktion |
|
||||
|--------|-----------|--------|
|
||||
| ✓ Grün | OK | Keine |
|
||||
| ⚠ Gelb | Warnung | Optional beheben |
|
||||
| ✗ Rot | Fehler | **Muss behoben werden!** |
|
||||
|
||||
## Beispiel
|
||||
|
||||
```bash
|
||||
$ python3 custom/scripts/validate_and_rebuild.py
|
||||
|
||||
EspoCRM Custom Entity Validator & Rebuild Tool
|
||||
Arbeitsverzeichnis: /var/lib/docker/volumes/vmh-espocrm_espocrm/_data
|
||||
|
||||
======================================================================
|
||||
1. JSON-SYNTAX VALIDIERUNG
|
||||
======================================================================
|
||||
|
||||
✓ Alle 547 JSON-Dateien sind syntaktisch korrekt
|
||||
|
||||
======================================================================
|
||||
2. RELATIONSHIP-KONSISTENZ
|
||||
======================================================================
|
||||
|
||||
✗ 4 Relationship-Fehler gefunden:
|
||||
• CMietobjekt.vmhRumungsklages → CVmhRumungsklage:
|
||||
Foreign link 'mietobjekte' fehlt in CVmhRumungsklage
|
||||
...
|
||||
|
||||
✗ REBUILD ABGEBROCHEN: Kritische Fehler müssen behoben werden!
|
||||
```
|
||||
|
||||
## Häufige Fehler beheben
|
||||
|
||||
### Relationship-Fehler
|
||||
```json
|
||||
// In CVmhRumungsklage.json HINZUFÜGEN:
|
||||
{
|
||||
"links": {
|
||||
"mietobjekte": {
|
||||
"type": "hasMany",
|
||||
"entity": "CMietobjekt",
|
||||
"foreign": "vmhRumungsklages"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### JSON-Syntax-Fehler
|
||||
- Mit einem JSON-Validator prüfen (z.B. `python3 -m json.tool datei.json`)
|
||||
- Auf fehlende Kommata, geschweifte Klammern achten
|
||||
|
||||
### i18n-Warnung (optional)
|
||||
```json
|
||||
// In i18n/de_DE/Entity.json ERGÄNZEN:
|
||||
{
|
||||
"links": {
|
||||
"meinLink": "Mein Link"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Mehr Infos
|
||||
|
||||
- **Ausführliche Doku:** `custom/scripts/VALIDATOR_README.md`
|
||||
- **EspoCRM-Doku:** `README.md`
|
||||
- **Custom-Struktur:** `custom/CUSTOM_DIRECTORY.md`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Python3 nicht gefunden?**
|
||||
```bash
|
||||
sudo apt-get install python3 # Ubuntu/Debian
|
||||
sudo yum install python3 # CentOS/RHEL
|
||||
```
|
||||
|
||||
**Keine Berechtigung?**
|
||||
```bash
|
||||
chmod +x custom/scripts/validate_and_rebuild.py
|
||||
```
|
||||
|
||||
**Script findet rebuild.php nicht?**
|
||||
```bash
|
||||
# Ins richtige Verzeichnis wechseln
|
||||
cd /var/lib/docker/volumes/vmh-espocrm_espocrm/_data
|
||||
python3 custom/scripts/validate_and_rebuild.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**💡 Tipp:** Führe das Script nach **jeder** Änderung an Custom-Dateien aus!
|
||||
292
custom/docs/tools/VALIDATION_TOOLS.md
Normal file
292
custom/docs/tools/VALIDATION_TOOLS.md
Normal file
@@ -0,0 +1,292 @@
|
||||
# Validierungstools für EspoCRM Custom-Entwicklung
|
||||
|
||||
## Installierte Tools
|
||||
|
||||
### 1. PHP-CLI (v8.2.29)
|
||||
**Zweck:** Validierung von PHP-Syntax
|
||||
|
||||
**Installation:**
|
||||
```bash
|
||||
sudo apt install -y php-cli
|
||||
```
|
||||
|
||||
**Verwendung im Script:**
|
||||
```bash
|
||||
php -l /pfad/zur/datei.php
|
||||
```
|
||||
|
||||
**Validiert:**
|
||||
- PHP-Syntax-Fehler
|
||||
- Parse-Fehler
|
||||
- Fehlende Klammern/Semikolons
|
||||
- Ungültige Funktionsdeklarationen
|
||||
|
||||
---
|
||||
|
||||
### 2. CSSLint (v1.0.4)
|
||||
**Zweck:** CSS-Validierung und Best-Practice-Checks
|
||||
|
||||
**Installation:**
|
||||
```bash
|
||||
sudo apt install -y nodejs npm
|
||||
sudo npm install -g csslint
|
||||
```
|
||||
|
||||
**Verwendung im Script:**
|
||||
```bash
|
||||
csslint --format=compact --quiet /pfad/zur/datei.css
|
||||
```
|
||||
|
||||
**Validiert:**
|
||||
- CSS-Syntax-Fehler
|
||||
- Ungültige Properties
|
||||
- Vendor-Prefix-Probleme
|
||||
- Performance-Probleme
|
||||
- Kompatibilitätsprobleme
|
||||
|
||||
**Konfiguration:**
|
||||
Das Script verwendet standardmäßig alle csslint-Regeln. Für custom Rules kann eine `.csslintrc` Datei erstellt werden.
|
||||
|
||||
---
|
||||
|
||||
### 3. JSHint (v2.13.6)
|
||||
**Zweck:** JavaScript-Code-Qualität und Syntax-Validierung
|
||||
|
||||
**Installation:**
|
||||
```bash
|
||||
sudo npm install -g jshint
|
||||
```
|
||||
|
||||
**Verwendung im Script:**
|
||||
```bash
|
||||
jshint --config=/dev/null /pfad/zur/datei.js
|
||||
```
|
||||
|
||||
**Validiert:**
|
||||
- JavaScript-Syntax-Fehler
|
||||
- Potenzielle Bugs
|
||||
- Code-Style-Probleme
|
||||
- Ungültige Variablen-Deklarationen
|
||||
- Scope-Probleme
|
||||
|
||||
**Konfiguration:**
|
||||
Aktuell nutzt das Script minimale Konfiguration. Für erweiterte Checks kann eine `.jshintrc` Datei erstellt werden:
|
||||
|
||||
```json
|
||||
{
|
||||
"esversion": 6,
|
||||
"browser": true,
|
||||
"jquery": true,
|
||||
"unused": true,
|
||||
"undef": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration im Validierungsscript
|
||||
|
||||
Das Script `custom/scripts/validate_and_rebuild.py` nutzt diese Tools automatisch:
|
||||
|
||||
### Automatische Erkennung
|
||||
```python
|
||||
# Prüft ob Tool verfügbar ist
|
||||
try:
|
||||
subprocess.run(['csslint', '--version'], capture_output=True)
|
||||
use_csslint = True
|
||||
except FileNotFoundError:
|
||||
use_csslint = False
|
||||
# Fallback auf Basis-Validierung
|
||||
```
|
||||
|
||||
### Fallback-Mechanismus
|
||||
Falls ein Tool nicht verfügbar ist, verwendet das Script eine Basis-Validierung:
|
||||
|
||||
- **CSS:** Klammer-Matching, Attribut-Selektoren
|
||||
- **JavaScript:** Klammer-Matching (rund, eckig, geschweift)
|
||||
- **PHP:** Übersprungen mit Warnung
|
||||
|
||||
---
|
||||
|
||||
## Validierungsebenen
|
||||
|
||||
### Kritische Fehler (Rebuild wird abgebrochen)
|
||||
- JSON-Syntax-Fehler
|
||||
- PHP-Syntax-Fehler
|
||||
- CSS-Syntax-Fehler (schwerwiegend)
|
||||
- JavaScript-Syntax-Fehler
|
||||
- Fehlende Relationship-Definitionen
|
||||
|
||||
### Warnungen (Rebuild wird fortgesetzt)
|
||||
- CSS-Best-Practice-Verletzungen
|
||||
- Fehlende i18n-Übersetzungen
|
||||
- Code-Style-Probleme
|
||||
- Performance-Hinweise
|
||||
|
||||
---
|
||||
|
||||
## Manuelle Verwendung der Tools
|
||||
|
||||
### CSS prüfen
|
||||
```bash
|
||||
# Einzelne Datei
|
||||
csslint client/custom/css/my-styles.css
|
||||
|
||||
# Alle CSS-Dateien
|
||||
find client/custom/css -name "*.css" -exec csslint {} \;
|
||||
|
||||
# Mit spezifischen Regeln
|
||||
csslint --errors=errors,duplicate-properties client/custom/css/
|
||||
```
|
||||
|
||||
### JavaScript prüfen
|
||||
```bash
|
||||
# Einzelne Datei
|
||||
jshint client/custom/src/views/my-view.js
|
||||
|
||||
# Alle JS-Dateien
|
||||
find client/custom/src -name "*.js" -exec jshint {} \;
|
||||
|
||||
# Mit Konfiguration
|
||||
jshint --config .jshintrc client/custom/src/
|
||||
```
|
||||
|
||||
### PHP prüfen
|
||||
```bash
|
||||
# Einzelne Datei
|
||||
php -l custom/Espo/Custom/Classes/MyClass.php
|
||||
|
||||
# Alle PHP-Dateien
|
||||
find custom/Espo -name "*.php" -exec php -l {} \; | grep -v "No syntax errors"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Zusätzliche empfohlene Tools (optional)
|
||||
|
||||
### 1. ESLint (moderne Alternative zu JSHint)
|
||||
```bash
|
||||
sudo npm install -g eslint
|
||||
eslint --init # Erstellt .eslintrc Konfiguration
|
||||
```
|
||||
|
||||
### 2. Stylelint (moderne Alternative zu CSSLint)
|
||||
```bash
|
||||
sudo npm install -g stylelint stylelint-config-standard
|
||||
# Benötigt .stylelintrc Konfiguration
|
||||
```
|
||||
|
||||
### 3. PHPStan (statische PHP-Analyse)
|
||||
```bash
|
||||
composer require --dev phpstan/phpstan
|
||||
vendor/bin/phpstan analyse custom/Espo
|
||||
```
|
||||
|
||||
### 4. PHP_CodeSniffer (PHP Code-Style)
|
||||
```bash
|
||||
sudo apt install -y php-codesniffer
|
||||
phpcs --standard=PSR12 custom/Espo/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Tool nicht gefunden
|
||||
```bash
|
||||
# Prüfe Installation
|
||||
which csslint
|
||||
which jshint
|
||||
which php
|
||||
|
||||
# Installiere fehlende Tools
|
||||
sudo apt update
|
||||
sudo apt install -y nodejs npm php-cli
|
||||
sudo npm install -g csslint jshint
|
||||
```
|
||||
|
||||
### Validierung zu streng
|
||||
Bearbeite das Script und passe die Tool-Parameter an:
|
||||
```python
|
||||
# Weniger strikte CSS-Validierung
|
||||
result = subprocess.run(
|
||||
['csslint', '--format=compact', '--errors=errors', str(css_file)],
|
||||
...
|
||||
)
|
||||
```
|
||||
|
||||
### Performance-Probleme
|
||||
Für große Projekte mit vielen Dateien:
|
||||
```python
|
||||
# Parallele Validierung mit ThreadPoolExecutor
|
||||
from concurrent.futures import ThreadPoolExecutor
|
||||
|
||||
with ThreadPoolExecutor(max_workers=4) as executor:
|
||||
results = executor.map(validate_css_file, css_files)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Vor jedem Commit:** Führe Validierung aus
|
||||
```bash
|
||||
python3 custom/scripts/validate_and_rebuild.py --dry-run
|
||||
```
|
||||
|
||||
2. **Automatisierung:** Integriere in Git pre-commit hook
|
||||
```bash
|
||||
# .git/hooks/pre-commit
|
||||
#!/bin/bash
|
||||
python3 custom/scripts/validate_and_rebuild.py --dry-run
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "Validierung fehlgeschlagen. Commit abgebrochen."
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
3. **CI/CD Integration:** Nutze in Build-Pipeline
|
||||
```yaml
|
||||
# .gitlab-ci.yml / .github/workflows/
|
||||
validate:
|
||||
script:
|
||||
- python3 custom/scripts/validate_and_rebuild.py --dry-run
|
||||
```
|
||||
|
||||
4. **IDE Integration:** Konfiguriere Editor für Live-Feedback
|
||||
- VSCode: ESLint/Stylelint Extensions
|
||||
- PHPStorm: Built-in PHP/JS/CSS Validierung
|
||||
|
||||
---
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Updates der Tools
|
||||
```bash
|
||||
# System-Packages
|
||||
sudo apt update && sudo apt upgrade
|
||||
|
||||
# NPM-Packages
|
||||
sudo npm update -g csslint jshint
|
||||
|
||||
# Prüfe Versionen
|
||||
php --version
|
||||
csslint --version
|
||||
jshint --version
|
||||
```
|
||||
|
||||
### Entfernung
|
||||
```bash
|
||||
# NPM-Tools
|
||||
sudo npm uninstall -g csslint jshint
|
||||
|
||||
# APT-Packages
|
||||
sudo apt remove php-cli nodejs npm
|
||||
sudo apt autoremove
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Letzte Aktualisierung:** Januar 2026
|
||||
**Maintainer:** Custom Scripts Team
|
||||
**Dokumentation:** `custom/scripts/VALIDATION_TOOLS.md`
|
||||
196
custom/docs/tools/VALIDATOR_README.md
Normal file
196
custom/docs/tools/VALIDATOR_README.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# EspoCRM Validator & Rebuild Tool
|
||||
|
||||
## Übersicht
|
||||
|
||||
Das neue Python-basierte Validierungs-Tool `validate_and_rebuild.py` ersetzt das bisherige Bash-Script und bietet erweiterte Prüfungen für EspoCRM Custom-Entities.
|
||||
|
||||
## Features
|
||||
|
||||
### ✅ Automatische Validierungen
|
||||
|
||||
1. **JSON-Syntax-Prüfung**
|
||||
- Validiert alle `.json` Dateien im `custom/` Verzeichnis
|
||||
- Findet Syntax-Fehler mit Dateiname und Zeilennummer
|
||||
|
||||
2. **Relationship-Konsistenz**
|
||||
- Prüft bidirektionale Relationships (hasMany/hasOne)
|
||||
- Validiert `foreign`-Links zwischen Entities
|
||||
- Überprüft `relationName`-Konsistenz
|
||||
- Erkennt fehlende Gegenseiten-Definitionen
|
||||
|
||||
3. **Formula-Script Platzierung**
|
||||
- Prüft ob Formula-Scripts in `/formula/` statt `/entityDefs/` liegen
|
||||
- Warnt vor leeren Formula-Definitionen
|
||||
|
||||
4. **i18n-Vollständigkeit**
|
||||
- Findet fehlende Übersetzungen (de_DE / en_US)
|
||||
- Prüft Link-Labels für alle Custom-Relationships
|
||||
- Warnt bei komplett fehlenden i18n-Dateien
|
||||
|
||||
5. **Layout-Struktur**
|
||||
- Validiert clientDefs und bottomPanels
|
||||
- Findet unnötige `false`-Elemente
|
||||
|
||||
6. **Dateirechte** (✨ ERWEITERT)
|
||||
- Prüft Owner (www-data:www-data) in DREI Bereichen:
|
||||
- `custom/Espo/Custom/Resources/` - Custom Metadata
|
||||
- `client/custom/` - Frontend JavaScript & CSS
|
||||
- `data/` - **INKL. config.php & config-internal.php**
|
||||
- Korrigiert Permissions automatisch (664 für Dateien, 775 für Verzeichnisse)
|
||||
- **Hebt kritische System-Dateien hervor** (config.php, config-internal.php)
|
||||
|
||||
7. **CSS-Validierung**
|
||||
- Validiert Syntax aller CSS-Dateien
|
||||
- Prüft Klammer-Balance und grundlegende Struktur
|
||||
|
||||
8. **JavaScript-Validierung**
|
||||
- Prüft Syntax aller JS-Dateien in `client/custom/src/`
|
||||
|
||||
9. **PHP-Validierung**
|
||||
- Validiert PHP-Syntax aller Custom-Klassen
|
||||
|
||||
10. **Rebuild-Ausführung**
|
||||
- Führt `rebuild.php` nur aus, wenn keine kritischen Fehler vorliegen
|
||||
|
||||
## Verwendung
|
||||
|
||||
### Direkt ausführen
|
||||
```bash
|
||||
cd /path/to/espocrm
|
||||
python3 custom/scripts/validate_and_rebuild.py
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Exit Codes
|
||||
|
||||
- `0` - Erfolg: Alle Validierungen bestanden, Rebuild erfolgreich
|
||||
- `1` - Fehler: Kritische Fehler gefunden oder Rebuild fehlgeschlagen
|
||||
|
||||
## Output-Format
|
||||
|
||||
Das Script verwendet farbcodierte Ausgaben:
|
||||
|
||||
- 🟢 **Grün (✓)**: Erfolgreich / OK
|
||||
- 🟡 **Gelb (⚠)**: Warnungen (nicht kritisch)
|
||||
- 🔴 **Rot (✗)**: Fehler (kritisch, Rebuild wird abgebrochen)
|
||||
- 🔵 **Blau (ℹ)**: Informationen
|
||||
|
||||
## Fehlertypen
|
||||
|
||||
### Kritische Fehler (Rebuild-Abbruch)
|
||||
- JSON-Syntax-Fehler
|
||||
- Fehlende Relationship-Definitionen
|
||||
- Falsch platzierte Formula-Scripts
|
||||
|
||||
### Warnungen (kein Abbruch)
|
||||
- Fehlende i18n-Übersetzungen
|
||||
- Layout-Strukturprobleme
|
||||
- Dateirechte-Probleme
|
||||
|
||||
## Beispiel-Output
|
||||
|
||||
```
|
||||
EspoCRM Custom Entity Validator & Rebuild Tool
|
||||
Arbeitsverzeichnis: /var/lib/docker/volumes/vmh-espocrm_espocrm/_data
|
||||
|
||||
======================================================================
|
||||
1. JSON-SYNTAX VALIDIERUNG
|
||||
======================================================================
|
||||
|
||||
✓ Alle 547 JSON-Dateien sind syntaktisch korrekt
|
||||
|
||||
======================================================================
|
||||
2. RELATIONSHIP-KONSISTENZ
|
||||
======================================================================
|
||||
|
||||
✗ 4 Relationship-Fehler gefunden:
|
||||
• Contact.cBankverbindungenContact: Ziel-Entity 'CBankverbindung' existiert nicht
|
||||
• CMietobjekt.vmhRumungsklages → CVmhRumungsklage: Foreign link 'mietobjekte' fehlt
|
||||
|
||||
======================================================================
|
||||
ZUSAMMENFASSUNG
|
||||
======================================================================
|
||||
|
||||
FEHLER: 4
|
||||
✗ Contact.cBankverbindungenContact: Ziel-Entity 'CBankverbindung' existiert nicht
|
||||
...
|
||||
|
||||
REBUILD ABGEBROCHEN: Kritische Fehler müssen behoben werden!
|
||||
```
|
||||
|
||||
## Erweiterung
|
||||
|
||||
Das Script ist modular aufgebaut. Neue Validierungen können einfach hinzugefügt werden:
|
||||
|
||||
```python
|
||||
def validate_custom_check(self) -> bool:
|
||||
"""Eigene Validierung."""
|
||||
print_header("X. CUSTOM CHECK")
|
||||
|
||||
# Prüflogik hier
|
||||
if error_found:
|
||||
self.errors.append("Fehlerbeschreibung")
|
||||
return False
|
||||
|
||||
print_success("Check erfolgreich")
|
||||
return True
|
||||
```
|
||||
|
||||
Dann in `validate_all()` hinzufügen:
|
||||
|
||||
```python
|
||||
if not self.validate_custom_check():
|
||||
all_valid = False
|
||||
```
|
||||
|
||||
## Anforderungen
|
||||
|
||||
- Python 3.6+
|
||||
- Keine zusätzlichen Packages erforderlich (nur Standard-Library)
|
||||
- Optionale sudo-Rechte für Dateirechte-Korrektur
|
||||
|
||||
## Integration in Workflow
|
||||
|
||||
Das Script kann in automatisierte Workflows integriert werden:
|
||||
|
||||
```bash
|
||||
# In CI/CD Pipeline
|
||||
python3 custom/scripts/validate_and_rebuild.py || exit 1
|
||||
|
||||
# Als Git Pre-Commit Hook
|
||||
#!/bin/bash
|
||||
python3 custom/scripts/validate_and_rebuild.py --dry-run
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Script findet rebuild.php nicht
|
||||
```bash
|
||||
# Stelle sicher, dass du im EspoCRM-Root bist
|
||||
cd /var/lib/docker/volumes/vmh-espocrm_espocrm/_data
|
||||
python3 custom/scripts/validate_and_rebuild.py
|
||||
```
|
||||
|
||||
### Dateirechte können nicht korrigiert werden
|
||||
```bash
|
||||
# Manuell mit sudo korrigieren
|
||||
sudo chown -R www-data:www-data custom/
|
||||
sudo find custom/ -type f -exec chmod 664 {} \;
|
||||
sudo find custom/ -type d -exec chmod 775 {} \;
|
||||
```
|
||||
|
||||
### Python3 nicht verfügbar
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt-get install python3
|
||||
|
||||
# CentOS/RHEL
|
||||
sudo yum install python3
|
||||
```
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [README.md](../../README.md) - Hauptdokumentation
|
||||
- [CUSTOM_DIRECTORY.md](../CUSTOM_DIRECTORY.md) - Custom-Verzeichnis-Struktur
|
||||
- [workflow_manager.php](workflow_manager.php) - Workflow-Management-Tool
|
||||
72
custom/docs/workflows/README.md
Normal file
72
custom/docs/workflows/README.md
Normal file
@@ -0,0 +1,72 @@
|
||||
# Workflow Definitions
|
||||
|
||||
This directory contains workflow definitions in JSON format that can be imported into EspoCRM using the workflow manager script.
|
||||
|
||||
## File Format
|
||||
|
||||
### Simple Workflow
|
||||
```json
|
||||
{
|
||||
"type": "simple",
|
||||
"name": "workflow-name",
|
||||
"entity_type": "EntityName",
|
||||
"trigger_type": "afterRecordSaved",
|
||||
"is_active": true,
|
||||
"description": "Description of what this workflow does",
|
||||
"category": "Category Name",
|
||||
"conditions_all": [],
|
||||
"conditions_any": [],
|
||||
"conditions_formula": null,
|
||||
"actions": []
|
||||
}
|
||||
```
|
||||
|
||||
**Trigger Types:**
|
||||
- `afterRecordSaved` - After record is created or updated
|
||||
- `afterRecordCreated` - Only after record is created
|
||||
- `scheduled` - Runs on a schedule
|
||||
- `manual` - Manually triggered
|
||||
|
||||
**Condition Types:**
|
||||
- `equals`, `notEquals`, `greaterThan`, `lessThan`, `contains`, `notContains`, `isEmpty`, `isNotEmpty`, `isTrue`, `isFalse`, `wasEqual`, `wasNotEqual`, `changed`, `notChanged`
|
||||
|
||||
**Action Types:**
|
||||
- `sendEmail` - Send email to recipient
|
||||
- `createEntity` - Create a new record
|
||||
- `updateEntity` - Update current record
|
||||
- `relateTo` - Link to another record
|
||||
- `unrelateFrom` - Unlink from record
|
||||
- `applyAssignmentRule` - Apply assignment rules
|
||||
- `createNotification` - Create notification
|
||||
|
||||
### BPM Flowchart
|
||||
```json
|
||||
{
|
||||
"type": "bpm",
|
||||
"name": "flowchart-name",
|
||||
"target_type": "EntityName",
|
||||
"is_active": true,
|
||||
"description": "Description",
|
||||
"data": {
|
||||
"list": []
|
||||
},
|
||||
"elements_data_hash": {},
|
||||
"event_start_all_id_list": []
|
||||
}
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
Import a workflow:
|
||||
```bash
|
||||
docker exec espocrm php /var/www/html/custom/scripts/workflow_manager.php import /var/www/html/custom/workflows/your-workflow.json
|
||||
```
|
||||
|
||||
Export a workflow:
|
||||
```bash
|
||||
docker exec espocrm php /var/www/html/custom/scripts/workflow_manager.php export <workflow-id> /var/www/html/custom/workflows/exported.json
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
- `vmh-erstberatung-abschliessen.json` - Sends email and sets status when consultation is completed
|
||||
Reference in New Issue
Block a user