leocrm/AGENTS.md

# LeoCRM — AGENTS.md

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

---

## 1. Build & Test Commands

```bash
# 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.