feat: implement background task architecture for code quality scans
- Add status fields to ArchitectureScan model (status, started_at, completed_at, error_message, progress_message) - Create database migration for new status fields - Create background task function execute_code_quality_scan() - Update API to return 202 with job IDs and support polling - Add code quality scans to unified BackgroundTasksService - Integrate scans into background tasks API and page - Implement frontend polling with 3-second interval - Add progress banner showing scan status - Users can navigate away while scans run in background - Document the implementation in architecture docs 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -1,24 +1,42 @@
|
||||
"""
|
||||
Code Quality API Endpoints
|
||||
RESTful API for architecture validation and violation management
|
||||
RESTful API for code quality validation and violation management
|
||||
Supports multiple validator types: architecture, security, performance
|
||||
"""
|
||||
|
||||
from datetime import datetime
|
||||
from datetime import UTC, datetime
|
||||
from enum import Enum
|
||||
|
||||
from fastapi import APIRouter, Depends, Query
|
||||
from fastapi import APIRouter, BackgroundTasks, Depends, Query
|
||||
from pydantic import BaseModel, Field
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.api.deps import get_current_admin_api
|
||||
from app.core.database import get_db
|
||||
from app.exceptions import ViolationNotFoundException
|
||||
from app.services.code_quality_service import code_quality_service
|
||||
from app.exceptions import ScanNotFoundException, ViolationNotFoundException
|
||||
from app.services.code_quality_service import (
|
||||
VALID_VALIDATOR_TYPES,
|
||||
code_quality_service,
|
||||
)
|
||||
from app.tasks.code_quality_tasks import execute_code_quality_scan
|
||||
from models.database.architecture_scan import ArchitectureScan
|
||||
from models.database.user import User
|
||||
from models.schema.stats import CodeQualityDashboardStatsResponse
|
||||
|
||||
router = APIRouter()
|
||||
|
||||
|
||||
# Enums and Constants
|
||||
|
||||
|
||||
class ValidatorType(str, Enum):
|
||||
"""Supported validator types"""
|
||||
|
||||
ARCHITECTURE = "architecture"
|
||||
SECURITY = "security"
|
||||
PERFORMANCE = "performance"
|
||||
|
||||
|
||||
# Pydantic Models for API
|
||||
|
||||
|
||||
@@ -27,23 +45,65 @@ class ScanResponse(BaseModel):
|
||||
|
||||
id: int
|
||||
timestamp: str
|
||||
validator_type: str
|
||||
status: str
|
||||
started_at: str | None
|
||||
completed_at: str | None
|
||||
progress_message: str | None
|
||||
total_files: int
|
||||
total_violations: int
|
||||
errors: int
|
||||
warnings: int
|
||||
duration_seconds: float
|
||||
triggered_by: str
|
||||
triggered_by: str | None
|
||||
git_commit_hash: str | None
|
||||
error_message: str | None = None
|
||||
|
||||
class Config:
|
||||
from_attributes = True
|
||||
|
||||
|
||||
class ScanRequest(BaseModel):
|
||||
"""Request model for triggering scans"""
|
||||
|
||||
validator_types: list[ValidatorType] = Field(
|
||||
default=[ValidatorType.ARCHITECTURE, ValidatorType.SECURITY, ValidatorType.PERFORMANCE],
|
||||
description="Validator types to run",
|
||||
)
|
||||
|
||||
|
||||
class ScanJobResponse(BaseModel):
|
||||
"""Response model for a queued scan job"""
|
||||
|
||||
id: int
|
||||
validator_type: str
|
||||
status: str
|
||||
message: str
|
||||
|
||||
|
||||
class MultiScanJobResponse(BaseModel):
|
||||
"""Response model for multiple queued scans (background task pattern)"""
|
||||
|
||||
scans: list[ScanJobResponse]
|
||||
message: str
|
||||
status_url: str
|
||||
|
||||
|
||||
class MultiScanResponse(BaseModel):
|
||||
"""Response model for completed scans (legacy sync pattern)"""
|
||||
|
||||
scans: list[ScanResponse]
|
||||
total_violations: int
|
||||
total_errors: int
|
||||
total_warnings: int
|
||||
|
||||
|
||||
class ViolationResponse(BaseModel):
|
||||
"""Response model for a violation"""
|
||||
|
||||
id: int
|
||||
scan_id: int
|
||||
validator_type: str
|
||||
rule_id: str
|
||||
rule_name: str
|
||||
severity: str
|
||||
@@ -111,37 +171,124 @@ class AddCommentRequest(BaseModel):
|
||||
# API Endpoints
|
||||
|
||||
|
||||
@router.post("/scan", response_model=ScanResponse)
|
||||
async def trigger_scan(
|
||||
db: Session = Depends(get_db), current_user: User = Depends(get_current_admin_api)
|
||||
):
|
||||
"""
|
||||
Trigger a new architecture scan
|
||||
|
||||
Requires authentication. Runs the validator script and stores results.
|
||||
Domain exceptions (ScanTimeoutException, ScanParseException) bubble up to global handler.
|
||||
"""
|
||||
scan = code_quality_service.run_scan(
|
||||
db, triggered_by=f"manual:{current_user.username}"
|
||||
)
|
||||
db.commit()
|
||||
|
||||
def _scan_to_response(scan: ArchitectureScan) -> ScanResponse:
|
||||
"""Convert ArchitectureScan to ScanResponse."""
|
||||
return ScanResponse(
|
||||
id=scan.id,
|
||||
timestamp=scan.timestamp.isoformat(),
|
||||
total_files=scan.total_files,
|
||||
total_violations=scan.total_violations,
|
||||
errors=scan.errors,
|
||||
warnings=scan.warnings,
|
||||
duration_seconds=scan.duration_seconds,
|
||||
timestamp=scan.timestamp.isoformat() if scan.timestamp else None,
|
||||
validator_type=scan.validator_type,
|
||||
status=scan.status,
|
||||
started_at=scan.started_at.isoformat() if scan.started_at else None,
|
||||
completed_at=scan.completed_at.isoformat() if scan.completed_at else None,
|
||||
progress_message=scan.progress_message,
|
||||
total_files=scan.total_files or 0,
|
||||
total_violations=scan.total_violations or 0,
|
||||
errors=scan.errors or 0,
|
||||
warnings=scan.warnings or 0,
|
||||
duration_seconds=scan.duration_seconds or 0.0,
|
||||
triggered_by=scan.triggered_by,
|
||||
git_commit_hash=scan.git_commit_hash,
|
||||
error_message=scan.error_message,
|
||||
)
|
||||
|
||||
|
||||
@router.post("/scan", response_model=MultiScanJobResponse, status_code=202)
|
||||
async def trigger_scan(
|
||||
request: ScanRequest = None,
|
||||
background_tasks: BackgroundTasks = None,
|
||||
db: Session = Depends(get_db),
|
||||
current_user: User = Depends(get_current_admin_api),
|
||||
):
|
||||
"""
|
||||
Trigger code quality scan(s) as background tasks.
|
||||
|
||||
By default runs all validators. Specify validator_types to run specific validators.
|
||||
Returns immediately with job IDs. Poll /scan/{scan_id}/status for progress.
|
||||
|
||||
Scans run asynchronously - users can browse other pages while scans execute.
|
||||
"""
|
||||
if request is None:
|
||||
request = ScanRequest()
|
||||
|
||||
scan_jobs = []
|
||||
triggered_by = f"manual:{current_user.username}"
|
||||
|
||||
for vtype in request.validator_types:
|
||||
# Create scan record with pending status
|
||||
scan = ArchitectureScan(
|
||||
timestamp=datetime.now(UTC),
|
||||
validator_type=vtype.value,
|
||||
status="pending",
|
||||
triggered_by=triggered_by,
|
||||
)
|
||||
db.add(scan)
|
||||
db.flush() # Get scan.id
|
||||
|
||||
# Queue background task
|
||||
background_tasks.add_task(execute_code_quality_scan, scan.id)
|
||||
|
||||
scan_jobs.append(
|
||||
ScanJobResponse(
|
||||
id=scan.id,
|
||||
validator_type=vtype.value,
|
||||
status="pending",
|
||||
message=f"{vtype.value.capitalize()} scan queued",
|
||||
)
|
||||
)
|
||||
|
||||
db.commit()
|
||||
|
||||
validator_names = ", ".join(vtype.value for vtype in request.validator_types)
|
||||
return MultiScanJobResponse(
|
||||
scans=scan_jobs,
|
||||
message=f"Scans queued for: {validator_names}",
|
||||
status_url="/admin/code-quality/scans/running",
|
||||
)
|
||||
|
||||
|
||||
@router.get("/scans/{scan_id}/status", response_model=ScanResponse)
|
||||
async def get_scan_status(
|
||||
scan_id: int,
|
||||
db: Session = Depends(get_db),
|
||||
current_user: User = Depends(get_current_admin_api),
|
||||
):
|
||||
"""
|
||||
Get status of a specific scan.
|
||||
|
||||
Use this endpoint to poll for scan completion.
|
||||
"""
|
||||
scan = db.query(ArchitectureScan).filter(ArchitectureScan.id == scan_id).first()
|
||||
if not scan:
|
||||
raise ScanNotFoundException(scan_id)
|
||||
|
||||
return _scan_to_response(scan)
|
||||
|
||||
|
||||
@router.get("/scans/running", response_model=list[ScanResponse])
|
||||
async def get_running_scans(
|
||||
db: Session = Depends(get_db),
|
||||
current_user: User = Depends(get_current_admin_api),
|
||||
):
|
||||
"""
|
||||
Get all currently running scans.
|
||||
|
||||
Returns scans with status 'pending' or 'running'.
|
||||
"""
|
||||
scans = (
|
||||
db.query(ArchitectureScan)
|
||||
.filter(ArchitectureScan.status.in_(["pending", "running"]))
|
||||
.order_by(ArchitectureScan.timestamp.desc())
|
||||
.all()
|
||||
)
|
||||
return [_scan_to_response(scan) for scan in scans]
|
||||
|
||||
|
||||
@router.get("/scans", response_model=list[ScanResponse])
|
||||
async def list_scans(
|
||||
limit: int = Query(30, ge=1, le=100, description="Number of scans to return"),
|
||||
validator_type: ValidatorType | None = Query(
|
||||
None, description="Filter by validator type"
|
||||
),
|
||||
db: Session = Depends(get_db),
|
||||
current_user: User = Depends(get_current_admin_api),
|
||||
):
|
||||
@@ -149,23 +296,13 @@ async def list_scans(
|
||||
Get scan history
|
||||
|
||||
Returns recent scans for trend analysis.
|
||||
Optionally filter by validator type.
|
||||
"""
|
||||
scans = code_quality_service.get_scan_history(db, limit=limit)
|
||||
scans = code_quality_service.get_scan_history(
|
||||
db, limit=limit, validator_type=validator_type.value if validator_type else None
|
||||
)
|
||||
|
||||
return [
|
||||
ScanResponse(
|
||||
id=scan.id,
|
||||
timestamp=scan.timestamp.isoformat(),
|
||||
total_files=scan.total_files,
|
||||
total_violations=scan.total_violations,
|
||||
errors=scan.errors,
|
||||
warnings=scan.warnings,
|
||||
duration_seconds=scan.duration_seconds,
|
||||
triggered_by=scan.triggered_by,
|
||||
git_commit_hash=scan.git_commit_hash,
|
||||
)
|
||||
for scan in scans
|
||||
]
|
||||
return [_scan_to_response(scan) for scan in scans]
|
||||
|
||||
|
||||
@router.get("/violations", response_model=ViolationListResponse)
|
||||
@@ -173,8 +310,11 @@ async def list_violations(
|
||||
scan_id: int | None = Query(
|
||||
None, description="Filter by scan ID (defaults to latest)"
|
||||
),
|
||||
validator_type: ValidatorType | None = Query(
|
||||
None, description="Filter by validator type"
|
||||
),
|
||||
severity: str | None = Query(
|
||||
None, description="Filter by severity (error, warning)"
|
||||
None, description="Filter by severity (error, warning, info)"
|
||||
),
|
||||
status: str | None = Query(
|
||||
None, description="Filter by status (open, assigned, resolved, ignored)"
|
||||
@@ -191,13 +331,15 @@ async def list_violations(
|
||||
"""
|
||||
Get violations with filtering and pagination
|
||||
|
||||
Returns violations from latest scan by default.
|
||||
Returns violations from latest scan(s) by default.
|
||||
Filter by validator_type to get violations from a specific validator.
|
||||
"""
|
||||
offset = (page - 1) * page_size
|
||||
|
||||
violations, total = code_quality_service.get_violations(
|
||||
db,
|
||||
scan_id=scan_id,
|
||||
validator_type=validator_type.value if validator_type else None,
|
||||
severity=severity,
|
||||
status=status,
|
||||
rule_id=rule_id,
|
||||
@@ -213,6 +355,7 @@ async def list_violations(
|
||||
ViolationResponse(
|
||||
id=v.id,
|
||||
scan_id=v.scan_id,
|
||||
validator_type=v.validator_type,
|
||||
rule_id=v.rule_id,
|
||||
rule_name=v.rule_name,
|
||||
severity=v.severity,
|
||||
@@ -280,6 +423,7 @@ async def get_violation(
|
||||
return ViolationDetailResponse(
|
||||
id=violation.id,
|
||||
scan_id=violation.scan_id,
|
||||
validator_type=violation.validator_type,
|
||||
rule_id=violation.rule_id,
|
||||
rule_name=violation.rule_name,
|
||||
severity=violation.severity,
|
||||
@@ -429,7 +573,11 @@ async def add_comment(
|
||||
|
||||
@router.get("/stats", response_model=CodeQualityDashboardStatsResponse)
|
||||
async def get_dashboard_stats(
|
||||
db: Session = Depends(get_db), current_user: User = Depends(get_current_admin_api)
|
||||
validator_type: ValidatorType | None = Query(
|
||||
None, description="Filter by validator type (returns combined stats if not specified)"
|
||||
),
|
||||
db: Session = Depends(get_db),
|
||||
current_user: User = Depends(get_current_admin_api),
|
||||
):
|
||||
"""
|
||||
Get dashboard statistics
|
||||
@@ -440,7 +588,32 @@ async def get_dashboard_stats(
|
||||
- Trend data (last 7 scans)
|
||||
- Top violating files
|
||||
- Violations by rule and module
|
||||
- Per-validator breakdown
|
||||
|
||||
When validator_type is specified, returns stats for that type only.
|
||||
When not specified, returns combined stats across all validators.
|
||||
"""
|
||||
stats = code_quality_service.get_dashboard_stats(db)
|
||||
stats = code_quality_service.get_dashboard_stats(
|
||||
db, validator_type=validator_type.value if validator_type else None
|
||||
)
|
||||
|
||||
return CodeQualityDashboardStatsResponse(**stats)
|
||||
|
||||
|
||||
@router.get("/validator-types")
|
||||
async def get_validator_types(
|
||||
current_user: User = Depends(get_current_admin_api),
|
||||
):
|
||||
"""
|
||||
Get list of available validator types
|
||||
|
||||
Returns the supported validator types for filtering.
|
||||
"""
|
||||
return {
|
||||
"validator_types": VALID_VALIDATOR_TYPES,
|
||||
"descriptions": {
|
||||
"architecture": "Architectural patterns and code organization rules",
|
||||
"security": "Security vulnerabilities and best practices",
|
||||
"performance": "Performance issues and optimizations",
|
||||
},
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user