crm-system/.a0/briefings/T09_briefing.md

T09 — KI-Copilot API + Hybrid Workflow Engine Backend

Project Root

/a0/usr/workdir/dev-projects/leocrm

Backend Directory

/a0/usr/workdir/dev-projects/leocrm/app/

Tech Stack (existing)

• FastAPI + SQLAlchemy 2.0 + asyncpg + Pydantic v2 + ARQ
• PostgreSQL 18 on localhost:5432 (user/db: leocrm/leocrm + leocrm_test)
• Redis on localhost:6379
• venv at /opt/venv (already activated)
• T01-T03 complete (103 tests pass, commit 7a5a48f)

Requirements (5)

F-AI-01, F-WF-01, F-CORE-01, F-CORE-06, F-TEST-01

Acceptance Criteria (22)

KI-Copilot (7 ACs)

1. POST /api/v1/ai/copilot/query mit NL input → 200 + proposed_actions array
2. POST /api/v1/ai/copilot/execute mit proposed action → 200 + API result (RBAC enforced)
3. POST /api/v1/ai/copilot/execute als viewer mit delete action → 403 (RBAC blocks)
4. GET /api/v1/ai/copilot/history → 200 + paginated conversation history
5. Copilot action logged in audit_log with entity_type=ai_copilot
6. Copilot respects tenant isolation: cross-tenant → 404
7. Copilot respects field-level permissions: hidden fields not in response

Workflow Engine (15 ACs)

8. POST /api/v1/workflows mit valid steps JSONB → 201 + workflow definition
9. GET /api/v1/workflows → 200 + paginated list
10. GET /api/v1/workflows/{id} → 200 + workflow detail with steps
11. PATCH /api/v1/workflows/{id} → 200, updated
12. DELETE /api/v1/workflows/{id} → 204
13. POST /api/v1/workflows/{id}/instances → 201, instance created with status=pending
14. GET /api/v1/workflows/instances?status=in_progress → 200 + filtered list
15. GET /api/v1/workflows/instances/{id} → 200 + current_step_index + history
16. POST /api/v1/workflows/instances/{id}/advance (approve) → 200, step advanced
17. POST /api/v1/workflows/instances/{id}/advance (reject) → 200, status=rejected, initiator notified
18. POST /api/v1/workflows/instances/{id}/cancel → 200, status=cancelled
19. Event-triggered workflow: publish event → workflow instance auto-starts
20. workflow_step_history entry created on every step transition
21. Code-engine workflow: onboarding workflow runs on user creation
22. Approval step timeout → auto-reject after configured hours (tested with mock timer)

Files to Create

KI-Copilot

• app/models/ai_conversation.py — AIConversation, AIMessage models (tenant-scoped)
• app/schemas/ai_copilot.py — CopilotQueryRequest, CopilotAction, CopilotExecuteRequest, CopilotHistoryResponse
• app/services/ai_copilot_service.py — NL→API translation, LLM client, RBAC enforcement, audit logging
• app/routes/ai_copilot.py — POST /query, POST /execute, GET /history
• app/ai/__init__.py
• app/ai/llm_client.py — Configurable LLM client (AI_MODEL, AI_API_KEY env vars)
• app/ai/action_mapper.py — Maps NL intents to API calls

Workflow Engine

• app/models/workflow.py — Workflow, WorkflowInstance, WorkflowStepHistory models (tenant-scoped)
• app/schemas/workflow.py — WorkflowCreate, WorkflowResponse, InstanceCreate, InstanceResponse, AdvanceRequest
• app/services/workflow_service.py — CRUD workflows, instance lifecycle (start/advance/approve/reject/cancel)
• app/routes/workflows.py — Workflow CRUD + instance endpoints
• app/workflows/__init__.py
• app/workflows/code/__init__.py — Code-engine workflows
• app/workflows/code/onboarding.py — Onboarding workflow (runs on user creation)
• app/workflows/engine.py — Workflow execution engine (step processing, conditions, approvals)

Tests

• tests/test_ai_copilot.py — 7 AC tests + edge cases
• tests/test_workflows.py — 15 AC tests + edge cases

Migration

• alembic/versions/0004_ai_workflows.py — ai_conversations, ai_messages, workflows, workflow_instances, workflow_step_history tables (all tenant-scoped with RLS)

Files to Modify

• app/main.py — Register ai_copilot + workflows routers
• app/models/__init__.py — Add new model imports
• app/routes/__init__.py — Add new router imports
• app/schemas/__init__.py — Add new schema imports
• app/services/__init__.py — Add new service imports
• tests/conftest.py — Add new tables to TRUNCATE list
• app/core/event_bus.py — Add workflow event trigger integration (if not already present)

LLM Client Design

• Read AI_MODEL and AI_API_KEY from environment
• If not set, use mock/stub mode (returns predefined actions for tests)
• Support OpenAI-compatible API (default)
• NL → proposed API calls: method, path, body, description
• Never execute directly — always return proposed actions for user confirmation

Workflow Engine Design

• Step types: action, approval, notification, condition
• Workflow definition: JSONB steps array
• Instance lifecycle: pending → in_progress → completed/rejected/cancelled
• Event bus integration: subscribe to events, auto-start workflows with matching trigger
• Code-engine: hardcoded workflows in app/workflows/code/ (onboarding on user.created event)
• Approval timeout: configurable hours, auto-reject via ARQ scheduled job or mock timer in tests

Critical Rules

• All POST routes MUST have status_code=201 (except execute/advance/cancel which are actions → 200)
• Use set_config() for tenant context, NOT SET LOCAL
• Use .com emails in tests, NOT .test
• All new tables MUST have tenant_id column + RLS policies
• Update tests/conftest.py TRUNCATE list with new tables
• Create Alembic migration 0004 for all new tables
• Copilot MUST enforce RBAC (same middleware, same permissions)
• Copilot MUST respect tenant isolation and field-level permissions
• Audit log entity_type=ai_copilot for all copilot actions
• Workflow mutations MUST be logged in workflow_step_history
• Idempotent where applicable

Test Commands

cd /a0/usr/workdir/dev-projects/leocrm && python -m pytest tests/test_ai_copilot.py tests/test_workflows.py -v --tb=short cd /a0/usr/workdir/dev-projects/leocrm && python -m pytest tests/ -v --tb=short (full suite regression)

Coverage Target

80% for new modules

Deliverables

1. All files listed above
2. Alembic migration 0004
3. tests/test_ai_copilot.py + tests/test_workflows.py covering all 22 ACs
4. Report: test results, AC coverage, files, bugs