docs: punkt 11 (documentation) — README, infrastructure, monitoring, admin-guide, deploy-guide, api-docs, PROGRESS, ENTERPRISE_READINESS_PLAN all updated

2026-08-20 14:03:35 +02:00
parent e6790d9b81
commit f79eb9354a
8 changed files with 853 additions and 242 deletions
@@ -1,7 +1,56 @@
 # LeoCRM v1.0

 > Plugin-basierte KI und Business-Plattform mit 23 Plugins (CRM, Mail, DMS, Chat, AI-Agenten, Workflows, Knowledge, Search). FastAPI Backend + React/TypeScript Frontend. Deployiert über Coolify auf Hetzner VPS.
-> Stack: FastAPI + SQLAlchemy (async) + PostgreSQL + Redis + React 18 + TypeScript + Vite + TanStack Query + Zustand + Tailwind + Docker + Coolify
+> Stack: FastAPI + SQLAlchemy (async) + PostgreSQL 16 (pgvector) + Redis 7 + React 18 + TypeScript + Vite + TanStack Query + Zustand + Tailwind + Docker + Coolify
+
+## Features
+
+### Core Platform
+- **Multi-Tenant** — Tenant-Isolation via ORM Auto-Filter + Row Level Security (RLS)
+- **Plugin System** — 23 Built-in Plugins, Manifest-basiert, aktivierbar/deaktivierbar
+- **Permission System** — ABAC/RBAC mit feingranularen Permissions
+- **Audit Log** — Vollständige Audit-Trail, CSV/JSON Export, 365 Tage Retention
+- **Entity History** — Undo/Restore für alle Entitäten
+- **Soft Delete** — `deleted_at` auf allen Entitäten, Hard-Delete mit `?gdpr=true`
+- **Unified Search** — Hybrid-Suche (PostgreSQL FTS + pgvector), KI Query-Understanding
+- **System Dashboard** — Admin-only Monitoring (DB, Redis, Worker, Errors, LLM Costs)
+- **Backup Automation** — ARQ-gesteuert, einstellbar in Settings, Backup-History
+- **Trash Cleanup** — Automatische endgültige Löschung nach 90 Tagen
+
+### 23 Plugins
+
+| # | Plugin | Beschreibung |
+|---|--------|-------------|
+| 1 | **contacts** | Kontakt-Verwaltung (Personen, Firmen, Ordner, Custom Fields) |
+| 2 | **mail** | IMAP/SMTP E-Mail-Integration, PGP, Filter-Regeln, Vacation Responder |
+| 3 | **dms** | Document Management System, File Upload, Preview, Sharing, Permissions |
+| 4 | **calendar** | Kalender, Termine, Ressourcen-Buchung, ICS Import/Export, Kanban |
+| 5 | **tasks** | Unified Task System, Subtasks, Goals, polymorphe Zuweisung |
+| 6 | **kommunikation** | Unified Messaging, Chat, Mini-Apps, WebSocket-basiert |
+| 7 | **automation** | Automation Builder, Trigger, Agent Runner, Cron-Scheduler |
+| 8 | **ai_assistant** | AI Chat Sessions, Provider, Models, Presets, Tools |
+| 9 | **ai_proactive** | Proactive AI, Suggestions, SSE Streaming, Settings |
+| 10 | **ai_ui_control** | AI-driven UI Control via WebSocket |
+| 11 | **agent_memory** | Agent Memory Plugin, eigene Routes |
+| 12 | **unified_search** | Hybrid-Suche, Embeddings, RRF Rank Fusion, Facets |
+| 13 | **graph_rag** | GraphRAG, Knowledge Graph, Relationship Extraction |
+| 14 | **wiki** | Wiki Plugin, Article Versioning, Categories, Entity Links |
+| 15 | **report_generator** | Report Templates, Generation, Download |
+| 16 | **entity_links** | Entity Linking, File-Entity Connections |
+| 17 | **tags** | Tag Management, Bulk-Assign, Entity-Tag Queries |
+| 18 | **permissions** | File-level Permissions, Share Links |
+| 19 | **mcp_server** | MCP Server, Tool Definitions für AI Agents |
+| 20 | **mcp_client** | MCP Client für externe Tool-Integration |
+| 21 | **marketplace** | Marketplace Listings |
+| 22 | **system_notif** | System Notifications, Alerting via Communication-System |
+| 23 | **forgejo_error_reporter** | Forgejo Error Reporting |
+
+### AI & Automation
+- **Agent System** — ReAct-Loop, Tool-Calls, Skills, Approvals, Monitoring, SSE Streaming
+- **Workflow Engine** — 14 Step-Types, Durable Runs, Retry, Idempotency, SSRF-Schutz
+- **Decision Guard** — Automated-Decision Guard für High-Risk Actions
+- **Approval System** — Human Approval für Agent Actions und Workflow Steps
+- **LLM Client** — Zentraler LLM Client, Cost-Tracking, Multi-Provider

 ## Quick Start (Development)

@@ -87,13 +136,23 @@ See [docs/admin-guide.md](docs/admin-guide.md) for detailed deployment, backup,

 | Endpoint | Method | Auth | Description |
 |---|---|---|---|
-| `/api/v1/health` | GET | No | Health check (DB, Redis, storage, worker) |
+| `/health/live` | GET | No | Liveness probe |
+| `/health/ready` | GET | No | Readiness probe (DB, Redis, storage, worker) |
+| `/api/v1/health` | GET | No | Full health check (DB, Redis, storage, worker) |
 | `/api/v1/metrics` | GET | Admin | Prometheus metrics (text/plain) |
+| `/api/v1/system/dashboard` | GET | Admin | System dashboard (DB, Redis, worker, errors, LLM costs) |
+| `/api/v1/system/alerts` | GET | Admin | Active system alerts |
 | `/api/v1/auth/login` | POST | No | Login |
 | `/api/v1/contacts` | GET | Yes | List contacts (paginated, max page_size=100) |
 | `/api/v1/contacts/export` | GET | Yes | Stream contacts as CSV |
 | `/api/v1/companies` | GET | Yes | List companies (paginated, max page_size=100) |
 | `/api/v1/companies/export` | GET | Yes | Stream companies as CSV |
+| `/api/v1/search` | POST | Yes | Hybrid search (FTS + pgvector) |
+| `/api/v1/audit-log` | GET | Admin | Query audit log entries |
+| `/api/v1/audit-log/export` | GET | Admin | Export audit log (CSV/JSON) |
+| `/api/v1/system-settings/backup-config` | GET/PUT | Admin | Backup configuration |
+| `/api/v1/system-settings/backup-now` | POST | Admin | Trigger immediate backup |
+| `/api/v1/system-settings/backup-history` | GET | Admin | Backup history (last 10) |

 ### Pagination

@@ -109,18 +168,25 @@ Uses `StreamingResponse` — does not buffer the entire file in memory.

 Interactive API documentation: http://localhost:8000/docs

-See [docs/api-overview.md](docs/api-overview.md) for the full endpoint summary.
+See [docs/api-documentation.md](docs/api-documentation.md) for the full endpoint reference.

 ## Monitoring

-### Health Check
+### Health Checks

 ```bash
-curl http://localhost:8000/api/v1/health
-```
+# Liveness
+curl http://localhost:8000/health/live
+# → {"status":"alive"}

-Returns JSON with overall status (`healthy`/`degraded`) and individual checks for
-`database`, `redis`, `storage`, and `worker`.
+# Readiness
+curl http://localhost:8000/health/ready
+# → {"status":"ready","checks":{"database":"ok","redis":"ok","storage":"ok"}}
+
+# Full health
+curl http://localhost:8000/api/v1/health
+# → {"status":"healthy","version":"1.0.0","checks":{...}}
+```

 ### Prometheus Metrics

@@ -135,6 +201,15 @@ Available metrics:
 - `leocrm_db_pool_connections` — Database connection pool size
 - `leocrm_arq_jobs_total` — Total ARQ background jobs

+### System Dashboard
+
+Admin-only dashboard at `/system-dashboard` in the WebUI. Shows:
+- System Health, DB Stats, Redis Stats, Worker Queue
+- API Stats (total requests, error rate, avg response time)
+- Plugin Stats (discovered, active)
+- Storage Stats (disk usage, file count)
+- Alert Feed (system messages from Communication-System)
+
 ### Structured Logging

 LeoCRM uses `structlog` for structured JSON logging. All API requests are logged with:
@@ -199,41 +274,73 @@ leocrm/
 ├── app/
 │   ├── main.py               # FastAPI entry point with logging middleware
 │   ├── config.py             # Pydantic settings
+│   ├── deps.py               # FastAPI dependencies (auth, permissions)
 │   ├── core/
 │   │   ├── monitoring.py      # Prometheus metrics + structured logging + health checks
 │   │   ├── db.py             # Async database engine
 │   │   ├── middleware.py     # CSRF middleware
+│   │   ├── worker.py        # ARQ worker settings
+│   │   ├── backup_job.py    # Automated backup job
+│   │   ├── notifications.py  # System notification dispatch
 │   │   └── ...
 │   ├── routes/
-│   │   ├── health.py         # Health endpoint
+│   │   ├── health.py         # Health endpoints
 │   │   ├── metrics.py        # Prometheus metrics endpoint (admin-only)
+│   │   ├── system_dashboard.py # System dashboard (admin-only)
+│   │   ├── system_settings.py # System settings + backup config
+│   │   ├── audit.py          # Audit log (list, export, retention)
 │   │   ├── contacts.py       # Contact CRUD + streaming CSV export
 │   │   ├── companies.py      # Company CRUD + streaming CSV export
+│   │   ├── workflows.py      # Workflow engine routes
 │   │   └── ...
 │   ├── models/               # SQLAlchemy models
 │   ├── schemas/              # Pydantic schemas
 │   ├── services/             # Business logic
-│   └── plugins/              # Plugin system
+│   ├── plugins/              # Plugin system (registry, manifest, base)
+│   │   └── builtins/         # 23 built-in plugins
+│   ├── workflows/            # Workflow engine
+│   └── ai/                   # AI modules
 ├── scripts/
+│   ├── fast-deploy.sh        # Frontend-only / full deploy
+│   ├── deploy.py             # Coolify API deployment
+│   ├── backup.py             # Backup script (pg_dump + files)
+│   ├── restore.py            # Restore script
 │   ├── seed_perf_data.py     # Performance test data seeding
 │   └── check_indexes.py      # Database index verification
 ├── tests/                    # Test suite (pytest + pytest-asyncio)
 ├── docs/
 │   ├── admin-guide.md       # Admin guide (deploy, backup, restore, troubleshooting)
-│   └── api-overview.md      # API endpoint summary
-├── alembic/                  # Database migrations
+│   ├── api-documentation.md  # Full API endpoint reference
+│   ├── monitoring.md        # Monitoring & health checks
+│   ├── infrastructure.md    # Infrastructure guide
+│   ├── deploy-guide.md      # Deploy guide (fast-deploy, Coolify, server info)
+│   └── ...
+├── alembic/                  # Database migrations (130+ files)
+├── frontend/                 # React + TypeScript + Vite + Tailwind
+│   └── src/pages/            # SystemDashboard, Contacts, Mail, DMS, Calendar, etc.
 ├── requirements.txt          # Production dependencies
 ├── requirements-dev.txt     # Test/lint dependencies
 ├── .env.example              # Environment template
-├── docker-compose.yml        # Docker Compose
+├── docker-compose.yaml       # Docker Compose (postgres, redis, crm_app, crm_worker)
+├── Dockerfile                # Multi-stage build (frontend → builder → runtime)
+├── prestart.sh               # Container entrypoint (migrations, seed, uvicorn)
+├── worker.sh                 # ARQ worker entrypoint
+├── healthcheck.sh            # Container healthcheck
 └── README.md                # This file
 ```

 ## Documentation

 - [Admin Guide](docs/admin-guide.md) — Deployment, backup, restore, env vars, troubleshooting
- [API Overview](docs/api-overview.md) — Full endpoint reference
- [Coolify Setup](COOLIFY_SETUP.md) — Coolify deployment instructions
+- [API Documentation](docs/api-documentation.md) — Full endpoint reference (300+ endpoints)
+- [Monitoring](docs/monitoring.md) — Health checks, metrics, system dashboard, alerting
+- [Infrastructure](docs/infrastructure.md) — Docker, PgBouncer, audit partitioning, backup
+- [Deploy Guide](docs/deploy-guide.md) — Fast-deploy, Coolify API, server info
+- [Plugin Development](docs/plugin-development-guide.md) — Plugin development guide
+- [Security Kernel](docs/security_kernel.md) — ABAC, RLS, session security
+- [Permissions](docs/permissions.md) — Permission system documentation
+- [Test Strategy](docs/test-strategy.md) — Test conventions and constraints
+- [UI Design Guidelines](docs/ui-design-guidelines.md) — UI design rules
 - [Swagger UI](http://localhost:8000/docs) — Interactive API docs (auto-generated)

 ## License