146 lines
5.8 KiB
Python
146 lines
5.8 KiB
Python
# [DEF:ReportsRouter:Module]
|
|
# @TIER: CRITICAL
|
|
# @SEMANTICS: api, reports, list, detail, pagination, filters
|
|
# @PURPOSE: FastAPI router for unified task report list and detail retrieval endpoints.
|
|
# @LAYER: UI (API)
|
|
# @RELATION: DEPENDS_ON -> backend.src.services.reports.report_service.ReportsService
|
|
# @RELATION: DEPENDS_ON -> backend.src.dependencies
|
|
# @INVARIANT: Endpoints are read-only and do not trigger long-running tasks.
|
|
|
|
# [SECTION: IMPORTS]
|
|
from datetime import datetime
|
|
from typing import List, Optional
|
|
|
|
from fastapi import APIRouter, Depends, HTTPException, Query, status
|
|
|
|
from ...dependencies import get_task_manager, has_permission
|
|
from ...core.task_manager import TaskManager
|
|
from ...core.logger import belief_scope
|
|
from ...models.report import ReportCollection, ReportDetailView, ReportQuery, ReportStatus, TaskType
|
|
from ...services.reports.report_service import ReportsService
|
|
# [/SECTION]
|
|
|
|
router = APIRouter(prefix="/api/reports", tags=["Reports"])
|
|
|
|
|
|
# [DEF:_parse_csv_enum_list:Function]
|
|
# @PURPOSE: Parse comma-separated query value into enum list.
|
|
# @PRE: raw may be None/empty or comma-separated values.
|
|
# @POST: Returns enum list or raises HTTP 400 with deterministic machine-readable payload.
|
|
# @PARAM: raw (Optional[str]) - Comma-separated enum values.
|
|
# @PARAM: enum_cls (type) - Enum class for validation.
|
|
# @PARAM: field_name (str) - Query field name for diagnostics.
|
|
# @RETURN: List - Parsed enum values.
|
|
def _parse_csv_enum_list(raw: Optional[str], enum_cls, field_name: str) -> List:
|
|
with belief_scope("_parse_csv_enum_list"):
|
|
if raw is None or not raw.strip():
|
|
return []
|
|
values = [item.strip() for item in raw.split(",") if item.strip()]
|
|
parsed = []
|
|
invalid = []
|
|
for value in values:
|
|
try:
|
|
parsed.append(enum_cls(value))
|
|
except ValueError:
|
|
invalid.append(value)
|
|
if invalid:
|
|
raise HTTPException(
|
|
status_code=status.HTTP_400_BAD_REQUEST,
|
|
detail={
|
|
"message": f"Invalid values for '{field_name}'",
|
|
"field": field_name,
|
|
"invalid_values": invalid,
|
|
"allowed_values": [item.value for item in enum_cls],
|
|
},
|
|
)
|
|
return parsed
|
|
# [/DEF:_parse_csv_enum_list:Function]
|
|
|
|
|
|
# [DEF:list_reports:Function]
|
|
# @PURPOSE: Return paginated unified reports list.
|
|
# @PRE: authenticated/authorized request and validated query params.
|
|
# @POST: returns {items,total,page,page_size,has_next,applied_filters}.
|
|
# @POST: deterministic error payload for invalid filters.
|
|
#
|
|
# @TEST_CONTRACT: ListReportsApi ->
|
|
# {
|
|
# required_fields: {page: int, page_size: int, sort_by: str, sort_order: str},
|
|
# optional_fields: {task_types: str, statuses: str, search: str},
|
|
# invariants: [
|
|
# "Returns ReportCollection on success",
|
|
# "Raises HTTPException 400 for invalid query parameters"
|
|
# ]
|
|
# }
|
|
# @TEST_FIXTURE: valid_list_request -> {"page": 1, "page_size": 20}
|
|
# @TEST_EDGE: invalid_task_type_filter -> raises HTTPException(400)
|
|
# @TEST_EDGE: malformed_query -> raises HTTPException(400)
|
|
# @TEST_INVARIANT: consistent_list_payload -> verifies: [valid_list_request]
|
|
@router.get("", response_model=ReportCollection)
|
|
async def list_reports(
|
|
page: int = Query(1, ge=1),
|
|
page_size: int = Query(20, ge=1, le=100),
|
|
task_types: Optional[str] = Query(None, description="Comma-separated task types"),
|
|
statuses: Optional[str] = Query(None, description="Comma-separated statuses"),
|
|
time_from: Optional[datetime] = Query(None),
|
|
time_to: Optional[datetime] = Query(None),
|
|
search: Optional[str] = Query(None, max_length=200),
|
|
sort_by: str = Query("updated_at"),
|
|
sort_order: str = Query("desc"),
|
|
task_manager: TaskManager = Depends(get_task_manager),
|
|
_=Depends(has_permission("tasks", "READ")),
|
|
):
|
|
with belief_scope("list_reports"):
|
|
try:
|
|
parsed_task_types = _parse_csv_enum_list(task_types, TaskType, "task_types")
|
|
parsed_statuses = _parse_csv_enum_list(statuses, ReportStatus, "statuses")
|
|
query = ReportQuery(
|
|
page=page,
|
|
page_size=page_size,
|
|
task_types=parsed_task_types,
|
|
statuses=parsed_statuses,
|
|
time_from=time_from,
|
|
time_to=time_to,
|
|
search=search,
|
|
sort_by=sort_by,
|
|
sort_order=sort_order,
|
|
)
|
|
except HTTPException:
|
|
raise
|
|
except Exception as exc:
|
|
raise HTTPException(
|
|
status_code=status.HTTP_400_BAD_REQUEST,
|
|
detail={
|
|
"message": "Invalid query parameters",
|
|
"code": "INVALID_REPORT_QUERY",
|
|
"reason": str(exc),
|
|
},
|
|
)
|
|
|
|
service = ReportsService(task_manager)
|
|
return service.list_reports(query)
|
|
# [/DEF:list_reports:Function]
|
|
|
|
|
|
# [DEF:get_report_detail:Function]
|
|
# @PURPOSE: Return one normalized report detail with diagnostics and next actions.
|
|
# @PRE: authenticated/authorized request and existing report_id.
|
|
# @POST: returns normalized detail envelope or 404 when report is not found.
|
|
@router.get("/{report_id}", response_model=ReportDetailView)
|
|
async def get_report_detail(
|
|
report_id: str,
|
|
task_manager: TaskManager = Depends(get_task_manager),
|
|
_=Depends(has_permission("tasks", "READ")),
|
|
):
|
|
with belief_scope("get_report_detail", f"report_id={report_id}"):
|
|
service = ReportsService(task_manager)
|
|
detail = service.get_report_detail(report_id)
|
|
if not detail:
|
|
raise HTTPException(
|
|
status_code=status.HTTP_404_NOT_FOUND,
|
|
detail={"message": "Report not found", "code": "REPORT_NOT_FOUND"},
|
|
)
|
|
return detail
|
|
# [/DEF:get_report_detail:Function]
|
|
|
|
# [/DEF:ReportsRouter:Module] |