T09: KI-Copilot API + Hybrid Workflow Engine + LLM client + event-triggered workflows

- KI-Copilot: NL query → proposed actions, execute with RBAC, history, audit logging - LLM client: mock mode (no API key) + OpenAI-compatible mode (AI_MODEL/AI_API_KEY) - Action mapper: NL intent → API calls (create/update/delete/search company/contact) - Workflow engine: step types (action/approval/notification/condition), JSONB steps - Workflow lifecycle: pending → in_progress → completed/rejected/cancelled - Event-triggered workflows: event bus → auto-start instances - Code-engine workflows: onboarding on user.created event - Approval timeout: auto-reject after configured hours - 5 new tenant-scoped tables with RLS: ai_conversations, ai_messages, workflows, workflow_instances, workflow_step_history - Migration 0004: all tables + RLS policies + tenant_id + indexes - 238 tests pass (30 AC + 105 coverage + 103 existing), 84.12% T09 module coverage - MissingGreenlet fix: safe accessor helpers for async ORM attribute access
2026-06-29 02:44:13 +02:00
parent 9678344f0e
commit 851e7999ba
31 changed files with 5884 additions and 3 deletions
@@ -1,3 +1,3 @@
 """Routes package."""

-from app.routes import auth, users, roles, tenants, health, notifications, companies, contacts, import_export, plugins
+from app.routes import auth, users, roles, tenants, health, notifications, companies, contacts, import_export, plugins, ai_copilot, workflows
@@ -0,0 +1,102 @@
+"""AI Copilot routes — query, execute, history."""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.auth import check_permission
+from app.core.db import get_db
+from app.deps import get_current_user
+from app.schemas.ai_copilot import (
+    CopilotQueryRequest,
+    CopilotExecuteRequest,
+)
+from app.services import ai_copilot_service
+
+router = APIRouter(prefix="/api/v1/ai/copilot", tags=["ai-copilot"])
+
+
+@router.post("/query")
+async def copilot_query(
+    body: CopilotQueryRequest,
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Process a natural language query and return proposed actions.
+
+    Returns proposed_actions array for user confirmation.
+    Does NOT execute any actions — user must call /execute to confirm.
+    """
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+    user_id = uuid.UUID(current_user["user_id"])
+
+    result = await ai_copilot_service.process_query(
+        db, tenant_id, user_id,
+        query=body.query,
+        conversation_id=body.conversation_id,
+        context=body.context,
+    )
+
+    if "error" in result and result.get("status_code") == 404:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail={"detail": result["error"], "code": "conversation_not_found"},
+        )
+
+    return result
+
+
+@router.post("/execute")
+async def copilot_execute(
+    body: CopilotExecuteRequest,
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Execute a proposed action after user confirmation.
+
+    RBAC is enforced — the user must have permission for the action.
+    Returns 200 with execution result or 403 if RBAC blocks.
+    """
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+    user_id = uuid.UUID(current_user["user_id"])
+    role = current_user.get("role", "viewer")
+
+    result = await ai_copilot_service.execute_action(
+        db, tenant_id, user_id, role,
+        conversation_id=body.conversation_id,
+        action=body.action.model_dump(),
+    )
+
+    if result.get("status_code") == 404:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail={"detail": result.get("error", "Not found"), "code": "not_found"},
+        )
+
+    if result.get("status_code") == 403:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail={"detail": result.get("error", "Insufficient permissions"), "code": "forbidden"},
+        )
+
+    return result
+
+
+@router.get("/history")
+async def copilot_history(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=100),
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Get paginated conversation history for the current user."""
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+    user_id = uuid.UUID(current_user["user_id"])
+
+    return await ai_copilot_service.get_history(
+        db, tenant_id, user_id,
+        page=page, page_size=page_size,
+    )
@@ -0,0 +1,249 @@
+"""Workflow routes — CRUD, instance lifecycle, advance/cancel."""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.auth import check_permission
+from app.core.db import get_db
+from app.deps import get_current_user
+from app.schemas.workflow import WorkflowCreate, WorkflowUpdate, InstanceCreate, AdvanceRequest
+from app.services import workflow_service
+
+router = APIRouter(prefix="/api/v1/workflows", tags=["workflows"])
+
+
+# ─── Workflow CRUD ───
+
+@router.get("")
+async def list_workflows(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=100),
+    is_active: bool | None = Query(None),
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """List workflows with pagination."""
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+    return await workflow_service.list_workflows(
+        db, tenant_id,
+        page=page, page_size=page_size,
+        is_active=is_active,
+    )
+
+
+@router.post("", status_code=status.HTTP_201_CREATED)
+async def create_workflow(
+    body: WorkflowCreate,
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Create a new workflow definition. Requires write permission."""
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+    user_id = uuid.UUID(current_user["user_id"])
+    role = current_user.get("role", "viewer")
+
+    if not check_permission(role, "workflows", "create"):
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail={"detail": "Insufficient permissions", "code": "forbidden"},
+        )
+
+    data = body.model_dump()
+    return await workflow_service.create_workflow(db, tenant_id, user_id, data)
+
+
+@router.get("/instances")
+async def list_instances(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=100),
+    status: str | None = Query(None),
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """List workflow instances with optional status filter."""
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+    return await workflow_service.list_instances(
+        db, tenant_id,
+        page=page, page_size=page_size,
+        status_filter=status,
+    )
+
+
+@router.get("/{workflow_id}")
+async def get_workflow(
+    workflow_id: str,
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Get a single workflow by ID."""
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+    result = await workflow_service.get_workflow(db, tenant_id, workflow_id)
+    if result is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail={"detail": "Workflow not found", "code": "not_found"},
+        )
+    return result
+
+
+@router.patch("/{workflow_id}")
+async def update_workflow(
+    workflow_id: str,
+    body: WorkflowUpdate,
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Update a workflow definition."""
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+    user_id = uuid.UUID(current_user["user_id"])
+    role = current_user.get("role", "viewer")
+
+    if not check_permission(role, "workflows", "update"):
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail={"detail": "Insufficient permissions", "code": "forbidden"},
+        )
+
+    data = body.model_dump(exclude_unset=True)
+    result = await workflow_service.update_workflow(db, tenant_id, user_id, workflow_id, data)
+    if result is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail={"detail": "Workflow not found", "code": "not_found"},
+        )
+    return result
+
+
+@router.delete("/{workflow_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_workflow(
+    workflow_id: str,
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Delete a workflow definition."""
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+    user_id = uuid.UUID(current_user["user_id"])
+    role = current_user.get("role", "viewer")
+
+    if not check_permission(role, "workflows", "delete"):
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail={"detail": "Insufficient permissions", "code": "forbidden"},
+        )
+
+    deleted = await workflow_service.delete_workflow(db, tenant_id, user_id, workflow_id)
+    if not deleted:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail={"detail": "Workflow not found", "code": "not_found"},
+        )
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+# ─── Instance endpoints ───
+
+@router.post("/{workflow_id}/instances", status_code=status.HTTP_201_CREATED)
+async def create_instance(
+    workflow_id: str,
+    body: InstanceCreate,
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Create a new workflow instance."""
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+    user_id = uuid.UUID(current_user["user_id"])
+
+    result = await workflow_service.create_instance(
+        db, tenant_id, user_id,
+        workflow_id=workflow_id,
+        context=body.context,
+        timeout_hours=body.timeout_hours,
+    )
+    if result is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail={"detail": "Workflow not found", "code": "not_found"},
+        )
+    return result
+
+
+@router.get("/instances/{instance_id}")
+async def get_instance(
+    instance_id: str,
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Get a workflow instance with step history."""
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+    result = await workflow_service.get_instance(db, tenant_id, instance_id)
+    if result is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail={"detail": "Instance not found", "code": "not_found"},
+        )
+    return result
+
+
+@router.post("/instances/{instance_id}/advance")
+async def advance_instance(
+    instance_id: str,
+    body: AdvanceRequest,
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Advance or reject a workflow instance step.
+
+    Body decision: "approve" or "reject".
+    Returns 200 with updated instance.
+    """
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+    user_id = uuid.UUID(current_user["user_id"])
+
+    result = await workflow_service.advance_instance(
+        db, tenant_id, user_id,
+        instance_id=instance_id,
+        decision=body.decision,
+        comment=body.comment,
+    )
+    if result is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail={"detail": "Instance not found", "code": "not_found"},
+        )
+    if "error" in result:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail={"detail": result["error"], "code": "invalid_state"},
+        )
+    return result
+
+
+@router.post("/instances/{instance_id}/cancel")
+async def cancel_instance(
+    instance_id: str,
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Cancel a workflow instance. Returns 200 with cancelled instance."""
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+    user_id = uuid.UUID(current_user["user_id"])
+
+    result = await workflow_service.cancel_instance(
+        db, tenant_id, user_id,
+        instance_id=instance_id,
+    )
+    if result is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail={"detail": "Instance not found", "code": "not_found"},
+        )
+    if "error" in result:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail={"detail": result["error"], "code": "invalid_state"},
+        )
+    return result