leocrm/.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