leocrm/AGENTS.md

LeoCRM — AGENTS.md

Projekt: leocrm | Stack: FastAPI + SQLAlchemy + PostgreSQL 16 (pgvector) + React/TypeScript/Vite/Tailwind

---

1. Build & Test Commands

# Backend
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
python -m pytest -v --tb=short
python -m pytest tests/test_auth.py -v --tb=short
alembic upgrade head
alembic revision --autogenerate -m "description"

# Frontend
cd frontend && npm run dev
cd frontend && npm run build
cd frontend && npx vitest run --reporter=verbose
cd frontend && npx tsc --noEmit

# Docker
docker compose up -d
docker compose logs -f backend

---

2. Test Rules

• TDD: failing test first → implement → refactor
• NEVER modify tests to make them pass — fix the code
• Test DB: ephemeral PostgreSQL, NEVER production DB
• Mock external services (SMTP, IMAP, OnlyOffice) with AsyncMock
• Tests must be deterministic and isolated

---

3. Code Conventions

Backend

• Async first: all routes/services async def
• UUID primary keys only, never integer auto-increment
• TIMESTAMPTZ only, never naive datetime
• Soft-delete via deleted_at IS NULL; hard-delete only with ?gdpr=true
• Pydantic schemas validate input, never validate in routes
• All mutations create audit log entries
• snake_case files/functions, PascalCase classes
• Schemas: <Entity>Create, <Entity>Update, <Entity>Read

Frontend

• TypeScript strict, no any
• Functional components only, no class components
• TanStack Query for server state, Zustand for client state only
• React Hook Form + Zod for all forms
• Tailwind utility classes, no inline styles
• i18n via t() from react-i18next, no hardcoded strings
• ARIA attributes on all interactive elements, 44px touch targets
• PascalCase.tsx for components, camelCase.ts for utilities

Git

• Conventional Commits: feat(core): ..., fix(dms): ...
• Squash merge to main after review

---

4. Forbidden Patterns

Backend

• ❌ SQLite — PostgreSQL 16 only
• ❌ Jinja2/server-side HTML rendering — API-only backend
• ❌ Cross-tenant data access — ORM auto-filter must not be bypassed
• ❌ Plaintext passwords — bcrypt cost=12
• ❌ JWT auth — session-based with HttpOnly cookies only
• ❌ Naive datetime — TIMESTAMPTZ only
• ❌ Integer IDs — UUID only
• ❌ Hard-delete without ?gdpr=true
• ❌ Manual tenant filter — ORM auto-filter handles it
• ❌ Sync I/O in routes — use asyncpg, aiofiles
• ❌ Raw SQL without tenant_id check
• ❌ Secrets in code — env vars only
• ❌ Unvalidated input — Pydantic schemas required
• ❌ Missing audit log on mutations
• ❌ Plugin tables without tenant_id

Frontend

• ❌ Class components
• ❌ Inline styles — Tailwind only
• ❌ Hardcoded strings — use t()
• ❌ Manual fetch/axios in components — use TanStack Query
• ❌ Server data in Zustand
• ❌ any types
• ❌ Missing ARIA attributes
• ❌ Touch targets < 44px
• ❌ Direct DOM manipulation — use React refs
• ❌ dangerouslySetInnerHTML without sanitization

Deployment

• ❌ Running as root in container — use app:app
• ❌ Exposed DB port in production
• ❌ Missing Docker health checks
• ❌ Ephemeral storage — use named volumes
• ❌ Secrets in docker-compose.yml

---

5. Quality Gates

• Per-Task: tests pass, coverage met, tsc/ruff clean, build succeeds, no forbidden patterns
• Phase: all tasks pass → quality_reviewer review → user checkpoint
• Release: all tasks complete → release_auditor audit → Docker builds → health 200 → E2E pass

---

6. ADRs

• ADR-01: PostgreSQL 16 (not SQLite)
• ADR-02: ARQ (not Celery)
• ADR-03: Built-in plugins with manifest (not pip-install)
• ADR-04: TanStack Query (not Redux)
• ADR-05: Session-based auth (not JWT)
• ADR-06: Soft-delete with deleted_at

Full architecture: architecture.md | Full task graph: task_graph.json

---

7. Deploy

Vor Deploy: docs/deploy-guide.md lesen (Befehle, Credentials, Server-Info).

• Frontend-only: bash /a0/usr/projects/leocrm/scripts/fast-deploy.sh frontend
• Full (Backend): bash /a0/usr/projects/leocrm/scripts/fast-deploy.sh full
• Git Workflow: commit → push → deploy

---

8. Dokumentations-Pflichten

Wichtige MD-Dateien im Projekt

Datei	Zweck
README.md	Projekt-Overview, Setup
PLATFORM_ROADMAP.md	EINZIGE Planungs-Datei für zukünftige Entwicklung, Umbauten, Roadmap. Alle Phasen, Tasks und Architekturentscheidungen
PROGRESS.md	Fortschritts-Tracking — pro Task: Status, Forgejo Issue, Verifiziert. Wird vom Agent bei jedem Status-Wechsel aktualisiert
AGENTS.md	Agent-Definitionen (diese Datei)
docs/test-strategy.md	Test-Strategie, Konventionen, Einschränkungen
docs/security_kernel.md	Security-Konzept (ABAC, RLS, Session)
docs/permissions.md	Permission-System-Dokumentation
docs/permissions_plugin_dev.md	Permission-Plugin-Entwicklung
docs/monitoring.md	Monitoring, Health-Checks
docs/infrastructure.md	Infrastruktur (Docker, PostgreSQL, Redis)
docs/admin-guide.md	Admin-Handbuch
docs/api-documentation.md	API-Dokumentation
docs/INSTALL.md	Installationsanleitung
docs/plugin-development-guide.md	Plugin-Entwicklungs-Guide
docs/ui-design-guidelines.md	UI-Design-Richtlinien
docs/deploy-guide.md	Deploy-Anleitung, Credentials, Server-Info

Pflicht: Aktualisierung nach größeren Änderungen

Nach jeder größeren Änderung MÜSSEN die betroffenen MD-Dateien überarbeitet werden:

1. Neue Plugins/Module → docs/plugin-development-guide.md, docs/api-documentation.md, docs/test-strategy.md
2. Security-Änderungen → docs/security_kernel.md, docs/permissions.md, docs/test-strategy.md
3. Neue Test-Infrastruktur → docs/test-strategy.md
4. CI-Pipeline-Änderungen → docs/test-strategy.md, docs/infrastructure.md
5. Größere Refactoring → README.md, betroffene docs/-Dateien, docs/test-strategy.md
6. Nach Bugfix-Session → docs/test-strategy.md, docs/security_kernel.md
7. Roadmap-Änderungen → PLATFORM_ROADMAP.md
8. Infrastruktur-Änderungen → docs/infrastructure.md, docs/INSTALL.md
9. UI/UX-Änderungen → docs/ui-design-guidelines.md
10. API-Änderungen → docs/api-documentation.md

Verantwortlich: Agent/Entwickler der die Änderung durchführt.

Test-Konventionen (MUST FOLLOW)

Vor Tests: docs/test-strategy.md lesen für vollständige Konventionen und Einschränkungen.

1. Plugin-Aktivierung: init_permission_registry(active_plugin_names={...}) in jeder Plugin-Test-Datei
2. Entity-Typen: Korrekte ENTITY_MODELS-Keys (file nicht dms_file, mail_account nicht mailbox)
3. URLs: Korrekte API-Pfade (/api/v1/entity-links/ nicht /api/v1/dms/)
4. Dedup-Tests: Unterschiedlichen Dateiinhalt pro Upload verwenden
5. Keine zufälligen UUIDs: Echte Entity-IDs aus der DB verwenden
6. Test-Dateien: tests/test_<modul>.py | Fixtures: tests/conftest.py

---

9. Progress-Tracking & Forgejo-Issue-Verwaltung

Planungs- und Fortschrittsdateien

Datei	Zweck	Wann aktualisieren
PLATFORM_ROADMAP.md	EINZIGE Planungs-Datei. Alle Phasen, Tasks, Architekturentscheidungen	Bei Planungsänderungen
PROGRESS.md	Fortschritts-Tracking. Pro Task: Status, Forgejo Issue, Verifiziert	Bei jedem Task-Status-Wechsel

Task-Status-Verwaltung

Jeder Task in der Roadmap hat einen Status der in PROGRESS.md verfolgt wird:

• not_started — Task noch nicht begonnen
• in_progress — Task wird bearbeitet
• blocked — Task blockiert (Abhängigkeit fehlt, Entscheidung ausstehend)
• review — Task implementiert, wartet auf Review/Tests
• done — Task hat Definition of Done (DoD) erfüllt

Der Agent MUSS PROGRESS.md bei jedem Status-Wechsel aktualisieren. Kein Task-Wechsel ohne PROGRESS.md-Update.

Forgejo Issues & Milestones

• Pro Phase (A-J): Ein Forgejo Milestone (z.B. "Phase A — Stabilität", "Phase B — System-Konsolidierung")
• Pro Task: Ein Forgejo Issue mit Label task + Milestone der jeweiligen Phase
• Pro Bug: Ein Forgejo Issue mit Label bug + Priorität (critical, high, medium, low)
• Pro Feature-Request: Ein Forgejo Issue mit Label enhancement

Der Agent MUSS für jeden Task ein Forgejo Issue erstellen und die Issue-Nummer in PROGRESS.md eintragen.

Commit-Messages

• Commit-Messages enthalten die Task-ID: feat(B-LLM): zentraler LLM Client implementiert
• Bug-Fixes referenzieren das Issue: fix(#123): Redis-Connection-Leak behoben
• fixes #123 oder closes #123 im Commit schließt das Issue automatisch

Definition of Done (DoD)

Ein Task gilt erst als DONE wenn alle 8 DoD-Kriterien erfüllt sind (siehe PLATFORM_ROADMAP.md). Ein Task ohne Test ist NICHT done. Der Agent darf keinen Task als done markieren ohne DoD erfüllt zu haben.

Phase-Gate-Review

Eine Phase gilt erst als ABGESCHLOSSEN wenn alle 7 Phase-Gate-Kriterien erfüllt sind (siehe PLATFORM_ROADMAP.md). Der Agent darf nicht zur nächsten Phase übergehen ohne Phase-Gate-Review bestanden zu haben.