feat(l1): L1 endpoint surface (intake/queue/step/notes/resolve/escalate)
Mounts /api/v1/l1/* with require_l1_or_coverage on every route. Intake creates an internal ticket and starts a flow OR adhoc session (PSA queue merge follows in Phase 2). Step/notes/resolve/escalate delegate to l1_session_service. escalate-without-walk creates an immediately- escalated session for the BuildAbortedNoKB path. ValueError from services → 400. Cross-account session access → 404. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
268
backend/app/api/endpoints/l1.py
Normal file
268
backend/app/api/endpoints/l1.py
Normal file
@@ -0,0 +1,268 @@
|
||||
"""L1 Workspace endpoints (Phase 1).
|
||||
|
||||
PSA-merge queue support + AI build path are deferred to Phase 2.
|
||||
"""
|
||||
from typing import Annotated, Optional
|
||||
from uuid import UUID
|
||||
|
||||
from fastapi import APIRouter, Depends, HTTPException, status as http_status
|
||||
from sqlalchemy import select
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
|
||||
from app.api.deps import get_db, require_l1_or_coverage
|
||||
from app.models.l1_walk_session import L1WalkSession
|
||||
from app.models.user import User
|
||||
from app.schemas.l1 import (
|
||||
EscalateRequest,
|
||||
EscalateWithoutWalkRequest,
|
||||
IntakeRequest,
|
||||
IntakeResponse,
|
||||
NotesRequest,
|
||||
QueueRow,
|
||||
ResolveRequest,
|
||||
StepRequest,
|
||||
WalkSessionResponse,
|
||||
)
|
||||
from app.services import internal_ticket_service, l1_session_service
|
||||
|
||||
|
||||
router = APIRouter(prefix="/l1", tags=["l1"])
|
||||
|
||||
|
||||
def _to_response(session: L1WalkSession) -> WalkSessionResponse:
|
||||
return WalkSessionResponse(
|
||||
id=session.id,
|
||||
session_kind=session.session_kind,
|
||||
flow_id=session.flow_id,
|
||||
flow_proposal_id=session.flow_proposal_id,
|
||||
current_node_id=session.current_node_id,
|
||||
walked_path=session.walked_path or [],
|
||||
walk_notes=session.walk_notes or [],
|
||||
status=session.status,
|
||||
started_at=session.started_at,
|
||||
last_step_at=session.last_step_at,
|
||||
resolved_at=session.resolved_at,
|
||||
)
|
||||
|
||||
|
||||
async def _get_session_or_404(
|
||||
db: AsyncSession, session_id: UUID, user: User
|
||||
) -> L1WalkSession:
|
||||
session = await db.get(L1WalkSession, session_id)
|
||||
if session is None or session.account_id != user.account_id:
|
||||
raise HTTPException(
|
||||
status_code=http_status.HTTP_404_NOT_FOUND,
|
||||
detail="Session not found",
|
||||
)
|
||||
return session
|
||||
|
||||
|
||||
@router.post("/intake", response_model=IntakeResponse)
|
||||
async def intake(
|
||||
payload: IntakeRequest,
|
||||
db: Annotated[AsyncSession, Depends(get_db)],
|
||||
user: Annotated[User, Depends(require_l1_or_coverage)],
|
||||
):
|
||||
"""L1 intake: creates an internal ticket and starts a walk session.
|
||||
|
||||
Phase 1: internal-ticket only (PSA support follows in Phase 2 escalation polish).
|
||||
If `flow_id` is provided, starts a flow session; otherwise an adhoc session.
|
||||
"""
|
||||
ticket = await internal_ticket_service.create_ticket(
|
||||
db,
|
||||
account_id=user.account_id,
|
||||
created_by_user_id=user.id,
|
||||
problem_statement=payload.problem_statement,
|
||||
customer_name=payload.customer_name,
|
||||
customer_contact=payload.customer_contact,
|
||||
)
|
||||
if payload.flow_id is not None:
|
||||
session = await l1_session_service.start_flow_session(
|
||||
db,
|
||||
account_id=user.account_id,
|
||||
user=user,
|
||||
flow_id=payload.flow_id,
|
||||
ticket_id=str(ticket.id),
|
||||
ticket_kind="internal",
|
||||
)
|
||||
else:
|
||||
session = await l1_session_service.start_adhoc_session(
|
||||
db,
|
||||
account_id=user.account_id,
|
||||
user=user,
|
||||
ticket_id=str(ticket.id),
|
||||
ticket_kind="internal",
|
||||
)
|
||||
await db.commit()
|
||||
return IntakeResponse(
|
||||
session_id=session.id,
|
||||
session_kind=session.session_kind,
|
||||
ticket_id=str(ticket.id),
|
||||
ticket_kind="internal",
|
||||
)
|
||||
|
||||
|
||||
@router.get("/queue", response_model=list[QueueRow])
|
||||
async def queue(
|
||||
db: Annotated[AsyncSession, Depends(get_db)],
|
||||
user: Annotated[User, Depends(require_l1_or_coverage)],
|
||||
status_filter: Optional[str] = None,
|
||||
limit: int = 50,
|
||||
):
|
||||
"""Phase 1 queue: internal tickets only. PSA-fed rows in Phase 2."""
|
||||
tickets = await internal_ticket_service.list_tickets_for_account(
|
||||
db,
|
||||
account_id=user.account_id,
|
||||
status=status_filter,
|
||||
limit=limit,
|
||||
)
|
||||
return [
|
||||
QueueRow(
|
||||
ticket_id=str(t.id),
|
||||
ticket_kind="internal",
|
||||
problem_statement=t.problem_statement,
|
||||
customer_name=t.customer_name,
|
||||
status=t.status,
|
||||
created_at=t.created_at,
|
||||
)
|
||||
for t in tickets
|
||||
]
|
||||
|
||||
|
||||
@router.get("/sessions/active", response_model=list[WalkSessionResponse])
|
||||
async def list_active_sessions(
|
||||
db: Annotated[AsyncSession, Depends(get_db)],
|
||||
user: Annotated[User, Depends(require_l1_or_coverage)],
|
||||
):
|
||||
"""The caller's currently-active sessions (for the dashboard 'Resume in progress' widget)."""
|
||||
stmt = (
|
||||
select(L1WalkSession)
|
||||
.where(L1WalkSession.created_by_user_id == user.id)
|
||||
.where(L1WalkSession.status == "active")
|
||||
.order_by(L1WalkSession.last_step_at.desc())
|
||||
.limit(20)
|
||||
)
|
||||
result = await db.execute(stmt)
|
||||
return [_to_response(s) for s in result.scalars()]
|
||||
|
||||
|
||||
@router.get("/sessions/{session_id}", response_model=WalkSessionResponse)
|
||||
async def get_session(
|
||||
session_id: UUID,
|
||||
db: Annotated[AsyncSession, Depends(get_db)],
|
||||
user: Annotated[User, Depends(require_l1_or_coverage)],
|
||||
):
|
||||
session = await _get_session_or_404(db, session_id, user)
|
||||
return _to_response(session)
|
||||
|
||||
|
||||
@router.post("/sessions/{session_id}/step", response_model=WalkSessionResponse)
|
||||
async def post_step(
|
||||
session_id: UUID,
|
||||
payload: StepRequest,
|
||||
db: Annotated[AsyncSession, Depends(get_db)],
|
||||
user: Annotated[User, Depends(require_l1_or_coverage)],
|
||||
):
|
||||
await _get_session_or_404(db, session_id, user)
|
||||
try:
|
||||
updated = await l1_session_service.record_step(
|
||||
db,
|
||||
session_id=session_id,
|
||||
node_id=payload.node_id,
|
||||
question=payload.question,
|
||||
answer=payload.answer,
|
||||
note=payload.note,
|
||||
)
|
||||
except ValueError as exc:
|
||||
raise HTTPException(status_code=http_status.HTTP_400_BAD_REQUEST, detail=str(exc))
|
||||
await db.commit()
|
||||
return _to_response(updated)
|
||||
|
||||
|
||||
@router.post("/sessions/{session_id}/notes", response_model=WalkSessionResponse)
|
||||
async def post_notes(
|
||||
session_id: UUID,
|
||||
payload: NotesRequest,
|
||||
db: Annotated[AsyncSession, Depends(get_db)],
|
||||
user: Annotated[User, Depends(require_l1_or_coverage)],
|
||||
):
|
||||
await _get_session_or_404(db, session_id, user)
|
||||
try:
|
||||
updated = await l1_session_service.update_notes(
|
||||
db,
|
||||
session_id=session_id,
|
||||
notes=payload.notes,
|
||||
)
|
||||
except ValueError as exc:
|
||||
raise HTTPException(status_code=http_status.HTTP_400_BAD_REQUEST, detail=str(exc))
|
||||
await db.commit()
|
||||
return _to_response(updated)
|
||||
|
||||
|
||||
@router.post("/sessions/{session_id}/resolve", response_model=WalkSessionResponse)
|
||||
async def post_resolve(
|
||||
session_id: UUID,
|
||||
payload: ResolveRequest,
|
||||
db: Annotated[AsyncSession, Depends(get_db)],
|
||||
user: Annotated[User, Depends(require_l1_or_coverage)],
|
||||
):
|
||||
await _get_session_or_404(db, session_id, user)
|
||||
try:
|
||||
updated = await l1_session_service.resolve(
|
||||
db,
|
||||
session_id=session_id,
|
||||
helpful=payload.helpful,
|
||||
resolution_notes=payload.resolution_notes,
|
||||
)
|
||||
except ValueError as exc:
|
||||
raise HTTPException(status_code=http_status.HTTP_400_BAD_REQUEST, detail=str(exc))
|
||||
await db.commit()
|
||||
return _to_response(updated)
|
||||
|
||||
|
||||
@router.post("/sessions/{session_id}/escalate", response_model=WalkSessionResponse)
|
||||
async def post_escalate(
|
||||
session_id: UUID,
|
||||
payload: EscalateRequest,
|
||||
db: Annotated[AsyncSession, Depends(get_db)],
|
||||
user: Annotated[User, Depends(require_l1_or_coverage)],
|
||||
):
|
||||
await _get_session_or_404(db, session_id, user)
|
||||
try:
|
||||
updated = await l1_session_service.escalate(
|
||||
db,
|
||||
session_id=session_id,
|
||||
reason=payload.reason or "",
|
||||
reason_category=payload.reason_category,
|
||||
)
|
||||
except ValueError as exc:
|
||||
raise HTTPException(status_code=http_status.HTTP_400_BAD_REQUEST, detail=str(exc))
|
||||
await db.commit()
|
||||
return _to_response(updated)
|
||||
|
||||
|
||||
@router.post("/escalate-without-walk", response_model=WalkSessionResponse)
|
||||
async def post_escalate_without_walk(
|
||||
payload: EscalateWithoutWalkRequest,
|
||||
db: Annotated[AsyncSession, Depends(get_db)],
|
||||
user: Annotated[User, Depends(require_l1_or_coverage)],
|
||||
):
|
||||
ticket = await internal_ticket_service.create_ticket(
|
||||
db,
|
||||
account_id=user.account_id,
|
||||
created_by_user_id=user.id,
|
||||
problem_statement=payload.problem_statement,
|
||||
customer_name=payload.customer_name,
|
||||
customer_contact=payload.customer_contact,
|
||||
)
|
||||
session = await l1_session_service.escalate_without_walk(
|
||||
db,
|
||||
account_id=user.account_id,
|
||||
user=user,
|
||||
ticket_id=str(ticket.id),
|
||||
ticket_kind="internal",
|
||||
reason_category=payload.reason_category,
|
||||
reason=payload.reason,
|
||||
)
|
||||
await db.commit()
|
||||
return _to_response(session)
|
||||
@@ -8,6 +8,7 @@ from app.api.deps import (
|
||||
from app.api.endpoints import (
|
||||
admin,
|
||||
admin_audit,
|
||||
l1,
|
||||
admin_categories,
|
||||
admin_dashboard,
|
||||
admin_feature_flags,
|
||||
@@ -185,3 +186,4 @@ api_router.include_router(beta_feedback.router, dependencies=_tenant_deps)
|
||||
api_router.include_router(session_branches.router, dependencies=_pro_deps)
|
||||
api_router.include_router(session_handoffs.router, dependencies=_pro_deps)
|
||||
api_router.include_router(device_types.router, dependencies=_tenant_deps)
|
||||
api_router.include_router(l1.router, dependencies=_tenant_deps)
|
||||
|
||||
72
backend/app/schemas/l1.py
Normal file
72
backend/app/schemas/l1.py
Normal file
@@ -0,0 +1,72 @@
|
||||
"""Pydantic schemas for the /l1/* endpoint surface."""
|
||||
from datetime import datetime
|
||||
from typing import Any, Literal, Optional
|
||||
from uuid import UUID
|
||||
|
||||
from pydantic import BaseModel, Field
|
||||
|
||||
|
||||
class IntakeRequest(BaseModel):
|
||||
problem_statement: str = Field(..., min_length=1)
|
||||
customer_name: Optional[str] = None
|
||||
customer_contact: Optional[str] = None
|
||||
flow_id: Optional[UUID] = None
|
||||
|
||||
|
||||
class IntakeResponse(BaseModel):
|
||||
session_id: UUID
|
||||
session_kind: Literal["flow", "proposal", "adhoc"]
|
||||
ticket_id: str
|
||||
ticket_kind: Literal["psa", "internal"]
|
||||
|
||||
|
||||
class StepRequest(BaseModel):
|
||||
node_id: str
|
||||
question: str
|
||||
answer: str
|
||||
note: Optional[str] = None
|
||||
|
||||
|
||||
class NotesRequest(BaseModel):
|
||||
notes: list[dict[str, Any]]
|
||||
|
||||
|
||||
class ResolveRequest(BaseModel):
|
||||
helpful: bool
|
||||
resolution_notes: str
|
||||
|
||||
|
||||
class EscalateRequest(BaseModel):
|
||||
reason: Optional[str] = None
|
||||
reason_category: str = Field(..., min_length=1)
|
||||
|
||||
|
||||
class EscalateWithoutWalkRequest(BaseModel):
|
||||
problem_statement: str = Field(..., min_length=1)
|
||||
customer_name: Optional[str] = None
|
||||
customer_contact: Optional[str] = None
|
||||
reason_category: str = Field(..., min_length=1)
|
||||
reason: Optional[str] = None
|
||||
|
||||
|
||||
class WalkSessionResponse(BaseModel):
|
||||
id: UUID
|
||||
session_kind: str
|
||||
flow_id: Optional[UUID]
|
||||
flow_proposal_id: Optional[UUID]
|
||||
current_node_id: Optional[str]
|
||||
walked_path: list[dict[str, Any]]
|
||||
walk_notes: list[dict[str, Any]]
|
||||
status: str
|
||||
started_at: datetime
|
||||
last_step_at: datetime
|
||||
resolved_at: Optional[datetime]
|
||||
|
||||
|
||||
class QueueRow(BaseModel):
|
||||
ticket_id: str
|
||||
ticket_kind: Literal["psa", "internal"]
|
||||
problem_statement: Optional[str] = None
|
||||
customer_name: Optional[str] = None
|
||||
status: str
|
||||
created_at: Optional[datetime] = None
|
||||
Reference in New Issue
Block a user