diff --git a/.kilocode/rules/specify-rules.md b/.kilocode/rules/specify-rules.md index 2b8292b..6525a8c 100644 --- a/.kilocode/rules/specify-rules.md +++ b/.kilocode/rules/specify-rules.md @@ -41,6 +41,8 @@ Auto-generated from all feature plans. Last updated: 2025-12-19 - SQLite (existing `tasks.db` for results, `auth.db` for permissions, `mappings.db` or new `plugins.db` for provider config/metadata) (017-llm-analysis-plugin) - Python 3.9+ (Backend), Node.js 18+ (Frontend) + FastAPI, SvelteKit, Tailwind CSS, SQLAlchemy, WebSocket (existing) (019-superset-ux-redesign) - SQLite (tasks.db, auth.db, migrations.db) - no new database tables required (019-superset-ux-redesign) +- Python 3.9+ (backend), Node.js 18+ (frontend) + FastAPI, SvelteKit, Tailwind CSS, SQLAlchemy/Pydantic task models, existing task/websocket stack (020-task-reports-design) +- SQLite task/result persistence (existing task DB), filesystem only for existing artifacts (no new primary store required) (020-task-reports-design) - Python 3.9+ (Backend), Node.js 18+ (Frontend Build) (001-plugin-arch-svelte-ui) @@ -61,9 +63,9 @@ cd src; pytest; ruff check . Python 3.9+ (Backend), Node.js 18+ (Frontend Build): Follow standard conventions ## Recent Changes +- 020-task-reports-design: Added Python 3.9+ (backend), Node.js 18+ (frontend) + FastAPI, SvelteKit, Tailwind CSS, SQLAlchemy/Pydantic task models, existing task/websocket stack - 019-superset-ux-redesign: Added Python 3.9+ (Backend), Node.js 18+ (Frontend) + FastAPI, SvelteKit, Tailwind CSS, SQLAlchemy, WebSocket (existing) - 017-llm-analysis-plugin: Added Python 3.9+ (Backend), Node.js 18+ (Frontend) -- 016-multi-user-auth: Added Python 3.9+ (Backend), Node.js 18+ (Frontend) diff --git a/backend/src/api/routes/__init__.py b/backend/src/api/routes/__init__.py index f857bc1..22420a3 100755 --- a/backend/src/api/routes/__init__.py +++ b/backend/src/api/routes/__init__.py @@ -1,7 +1,7 @@ # Lazy loading of route modules to avoid import issues in tests # This allows tests to import routes without triggering all module imports -__all__ = ['plugins', 'tasks', 'settings', 'connections', 'environments', 'mappings', 'migration', 'git', 'storage', 'admin'] +__all__ = ['plugins', 'tasks', 'settings', 'connections', 'environments', 'mappings', 'migration', 'git', 'storage', 'admin', 'reports'] def __getattr__(name): if name in __all__: diff --git a/backend/src/api/routes/reports.py b/backend/src/api/routes/reports.py new file mode 100644 index 0000000..dca69f8 --- /dev/null +++ b/backend/src/api/routes/reports.py @@ -0,0 +1,131 @@ +# [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: + 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. +@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] \ No newline at end of file diff --git a/backend/src/app.py b/backend/src/app.py index 9f586fc..cd445be 100755 --- a/backend/src/app.py +++ b/backend/src/app.py @@ -21,7 +21,7 @@ import asyncio from .dependencies import get_task_manager, get_scheduler_service from .core.utils.network import NetworkError from .core.logger import logger, belief_scope -from .api.routes import plugins, tasks, settings, environments, mappings, migration, connections, git, storage, admin, llm, dashboards, datasets +from .api.routes import plugins, tasks, settings, environments, mappings, migration, connections, git, storage, admin, llm, dashboards, datasets, reports from .api import auth # [DEF:App:Global] @@ -123,6 +123,7 @@ app.include_router(llm.router, prefix="/api/llm", tags=["LLM"]) app.include_router(storage.router, prefix="/api/storage", tags=["Storage"]) app.include_router(dashboards.router) app.include_router(datasets.router) +app.include_router(reports.router) # [DEF:api.include_routers:Action] diff --git a/backend/src/models/report.py b/backend/src/models/report.py new file mode 100644 index 0000000..ebbfdff --- /dev/null +++ b/backend/src/models/report.py @@ -0,0 +1,128 @@ +# [DEF:backend.src.models.report:Module] +# @TIER: CRITICAL +# @SEMANTICS: reports, models, pydantic, normalization, pagination +# @PURPOSE: Canonical report schemas for unified task reporting across heterogeneous task types. +# @LAYER: Domain +# @RELATION: DEPENDS_ON -> backend.src.core.task_manager.models +# @INVARIANT: Canonical report fields are always present for every report item. + +# [SECTION: IMPORTS] +from datetime import datetime +from enum import Enum +from typing import Any, Dict, List, Optional + +from pydantic import BaseModel, Field, field_validator, model_validator +# [/SECTION] + + +# [DEF:TaskType:Class] +# @PURPOSE: Supported normalized task report types. +class TaskType(str, Enum): + LLM_VERIFICATION = "llm_verification" + BACKUP = "backup" + MIGRATION = "migration" + DOCUMENTATION = "documentation" + UNKNOWN = "unknown" +# [/DEF:TaskType:Class] + + +# [DEF:ReportStatus:Class] +# @PURPOSE: Supported normalized report status values. +class ReportStatus(str, Enum): + SUCCESS = "success" + FAILED = "failed" + IN_PROGRESS = "in_progress" + PARTIAL = "partial" +# [/DEF:ReportStatus:Class] + + +# [DEF:ErrorContext:Class] +# @PURPOSE: Error and recovery context for failed/partial reports. +class ErrorContext(BaseModel): + code: Optional[str] = None + message: str + next_actions: List[str] = Field(default_factory=list) +# [/DEF:ErrorContext:Class] + + +# [DEF:TaskReport:Class] +# @PURPOSE: Canonical normalized report envelope for one task execution. +class TaskReport(BaseModel): + report_id: str + task_id: str + task_type: TaskType + status: ReportStatus + started_at: Optional[datetime] = None + updated_at: datetime + summary: str + details: Optional[Dict[str, Any]] = None + error_context: Optional[ErrorContext] = None + source_ref: Optional[Dict[str, Any]] = None + + @field_validator("report_id", "task_id", "summary") + @classmethod + def _non_empty_str(cls, value: str) -> str: + if not isinstance(value, str) or not value.strip(): + raise ValueError("Value must be a non-empty string") + return value.strip() +# [/DEF:TaskReport:Class] + + +# [DEF:ReportQuery:Class] +# @PURPOSE: Query object for server-side report filtering, sorting, and pagination. +class ReportQuery(BaseModel): + page: int = Field(default=1, ge=1) + page_size: int = Field(default=20, ge=1, le=100) + task_types: List[TaskType] = Field(default_factory=list) + statuses: List[ReportStatus] = Field(default_factory=list) + time_from: Optional[datetime] = None + time_to: Optional[datetime] = None + search: Optional[str] = Field(default=None, max_length=200) + sort_by: str = Field(default="updated_at") + sort_order: str = Field(default="desc") + + @field_validator("sort_by") + @classmethod + def _validate_sort_by(cls, value: str) -> str: + allowed = {"updated_at", "status", "task_type"} + if value not in allowed: + raise ValueError(f"sort_by must be one of: {', '.join(sorted(allowed))}") + return value + + @field_validator("sort_order") + @classmethod + def _validate_sort_order(cls, value: str) -> str: + if value not in {"asc", "desc"}: + raise ValueError("sort_order must be 'asc' or 'desc'") + return value + + @model_validator(mode="after") + def _validate_time_range(self): + if self.time_from and self.time_to and self.time_from > self.time_to: + raise ValueError("time_from must be less than or equal to time_to") + return self +# [/DEF:ReportQuery:Class] + + +# [DEF:ReportCollection:Class] +# @PURPOSE: Paginated collection of normalized task reports. +class ReportCollection(BaseModel): + items: List[TaskReport] + total: int = Field(ge=0) + page: int = Field(ge=1) + page_size: int = Field(ge=1) + has_next: bool + applied_filters: ReportQuery +# [/DEF:ReportCollection:Class] + + +# [DEF:ReportDetailView:Class] +# @PURPOSE: Detailed report representation including diagnostics and recovery actions. +class ReportDetailView(BaseModel): + report: TaskReport + timeline: List[Dict[str, Any]] = Field(default_factory=list) + diagnostics: Optional[Dict[str, Any]] = None + next_actions: List[str] = Field(default_factory=list) +# [/DEF:ReportDetailView:Class] + +# [/DEF:backend.src.models.report:Module] \ No newline at end of file diff --git a/backend/src/services/reports/normalizer.py b/backend/src/services/reports/normalizer.py new file mode 100644 index 0000000..b643d79 --- /dev/null +++ b/backend/src/services/reports/normalizer.py @@ -0,0 +1,152 @@ +# [DEF:backend.src.services.reports.normalizer:Module] +# @TIER: CRITICAL +# @SEMANTICS: reports, normalization, tasks, fallback +# @PURPOSE: Convert task manager task objects into canonical unified TaskReport entities with deterministic fallback behavior. +# @LAYER: Domain +# @RELATION: DEPENDS_ON -> backend.src.core.task_manager.models.Task +# @RELATION: DEPENDS_ON -> backend.src.models.report +# @RELATION: DEPENDS_ON -> backend.src.services.reports.type_profiles +# @INVARIANT: Unknown task types and partial payloads remain visible via fallback mapping. + +# [SECTION: IMPORTS] +from datetime import datetime +from typing import Any, Dict, Optional + +from ...core.task_manager.models import Task, TaskStatus +from ...models.report import ErrorContext, ReportStatus, TaskReport +from .type_profiles import get_type_profile, resolve_task_type +# [/SECTION] + + +# [DEF:status_to_report_status:Function] +# @PURPOSE: Normalize internal task status to canonical report status. +# @PRE: status may be known or unknown string/enum value. +# @POST: Always returns one of canonical ReportStatus values. +# @PARAM: status (Any) - Internal task status value. +# @RETURN: ReportStatus - Canonical report status. +def status_to_report_status(status: Any) -> ReportStatus: + raw = str(status.value if isinstance(status, TaskStatus) else status).upper() + if raw == TaskStatus.SUCCESS.value: + return ReportStatus.SUCCESS + if raw == TaskStatus.FAILED.value: + return ReportStatus.FAILED + if raw in {TaskStatus.PENDING.value, TaskStatus.RUNNING.value, TaskStatus.AWAITING_INPUT.value, TaskStatus.AWAITING_MAPPING.value}: + return ReportStatus.IN_PROGRESS + return ReportStatus.PARTIAL +# [/DEF:status_to_report_status:Function] + + +# [DEF:build_summary:Function] +# @PURPOSE: Build deterministic user-facing summary from task payload and status. +# @PRE: report_status is canonical; plugin_id may be unknown. +# @POST: Returns non-empty summary text. +# @PARAM: task (Task) - Source task object. +# @PARAM: report_status (ReportStatus) - Canonical status. +# @RETURN: str - Normalized summary. +def build_summary(task: Task, report_status: ReportStatus) -> str: + result = task.result + if isinstance(result, dict): + for key in ("summary", "message", "status_message", "description"): + value = result.get(key) + if isinstance(value, str) and value.strip(): + return value.strip() + if report_status == ReportStatus.SUCCESS: + return "Task completed successfully" + if report_status == ReportStatus.FAILED: + return "Task failed" + if report_status == ReportStatus.IN_PROGRESS: + return "Task is in progress" + return "Task completed with partial data" +# [/DEF:build_summary:Function] + + +# [DEF:extract_error_context:Function] +# @PURPOSE: Extract normalized error context and next actions for failed/partial reports. +# @PRE: task is a valid Task object. +# @POST: Returns ErrorContext for failed/partial when context exists; otherwise None. +# @PARAM: task (Task) - Source task. +# @PARAM: report_status (ReportStatus) - Canonical status. +# @RETURN: Optional[ErrorContext] - Error context block. +def extract_error_context(task: Task, report_status: ReportStatus) -> Optional[ErrorContext]: + if report_status not in {ReportStatus.FAILED, ReportStatus.PARTIAL}: + return None + + result = task.result if isinstance(task.result, dict) else {} + message = None + code = None + next_actions = [] + + if isinstance(result.get("error"), dict): + error_obj = result.get("error", {}) + message = error_obj.get("message") or message + code = error_obj.get("code") or code + actions = error_obj.get("next_actions") + if isinstance(actions, list): + next_actions = [str(action) for action in actions if str(action).strip()] + + if not message: + message = result.get("error_message") if isinstance(result.get("error_message"), str) else None + + if not message: + for log in reversed(task.logs): + if str(log.level).upper() == "ERROR" and log.message: + message = log.message + break + + if not message: + message = "Not provided" + + if not next_actions: + next_actions = ["Review task diagnostics", "Retry the operation"] + + return ErrorContext(code=code, message=message, next_actions=next_actions) +# [/DEF:extract_error_context:Function] + + +# [DEF:normalize_task_report:Function] +# @PURPOSE: Convert one Task to canonical TaskReport envelope. +# @PRE: task has valid id and plugin_id fields. +# @POST: Returns TaskReport with required fields and deterministic fallback behavior. +# @PARAM: task (Task) - Source task. +# @RETURN: TaskReport - Canonical normalized report. +def normalize_task_report(task: Task) -> TaskReport: + task_type = resolve_task_type(task.plugin_id) + report_status = status_to_report_status(task.status) + profile = get_type_profile(task_type) + + started_at = task.started_at if isinstance(task.started_at, datetime) else None + updated_at = task.finished_at if isinstance(task.finished_at, datetime) else None + if not updated_at: + updated_at = started_at or datetime.utcnow() + + details: Dict[str, Any] = { + "profile": { + "display_label": profile.get("display_label"), + "visual_variant": profile.get("visual_variant"), + "icon_token": profile.get("icon_token"), + "emphasis_rules": profile.get("emphasis_rules", []), + }, + "result": task.result if task.result is not None else {"note": "Not provided"}, + } + + source_ref: Dict[str, Any] = {} + if isinstance(task.params, dict): + for key in ("environment_id", "source_env_id", "target_env_id", "dashboard_id", "dataset_id", "resource_id"): + if key in task.params: + source_ref[key] = task.params.get(key) + + return TaskReport( + report_id=task.id, + task_id=task.id, + task_type=task_type, + status=report_status, + started_at=started_at, + updated_at=updated_at, + summary=build_summary(task, report_status), + details=details, + error_context=extract_error_context(task, report_status), + source_ref=source_ref or None, + ) +# [/DEF:normalize_task_report:Function] + +# [/DEF:backend.src.services.reports.normalizer:Module] \ No newline at end of file diff --git a/backend/src/services/reports/report_service.py b/backend/src/services/reports/report_service.py new file mode 100644 index 0000000..022f325 --- /dev/null +++ b/backend/src/services/reports/report_service.py @@ -0,0 +1,148 @@ +# [DEF:backend.src.services.reports.report_service:Module] +# @TIER: CRITICAL +# @SEMANTICS: reports, service, aggregation, filtering, pagination, detail +# @PURPOSE: Aggregate, normalize, filter, and paginate task reports for unified list/detail API use cases. +# @LAYER: Domain +# @RELATION: DEPENDS_ON -> backend.src.core.task_manager.manager.TaskManager +# @RELATION: DEPENDS_ON -> backend.src.models.report +# @RELATION: DEPENDS_ON -> backend.src.services.reports.normalizer +# @INVARIANT: List responses are deterministic and include applied filter echo metadata. + +# [SECTION: IMPORTS] +from datetime import datetime +from typing import List, Optional + +from ...core.task_manager import TaskManager +from ...models.report import ReportCollection, ReportDetailView, ReportQuery, ReportStatus, TaskReport, TaskType +from .normalizer import normalize_task_report +# [/SECTION] + + +# [DEF:ReportsService:Class] +# @PURPOSE: Service layer for list/detail report retrieval and normalization. +# @TIER: CRITICAL +# @PRE: TaskManager dependency is initialized. +# @POST: Provides deterministic list/detail report responses. +class ReportsService: + # [DEF:__init__:Function] + # @PURPOSE: Initialize service with TaskManager dependency. + # @PARAM: task_manager (TaskManager) - Task manager providing source task history. + def __init__(self, task_manager: TaskManager): + self.task_manager = task_manager + # [/DEF:__init__:Function] + + # [DEF:_load_normalized_reports:Function] + # @PURPOSE: Build normalized reports from all available tasks. + # @RETURN: List[TaskReport] - Reports sorted later by list logic. + def _load_normalized_reports(self) -> List[TaskReport]: + tasks = self.task_manager.get_all_tasks() + reports = [normalize_task_report(task) for task in tasks] + return reports + # [/DEF:_load_normalized_reports:Function] + + # [DEF:_matches_query:Function] + # @PURPOSE: Apply query filtering to a report. + # @PARAM: report (TaskReport) - Candidate report. + # @PARAM: query (ReportQuery) - Applied query. + # @RETURN: bool - True if report matches all filters. + def _matches_query(self, report: TaskReport, query: ReportQuery) -> bool: + if query.task_types and report.task_type not in query.task_types: + return False + if query.statuses and report.status not in query.statuses: + return False + if query.time_from and report.updated_at < query.time_from: + return False + if query.time_to and report.updated_at > query.time_to: + return False + if query.search: + needle = query.search.lower() + haystack = f"{report.summary} {report.task_type.value} {report.status.value}".lower() + if needle not in haystack: + return False + return True + # [/DEF:_matches_query:Function] + + # [DEF:_sort_reports:Function] + # @PURPOSE: Sort reports deterministically according to query settings. + # @PARAM: reports (List[TaskReport]) - Filtered reports. + # @PARAM: query (ReportQuery) - Sort config. + # @RETURN: List[TaskReport] - Sorted reports. + def _sort_reports(self, reports: List[TaskReport], query: ReportQuery) -> List[TaskReport]: + reverse = query.sort_order == "desc" + + if query.sort_by == "status": + reports.sort(key=lambda item: item.status.value, reverse=reverse) + elif query.sort_by == "task_type": + reports.sort(key=lambda item: item.task_type.value, reverse=reverse) + else: + reports.sort(key=lambda item: item.updated_at, reverse=reverse) + + return reports + # [/DEF:_sort_reports:Function] + + # [DEF:list_reports:Function] + # @PURPOSE: Return filtered, sorted, paginated report collection. + # @PRE: query has passed schema validation. + # @POST: Returns {items,total,page,page_size,has_next,applied_filters}. + # @PARAM: query (ReportQuery) - List filters and pagination. + # @RETURN: ReportCollection - Paginated unified reports payload. + def list_reports(self, query: ReportQuery) -> ReportCollection: + reports = self._load_normalized_reports() + filtered = [report for report in reports if self._matches_query(report, query)] + sorted_reports = self._sort_reports(filtered, query) + + total = len(sorted_reports) + start = (query.page - 1) * query.page_size + end = start + query.page_size + items = sorted_reports[start:end] + has_next = end < total + + return ReportCollection( + items=items, + total=total, + page=query.page, + page_size=query.page_size, + has_next=has_next, + applied_filters=query, + ) + # [/DEF:list_reports:Function] + + # [DEF:get_report_detail:Function] + # @PURPOSE: Return one normalized report with timeline/diagnostics/next actions. + # @PRE: report_id exists in normalized report set. + # @POST: Returns normalized detail envelope with diagnostics and next actions where applicable. + # @PARAM: report_id (str) - Stable report identifier. + # @RETURN: Optional[ReportDetailView] - Detailed report or None if not found. + def get_report_detail(self, report_id: str) -> Optional[ReportDetailView]: + reports = self._load_normalized_reports() + target = next((report for report in reports if report.report_id == report_id), None) + if not target: + return None + + timeline = [] + if target.started_at: + timeline.append({"event": "started", "at": target.started_at.isoformat()}) + timeline.append({"event": "updated", "at": target.updated_at.isoformat()}) + + diagnostics = target.details or {} + if not diagnostics: + diagnostics = {"note": "Not provided"} + if target.error_context: + diagnostics["error_context"] = target.error_context.model_dump() + + next_actions = [] + if target.error_context and target.error_context.next_actions: + next_actions = target.error_context.next_actions + elif target.status in {ReportStatus.FAILED, ReportStatus.PARTIAL}: + next_actions = ["Review diagnostics", "Retry task if applicable"] + + return ReportDetailView( + report=target, + timeline=timeline, + diagnostics=diagnostics, + next_actions=next_actions, + ) + # [/DEF:get_report_detail:Function] +# [/DEF:ReportsService:Class] + +# [/DEF:backend.src.services.reports.report_service:Module] \ No newline at end of file diff --git a/backend/src/services/reports/type_profiles.py b/backend/src/services/reports/type_profiles.py new file mode 100644 index 0000000..9346cd9 --- /dev/null +++ b/backend/src/services/reports/type_profiles.py @@ -0,0 +1,91 @@ +# [DEF:backend.src.services.reports.type_profiles:Module] +# @TIER: CRITICAL +# @SEMANTICS: reports, type_profiles, normalization, fallback +# @PURPOSE: Deterministic mapping of plugin/task identifiers to canonical report task types and fallback profile metadata. +# @LAYER: Domain +# @RELATION: DEPENDS_ON -> backend.src.models.report.TaskType +# @INVARIANT: Unknown input always resolves to TaskType.UNKNOWN with a single fallback profile. + +# [SECTION: IMPORTS] +from typing import Any, Dict, Optional + +from ...models.report import TaskType +# [/SECTION] + +# [DEF:PLUGIN_TO_TASK_TYPE:Data] +# @PURPOSE: Maps plugin identifiers to normalized report task types. +PLUGIN_TO_TASK_TYPE: Dict[str, TaskType] = { + "llm_dashboard_validation": TaskType.LLM_VERIFICATION, + "superset-backup": TaskType.BACKUP, + "superset-migration": TaskType.MIGRATION, + "documentation": TaskType.DOCUMENTATION, +} +# [/DEF:PLUGIN_TO_TASK_TYPE:Data] + +# [DEF:TASK_TYPE_PROFILES:Data] +# @PURPOSE: Profile metadata registry for each normalized task type. +TASK_TYPE_PROFILES: Dict[TaskType, Dict[str, Any]] = { + TaskType.LLM_VERIFICATION: { + "display_label": "LLM Verification", + "visual_variant": "llm", + "icon_token": "sparkles", + "emphasis_rules": ["summary", "status", "next_actions"], + "fallback": False, + }, + TaskType.BACKUP: { + "display_label": "Backup", + "visual_variant": "backup", + "icon_token": "archive", + "emphasis_rules": ["summary", "status", "updated_at"], + "fallback": False, + }, + TaskType.MIGRATION: { + "display_label": "Migration", + "visual_variant": "migration", + "icon_token": "shuffle", + "emphasis_rules": ["summary", "status", "error_context"], + "fallback": False, + }, + TaskType.DOCUMENTATION: { + "display_label": "Documentation", + "visual_variant": "documentation", + "icon_token": "file-text", + "emphasis_rules": ["summary", "status", "details"], + "fallback": False, + }, + TaskType.UNKNOWN: { + "display_label": "Other / Unknown", + "visual_variant": "unknown", + "icon_token": "help-circle", + "emphasis_rules": ["summary", "status"], + "fallback": True, + }, +} +# [/DEF:TASK_TYPE_PROFILES:Data] + + +# [DEF:resolve_task_type:Function] +# @PURPOSE: Resolve canonical task type from plugin/task identifier with guaranteed fallback. +# @PRE: plugin_id may be None or unknown. +# @POST: Always returns one of TaskType enum values. +# @PARAM: plugin_id (Optional[str]) - Source plugin/task identifier from task record. +# @RETURN: TaskType - Resolved canonical type or UNKNOWN fallback. +def resolve_task_type(plugin_id: Optional[str]) -> TaskType: + normalized = (plugin_id or "").strip() + if not normalized: + return TaskType.UNKNOWN + return PLUGIN_TO_TASK_TYPE.get(normalized, TaskType.UNKNOWN) +# [/DEF:resolve_task_type:Function] + + +# [DEF:get_type_profile:Function] +# @PURPOSE: Return deterministic profile metadata for a task type. +# @PRE: task_type may be known or unknown. +# @POST: Returns a profile dict and never raises for unknown types. +# @PARAM: task_type (TaskType) - Canonical task type. +# @RETURN: Dict[str, Any] - Profile metadata used by normalization and UI contracts. +def get_type_profile(task_type: TaskType) -> Dict[str, Any]: + return TASK_TYPE_PROFILES.get(task_type, TASK_TYPE_PROFILES[TaskType.UNKNOWN]) +# [/DEF:get_type_profile:Function] + +# [/DEF:backend.src.services.reports.type_profiles:Module] \ No newline at end of file diff --git a/backend/tests/fixtures/reports/fixtures_reports.json b/backend/tests/fixtures/reports/fixtures_reports.json new file mode 100644 index 0000000..de56907 --- /dev/null +++ b/backend/tests/fixtures/reports/fixtures_reports.json @@ -0,0 +1,81 @@ +{ + "mixed_task_reports": { + "description": "Mixed reports across all supported task types", + "items": [ + { + "report_id": "rep-001", + "task_id": "task-001", + "task_type": "llm_verification", + "status": "success", + "started_at": "2026-02-22T09:00:00Z", + "updated_at": "2026-02-22T09:00:30Z", + "summary": "LLM verification completed", + "details": { + "checks_performed": 12, + "issues_found": 1 + } + }, + { + "report_id": "rep-002", + "task_id": "task-002", + "task_type": "backup", + "status": "failed", + "started_at": "2026-02-22T09:10:00Z", + "updated_at": "2026-02-22T09:11:00Z", + "summary": "Backup failed due to storage limit", + "error_context": { + "message": "Not enough disk space", + "next_actions": ["Free storage", "Retry backup"] + } + }, + { + "report_id": "rep-003", + "task_id": "task-003", + "task_type": "migration", + "status": "in_progress", + "started_at": "2026-02-22T09:20:00Z", + "updated_at": "2026-02-22T09:21:00Z", + "summary": "Migration running", + "details": { + "progress_percent": 42 + } + }, + { + "report_id": "rep-004", + "task_id": "task-004", + "task_type": "documentation", + "status": "partial", + "started_at": "2026-02-22T09:30:00Z", + "updated_at": "2026-02-22T09:31:00Z", + "summary": "Documentation generated with partial coverage", + "error_context": { + "message": "Missing metadata for 3 columns", + "next_actions": ["Review missing metadata"] + } + } + ] + }, + "unknown_type_partial_payload": { + "description": "Unknown type and partial payload fallback coverage", + "items": [ + { + "report_id": "rep-unknown-001", + "task_id": "task-unknown-001", + "task_type": "unknown", + "status": "failed", + "updated_at": "2026-02-22T10:00:00Z", + "summary": "Unknown task type failed", + "details": null + }, + { + "report_id": "rep-partial-001", + "task_id": "task-partial-001", + "task_type": "backup", + "status": "success", + "updated_at": "2026-02-22T10:05:00Z", + "summary": "Backup completed", + "details": {} + } + ] + } +} \ No newline at end of file diff --git a/backend/tests/test_report_normalizer.py b/backend/tests/test_report_normalizer.py new file mode 100644 index 0000000..98d3681 --- /dev/null +++ b/backend/tests/test_report_normalizer.py @@ -0,0 +1,51 @@ +# [DEF:backend.tests.test_report_normalizer:Module] +# @TIER: CRITICAL +# @SEMANTICS: tests, reports, normalizer, fallback +# @PURPOSE: Validate unknown task type fallback and partial payload normalization behavior. +# @LAYER: Domain (Tests) +# @RELATION: TESTS -> backend.src.services.reports.normalizer +# @INVARIANT: Unknown plugin types are mapped to canonical unknown task type. + +from datetime import datetime + +from src.core.task_manager.models import Task, TaskStatus +from src.services.reports.normalizer import normalize_task_report + + +def test_unknown_type_maps_to_unknown_profile(): + task = Task( + id="unknown-1", + plugin_id="custom-unmapped-plugin", + status=TaskStatus.FAILED, + started_at=datetime.utcnow(), + finished_at=datetime.utcnow(), + params={}, + result={"error_message": "Unexpected plugin payload"}, + ) + + report = normalize_task_report(task) + + assert report.task_type.value == "unknown" + assert report.summary + assert report.error_context is not None + + +def test_partial_payload_keeps_report_visible_with_placeholders(): + task = Task( + id="partial-1", + plugin_id="superset-backup", + status=TaskStatus.SUCCESS, + started_at=datetime.utcnow(), + finished_at=datetime.utcnow(), + params={}, + result=None, + ) + + report = normalize_task_report(task) + + assert report.task_type.value == "backup" + assert report.details is not None + assert "result" in report.details + + +# [/DEF:backend.tests.test_report_normalizer:Module] \ No newline at end of file diff --git a/backend/tests/test_reports_api.py b/backend/tests/test_reports_api.py new file mode 100644 index 0000000..36ec309 --- /dev/null +++ b/backend/tests/test_reports_api.py @@ -0,0 +1,117 @@ +# [DEF:backend.tests.test_reports_api:Module] +# @TIER: CRITICAL +# @SEMANTICS: tests, reports, api, contract, pagination, filtering +# @PURPOSE: Contract tests for GET /api/reports defaults, pagination, and filtering behavior. +# @LAYER: Domain (Tests) +# @RELATION: TESTS -> backend.src.api.routes.reports +# @INVARIANT: API response contract contains {items,total,page,page_size,has_next,applied_filters}. + +from datetime import datetime, timedelta +from types import SimpleNamespace + +from fastapi.testclient import TestClient + +from src.app import app +from src.core.task_manager.models import Task, TaskStatus +from src.dependencies import get_current_user, get_task_manager + + +class _FakeTaskManager: + def __init__(self, tasks): + self._tasks = tasks + + def get_all_tasks(self): + return self._tasks + + +def _admin_user(): + admin_role = SimpleNamespace(name="Admin", permissions=[]) + return SimpleNamespace(username="test-admin", roles=[admin_role]) + + +def _make_task(task_id: str, plugin_id: str, status: TaskStatus, started_at: datetime, finished_at: datetime = None, result=None): + return Task( + id=task_id, + plugin_id=plugin_id, + status=status, + started_at=started_at, + finished_at=finished_at, + params={"environment_id": "env-1"}, + result=result or {"summary": f"{plugin_id} {status.value.lower()}"}, + ) + + +def test_get_reports_default_pagination_contract(): + now = datetime.utcnow() + tasks = [ + _make_task("t-1", "superset-backup", TaskStatus.SUCCESS, now - timedelta(minutes=10), now - timedelta(minutes=9)), + _make_task("t-2", "superset-migration", TaskStatus.FAILED, now - timedelta(minutes=8), now - timedelta(minutes=7)), + _make_task("t-3", "llm_dashboard_validation", TaskStatus.RUNNING, now - timedelta(minutes=6), None), + ] + + app.dependency_overrides[get_current_user] = lambda: _admin_user() + app.dependency_overrides[get_task_manager] = lambda: _FakeTaskManager(tasks) + + try: + client = TestClient(app) + response = client.get("/api/reports") + assert response.status_code == 200 + + data = response.json() + assert set(["items", "total", "page", "page_size", "has_next", "applied_filters"]).issubset(data.keys()) + assert data["page"] == 1 + assert data["page_size"] == 20 + assert data["total"] == 3 + assert isinstance(data["items"], list) + assert data["applied_filters"]["sort_by"] == "updated_at" + assert data["applied_filters"]["sort_order"] == "desc" + finally: + app.dependency_overrides.clear() + + +def test_get_reports_filter_and_pagination(): + now = datetime.utcnow() + tasks = [ + _make_task("t-1", "superset-backup", TaskStatus.SUCCESS, now - timedelta(minutes=30), now - timedelta(minutes=29)), + _make_task("t-2", "superset-backup", TaskStatus.FAILED, now - timedelta(minutes=20), now - timedelta(minutes=19)), + _make_task("t-3", "superset-migration", TaskStatus.FAILED, now - timedelta(minutes=10), now - timedelta(minutes=9)), + ] + + app.dependency_overrides[get_current_user] = lambda: _admin_user() + app.dependency_overrides[get_task_manager] = lambda: _FakeTaskManager(tasks) + + try: + client = TestClient(app) + response = client.get("/api/reports?task_types=backup&statuses=failed&page=1&page_size=1") + assert response.status_code == 200 + + data = response.json() + assert data["total"] == 1 + assert data["page"] == 1 + assert data["page_size"] == 1 + assert data["has_next"] is False + assert len(data["items"]) == 1 + assert data["items"][0]["task_type"] == "backup" + assert data["items"][0]["status"] == "failed" + finally: + app.dependency_overrides.clear() + + +def test_get_reports_invalid_filter_returns_400(): + now = datetime.utcnow() + tasks = [_make_task("t-1", "superset-backup", TaskStatus.SUCCESS, now - timedelta(minutes=5), now - timedelta(minutes=4))] + + app.dependency_overrides[get_current_user] = lambda: _admin_user() + app.dependency_overrides[get_task_manager] = lambda: _FakeTaskManager(tasks) + + try: + client = TestClient(app) + response = client.get("/api/reports?task_types=bad_type") + assert response.status_code == 400 + body = response.json() + assert "detail" in body + finally: + app.dependency_overrides.clear() + + +# [/DEF:backend.tests.test_reports_api:Module] \ No newline at end of file diff --git a/backend/tests/test_reports_detail_api.py b/backend/tests/test_reports_detail_api.py new file mode 100644 index 0000000..e3c464d --- /dev/null +++ b/backend/tests/test_reports_detail_api.py @@ -0,0 +1,83 @@ +# [DEF:backend.tests.test_reports_detail_api:Module] +# @TIER: CRITICAL +# @SEMANTICS: tests, reports, api, detail, diagnostics +# @PURPOSE: Contract tests for GET /api/reports/{report_id} detail endpoint behavior. +# @LAYER: Domain (Tests) +# @RELATION: TESTS -> backend.src.api.routes.reports + +from datetime import datetime, timedelta +from types import SimpleNamespace + +from fastapi.testclient import TestClient + +from src.app import app +from src.core.task_manager.models import Task, TaskStatus +from src.dependencies import get_current_user, get_task_manager + + +class _FakeTaskManager: + def __init__(self, tasks): + self._tasks = tasks + + def get_all_tasks(self): + return self._tasks + + +def _admin_user(): + role = SimpleNamespace(name="Admin", permissions=[]) + return SimpleNamespace(username="test-admin", roles=[role]) + + +def _make_task(task_id: str, plugin_id: str, status: TaskStatus, result=None): + now = datetime.utcnow() + return Task( + id=task_id, + plugin_id=plugin_id, + status=status, + started_at=now - timedelta(minutes=2), + finished_at=now - timedelta(minutes=1) if status != TaskStatus.RUNNING else None, + params={"environment_id": "env-1"}, + result=result or {"summary": f"{plugin_id} result"}, + ) + + +def test_get_report_detail_success(): + task = _make_task( + "detail-1", + "superset-migration", + TaskStatus.FAILED, + result={"error": {"message": "Step failed", "next_actions": ["Check mapping", "Retry"]}}, + ) + + app.dependency_overrides[get_current_user] = lambda: _admin_user() + app.dependency_overrides[get_task_manager] = lambda: _FakeTaskManager([task]) + + try: + client = TestClient(app) + response = client.get("/api/reports/detail-1") + assert response.status_code == 200 + + data = response.json() + assert "report" in data + assert data["report"]["report_id"] == "detail-1" + assert "diagnostics" in data + assert "next_actions" in data + finally: + app.dependency_overrides.clear() + + +def test_get_report_detail_not_found(): + task = _make_task("detail-2", "superset-backup", TaskStatus.SUCCESS) + + app.dependency_overrides[get_current_user] = lambda: _admin_user() + app.dependency_overrides[get_task_manager] = lambda: _FakeTaskManager([task]) + + try: + client = TestClient(app) + response = client.get("/api/reports/unknown-id") + assert response.status_code == 404 + finally: + app.dependency_overrides.clear() + + +# [/DEF:backend.tests.test_reports_detail_api:Module] \ No newline at end of file diff --git a/backend/tests/test_reports_openapi_conformance.py b/backend/tests/test_reports_openapi_conformance.py new file mode 100644 index 0000000..2c11ae7 --- /dev/null +++ b/backend/tests/test_reports_openapi_conformance.py @@ -0,0 +1,81 @@ +# [DEF:backend.tests.test_reports_openapi_conformance:Module] +# @TIER: CRITICAL +# @SEMANTICS: tests, reports, openapi, conformance +# @PURPOSE: Validate implemented reports payload shape against OpenAPI-required top-level contract fields. +# @LAYER: Domain (Tests) +# @RELATION: TESTS -> specs/020-task-reports-design/contracts/reports-api.openapi.yaml +# @INVARIANT: List and detail payloads include required contract keys. + +from datetime import datetime +from types import SimpleNamespace + +from fastapi.testclient import TestClient + +from src.app import app +from src.core.task_manager.models import Task, TaskStatus +from src.dependencies import get_current_user, get_task_manager + + +class _FakeTaskManager: + def __init__(self, tasks): + self._tasks = tasks + + def get_all_tasks(self): + return self._tasks + + +def _admin_user(): + role = SimpleNamespace(name="Admin", permissions=[]) + return SimpleNamespace(username="test-admin", roles=[role]) + + +def _task(task_id: str, plugin_id: str, status: TaskStatus): + now = datetime.utcnow() + return Task( + id=task_id, + plugin_id=plugin_id, + status=status, + started_at=now, + finished_at=now if status != TaskStatus.RUNNING else None, + params={"environment_id": "env-1"}, + result={"summary": f"{plugin_id} {status.value.lower()}"}, + ) + + +def test_reports_list_openapi_required_keys(): + tasks = [ + _task("r-1", "superset-backup", TaskStatus.SUCCESS), + _task("r-2", "superset-migration", TaskStatus.FAILED), + ] + app.dependency_overrides[get_current_user] = lambda: _admin_user() + app.dependency_overrides[get_task_manager] = lambda: _FakeTaskManager(tasks) + + try: + client = TestClient(app) + response = client.get("/api/reports") + assert response.status_code == 200 + + body = response.json() + required = {"items", "total", "page", "page_size", "has_next", "applied_filters"} + assert required.issubset(body.keys()) + finally: + app.dependency_overrides.clear() + + +def test_reports_detail_openapi_required_keys(): + tasks = [_task("r-3", "llm_dashboard_validation", TaskStatus.SUCCESS)] + app.dependency_overrides[get_current_user] = lambda: _admin_user() + app.dependency_overrides[get_task_manager] = lambda: _FakeTaskManager(tasks) + + try: + client = TestClient(app) + response = client.get("/api/reports/r-3") + assert response.status_code == 200 + + body = response.json() + assert "report" in body + finally: + app.dependency_overrides.clear() + + +# [/DEF:backend.tests.test_reports_openapi_conformance:Module] \ No newline at end of file diff --git a/docs/design/resource_centric_layout.md b/docs/design/resource_centric_layout.md index b9247a2..186bdb6 100644 --- a/docs/design/resource_centric_layout.md +++ b/docs/design/resource_centric_layout.md @@ -17,10 +17,11 @@ The application moves from a **Task-Centric** model (where users navigate to "Mi `[Home] [Migration] [Git Manager] [Mapper] [Settings] [Logout]` **New Menu:** -`[Superset Manager] [Dashboards] [Datasets] [Storage] | [Activity (0)] [Settings] [User]` +`[Superset Manager] [Dashboards] [Datasets] [Reports] [Storage] | [Activity (0)] [Settings] [User]` * **Dashboards**: Main hub for all dashboard operations (Migrate, Backup, Git). * **Datasets**: Hub for dataset documentation and mapping. +* **Reports**: Unified center for all task outcomes with type-distinct visual profiles and detail diagnostics. * **Storage**: File management (Backups, Repositories). * **Activity**: Global indicator of running tasks. Clicking it opens the Task Drawer. diff --git a/docs/settings.md b/docs/settings.md index ab73cfa..c82cb19 100644 --- a/docs/settings.md +++ b/docs/settings.md @@ -39,6 +39,23 @@ The settings API is available at `/settings`: The settings page is located at `frontend/src/pages/Settings.svelte`. It provides forms for managing global settings and Superset environments. +## Reports Center + +Unified reports are available at [`/reports`](frontend/src/routes/reports/+page.svelte) and use the backend API at [`/api/reports`](backend/src/api/routes/reports.py) and [`/api/reports/{report_id}`](backend/src/api/routes/reports.py). + +### What operators can do + +- View all task outcomes (LLM verification, backup, migration, documentation) in one list. +- Filter by type and status. +- Open report detail with diagnostics and recommended next actions. +- Continue working even for unknown task types and partial payloads (explicit placeholders are shown instead of hidden data). + +### Troubleshooting + +- If report list is empty, verify tasks exist and clear filters. +- If report detail is not found (404), confirm the selected report still exists in task history. +- If report API tests fail during local execution with database connectivity errors, ensure the configured DB is reachable or run in an environment with available test DB services. + ## Integration Existing plugins and utilities use the `ConfigManager` to fetch configuration: diff --git a/frontend/src/components/TaskList.svelte b/frontend/src/components/TaskList.svelte index a57c928..45dd543 100644 --- a/frontend/src/components/TaskList.svelte +++ b/frontend/src/components/TaskList.svelte @@ -14,6 +14,7 @@ let { tasks = [], loading = false, + selectedTaskId = null, } = $props(); @@ -54,8 +55,8 @@ // @PURPOSE: Dispatches a select event when a task is clicked. // @PRE: taskId is provided. // @POST: 'select' event is dispatched with task ID. - function handleTaskClick(taskId: string) { - dispatch('select', { id: taskId }); + function handleTaskClick(task: any) { + dispatch('select', { id: task.id, task }); } // [/DEF:handleTaskClick:Function] @@ -70,8 +71,8 @@ {#each tasks as task (task.id)}
  • + {$t.nav?.tasks || "Tasks"} + + + @@ -318,4 +331,3 @@ - diff --git a/frontend/src/lib/components/layout/__tests__/test_breadcrumbs.svelte.js b/frontend/src/lib/components/layout/__tests__/test_breadcrumbs.svelte.js new file mode 100644 index 0000000..47c4f0f --- /dev/null +++ b/frontend/src/lib/components/layout/__tests__/test_breadcrumbs.svelte.js @@ -0,0 +1,105 @@ +// [DEF:__tests__/test_breadcrumbs:Module] +// @TIER: STANDARD +// @PURPOSE: Contract-focused unit tests for Breadcrumbs.svelte logic and UX annotations +// @LAYER: UI +// @RELATION: VERIFIES -> frontend/src/lib/components/layout/Breadcrumbs.svelte + +import { describe, it, expect } from 'vitest'; +import fs from 'node:fs'; +import path from 'node:path'; + +const COMPONENT_PATH = path.resolve( + process.cwd(), + 'src/lib/components/layout/Breadcrumbs.svelte' +); + +function getBreadcrumbs(pathname, maxVisible = 3) { + const segments = pathname.split('/').filter(Boolean); + const allItems = [{ label: 'Home', path: '/' }]; + + let currentPath = ''; + segments.forEach((segment, index) => { + currentPath += `/${segment}`; + const label = formatBreadcrumbLabel(segment); + allItems.push({ + label, + path: currentPath, + isLast: index === segments.length - 1 + }); + }); + + if (allItems.length > maxVisible) { + const firstItem = allItems[0]; + const itemsToShow = []; + itemsToShow.push(firstItem); + itemsToShow.push({ isEllipsis: true }); + + const startFromIndex = allItems.length - (maxVisible - 1); + for (let i = startFromIndex; i < allItems.length; i++) { + itemsToShow.push(allItems[i]); + } + return itemsToShow; + } + + return allItems; +} + +function formatBreadcrumbLabel(segment) { + const specialCases = { + dashboards: 'Dashboards', + datasets: 'Datasets', + storage: 'Storage', + admin: 'Admin', + settings: 'Settings', + git: 'Git' + }; + + if (specialCases[segment]) { + return specialCases[segment]; + } + + return segment + .split('-') + .map((word) => word.charAt(0).toUpperCase() + word.slice(1)) + .join(' '); +} + +describe('Breadcrumbs Component Contract & Logic', () => { + it('contains required UX tags and semantic header for STANDARD module', () => { + const source = fs.readFileSync(COMPONENT_PATH, 'utf-8'); + + expect(source).toContain('@TIER: STANDARD'); + expect(source).toContain('@UX_STATE: Idle'); + expect(source).toContain('@UX_FEEDBACK'); + expect(source).toContain('@UX_RECOVERY'); + expect(source).toContain('@RELATION: DEPENDS_ON -> page store'); + }); + + it('returns Home for root path (Short-Path UX state)', () => { + const result = getBreadcrumbs('/', 3); + + expect(result).toEqual([{ label: 'Home', path: '/' }]); + }); + + it('maps known segments to expected labels', () => { + expect(formatBreadcrumbLabel('dashboards')).toBe('Dashboards'); + expect(formatBreadcrumbLabel('datasets')).toBe('Datasets'); + expect(formatBreadcrumbLabel('settings')).toBe('Settings'); + }); + + it('formats unknown kebab-case segment to title case', () => { + expect(formatBreadcrumbLabel('data-quality-rules')).toBe('Data Quality Rules'); + }); + + it('truncates long paths with ellipsis and keeps tail segments', () => { + const result = getBreadcrumbs('/dashboards/segment-a/segment-b/segment-c', 3); + + expect(result[0]).toEqual({ label: 'Home', path: '/' }); + expect(result[1]).toEqual({ isEllipsis: true }); + const lastItem = result[result.length - 1]; + expect('label' in lastItem && lastItem.label).toBe('Segment C'); + expect(result.length).toBe(4); + }); +}); + +// [/DEF:__tests__/test_breadcrumbs:Module] \ No newline at end of file diff --git a/frontend/src/lib/components/reports/ReportCard.svelte b/frontend/src/lib/components/reports/ReportCard.svelte new file mode 100644 index 0000000..c91f0d7 --- /dev/null +++ b/frontend/src/lib/components/reports/ReportCard.svelte @@ -0,0 +1,63 @@ + + + + + + \ No newline at end of file diff --git a/frontend/src/lib/components/reports/ReportDetailPanel.svelte b/frontend/src/lib/components/reports/ReportDetailPanel.svelte new file mode 100644 index 0000000..69573a1 --- /dev/null +++ b/frontend/src/lib/components/reports/ReportDetailPanel.svelte @@ -0,0 +1,66 @@ + + + +
    +

    {$t.reports?.view_details || 'View details'}

    + + {#if !detail || !detail.report} +

    {$t.reports?.not_provided || 'Not provided'}

    + {:else} +
    +

    ID: {notProvided(detail.report.report_id)}

    +

    Type: {notProvided(detail.report.task_type)}

    +

    Status: {notProvided(detail.report.status)}

    +

    Summary: {notProvided(detail.report.summary)}

    +

    Updated: {formatDate(detail.report.updated_at)}

    +
    + +
    +

    Diagnostics

    + 
    {JSON.stringify(detail.diagnostics || { note: $t.reports?.not_provided || 'Not provided' }, null, 2)}
    +
    + + {#if (detail.next_actions && detail.next_actions.length > 0) || (detail.report.error_context && detail.report.error_context.next_actions && detail.report.error_context.next_actions.length > 0)} +
    +

    Next actions

    +
      + {#each (detail.next_actions && detail.next_actions.length > 0 ? detail.next_actions : detail.report.error_context.next_actions) as action} +
    • {action}
      • + {/each} +
    +
    + {/if} + {/if} +
    + + \ No newline at end of file diff --git a/frontend/src/lib/components/reports/ReportsList.svelte b/frontend/src/lib/components/reports/ReportsList.svelte new file mode 100644 index 0000000..c775fd4 --- /dev/null +++ b/frontend/src/lib/components/reports/ReportsList.svelte @@ -0,0 +1,37 @@ + + + +
    + {#each reports as report (report.report_id)} + + {/each} +
    + + \ No newline at end of file diff --git a/frontend/src/lib/components/reports/__tests__/fixtures/reports.fixtures.js b/frontend/src/lib/components/reports/__tests__/fixtures/reports.fixtures.js new file mode 100644 index 0000000..3a85da5 --- /dev/null +++ b/frontend/src/lib/components/reports/__tests__/fixtures/reports.fixtures.js @@ -0,0 +1,90 @@ +// [DEF:reports.fixtures:Module] +// @TIER: STANDARD +// @SEMANTICS: reports, fixtures, test-data +// @PURPOSE: Shared frontend fixtures for unified reports states. +// @LAYER: UI + +export const mixedTaskReports = [ + { + report_id: "rep-001", + task_id: "task-001", + task_type: "llm_verification", + status: "success", + started_at: "2026-02-22T09:00:00Z", + updated_at: "2026-02-22T09:00:30Z", + summary: "LLM verification completed", + details: { checks_performed: 12, issues_found: 1 } + }, + { + report_id: "rep-002", + task_id: "task-002", + task_type: "backup", + status: "failed", + started_at: "2026-02-22T09:10:00Z", + updated_at: "2026-02-22T09:11:00Z", + summary: "Backup failed due to storage limit", + error_context: { message: "Not enough disk space", next_actions: ["Free storage", "Retry backup"] } + }, + { + report_id: "rep-003", + task_id: "task-003", + task_type: "migration", + status: "in_progress", + started_at: "2026-02-22T09:20:00Z", + updated_at: "2026-02-22T09:21:00Z", + summary: "Migration running", + details: { progress_percent: 42 } + }, + { + report_id: "rep-004", + task_id: "task-004", + task_type: "documentation", + status: "partial", + started_at: "2026-02-22T09:30:00Z", + updated_at: "2026-02-22T09:31:00Z", + summary: "Documentation generated with partial coverage", + error_context: { message: "Missing metadata for 3 columns", next_actions: ["Review missing metadata"] } + } +]; + +export const unknownTypePartialPayload = [ + { + report_id: "rep-unknown-001", + task_id: "task-unknown-001", + task_type: "unknown", + status: "failed", + updated_at: "2026-02-22T10:00:00Z", + summary: "Unknown task type failed", + details: null + }, + { + report_id: "rep-partial-001", + task_id: "task-partial-001", + task_type: "backup", + status: "success", + updated_at: "2026-02-22T10:05:00Z", + summary: "Backup completed", + details: {} + } +]; + +export const reportCollections = { + ready: { + items: mixedTaskReports, + total: mixedTaskReports.length, + page: 1, + page_size: 20, + has_next: false, + applied_filters: { page: 1, page_size: 20, sort_by: "updated_at", sort_order: "desc" } + }, + empty: { + items: [], + total: 0, + page: 1, + page_size: 20, + has_next: false, + applied_filters: { page: 1, page_size: 20, sort_by: "updated_at", sort_order: "desc" } + } +}; + +// [/DEF:reports.fixtures:Module] \ No newline at end of file diff --git a/frontend/src/lib/components/reports/__tests__/report_detail.integration.test.js b/frontend/src/lib/components/reports/__tests__/report_detail.integration.test.js new file mode 100644 index 0000000..5d2bdf0 --- /dev/null +++ b/frontend/src/lib/components/reports/__tests__/report_detail.integration.test.js @@ -0,0 +1,45 @@ +// [DEF:frontend.src.lib.components.reports.__tests__.report_detail.integration:Module] +// @TIER: CRITICAL +// @SEMANTICS: tests, reports, detail, recovery-guidance, integration +// @PURPOSE: Validate detail-panel behavior for failed reports and recovery guidance visibility. +// @LAYER: UI (Tests) +// @RELATION: TESTS -> frontend/src/lib/components/reports/ReportDetailPanel.svelte +// @RELATION: TESTS -> frontend/src/routes/reports/+page.svelte +// @INVARIANT: Failed report detail exposes actionable next actions when available. + +import { describe, it, expect } from 'vitest'; +import { mixedTaskReports } from './fixtures/reports.fixtures.js'; + +function buildFailedDetailFixture() { + const failed = mixedTaskReports.find((item) => item.status === 'failed'); + return { + report: failed, + diagnostics: { + error_context: failed?.error_context || { message: 'Not provided', next_actions: [] } + }, + next_actions: failed?.error_context?.next_actions || [] + }; +} + +describe('report detail integration - failed report guidance', () => { + it('failed fixture includes error context and next actions', () => { + const detail = buildFailedDetailFixture(); + + expect(detail.report).toBeTruthy(); + expect(detail.report.status).toBe('failed'); + expect(detail.diagnostics).toBeTruthy(); + expect(Array.isArray(detail.next_actions)).toBe(true); + expect(detail.next_actions.length).toBeGreaterThan(0); + }); + + it('next actions are human-readable strings for operator recovery', () => { + const detail = buildFailedDetailFixture(); + + for (const action of detail.next_actions) { + expect(typeof action).toBe('string'); + expect(action.trim().length).toBeGreaterThan(0); + } + }); +}); + +// [/DEF:frontend.src.lib.components.reports.__tests__.report_detail.integration:Module] \ No newline at end of file diff --git a/frontend/src/lib/components/reports/__tests__/report_type_profiles.test.js b/frontend/src/lib/components/reports/__tests__/report_type_profiles.test.js new file mode 100644 index 0000000..d239e77 --- /dev/null +++ b/frontend/src/lib/components/reports/__tests__/report_type_profiles.test.js @@ -0,0 +1,32 @@ +// [DEF:frontend.src.lib.components.reports.__tests__.report_type_profiles:Module] +// @TIER: CRITICAL +// @SEMANTICS: tests, reports, type-profiles, fallback +// @PURPOSE: Validate report type profile mapping and unknown fallback behavior. +// @LAYER: UI (Tests) +// @RELATION: TESTS -> frontend/src/lib/components/reports/reportTypeProfiles.js +// @INVARIANT: Unknown task_type always resolves to the fallback profile. + +import { describe, it, expect } from 'vitest'; +import { getReportTypeProfile, REPORT_TYPE_PROFILES } from '../reportTypeProfiles.js'; + +describe('report type profiles', () => { + it('returns dedicated profiles for known task types', () => { + expect(getReportTypeProfile('llm_verification').key).toBe('llm_verification'); + expect(getReportTypeProfile('backup').key).toBe('backup'); + expect(getReportTypeProfile('migration').key).toBe('migration'); + expect(getReportTypeProfile('documentation').key).toBe('documentation'); + }); + + it('returns fallback profile for unknown task type', () => { + const profile = getReportTypeProfile('something_new'); + expect(profile.key).toBe('unknown'); + expect(profile.fallback).toBe(true); + }); + + it('contains exactly one fallback profile in registry', () => { + const fallbackCount = Object.values(REPORT_TYPE_PROFILES).filter((p) => p.fallback === true).length; + expect(fallbackCount).toBe(1); + }); +}); + +// [/DEF:frontend.src.lib.components.reports.__tests__.report_type_profiles:Module] \ No newline at end of file diff --git a/frontend/src/lib/components/reports/__tests__/reports_filter_performance.test.js b/frontend/src/lib/components/reports/__tests__/reports_filter_performance.test.js new file mode 100644 index 0000000..ad1a2fc --- /dev/null +++ b/frontend/src/lib/components/reports/__tests__/reports_filter_performance.test.js @@ -0,0 +1,48 @@ +// [DEF:frontend.src.lib.components.reports.__tests__.reports_filter_performance:Module] +// @TIER: STANDARD +// @SEMANTICS: tests, reports, performance, filtering +// @PURPOSE: Guard test for report filter responsiveness on moderate in-memory dataset. +// @LAYER: UI (Tests) +// @RELATION: TESTS -> frontend/src/routes/reports/+page.svelte + +import { describe, it, expect } from 'vitest'; + +function applyFilters(items, { taskType = 'all', status = 'all' } = {}) { + return items.filter((item) => { + const typeMatch = taskType === 'all' || item.task_type === taskType; + const statusMatch = status === 'all' || item.status === status; + return typeMatch && statusMatch; + }); +} + +function makeDataset(size = 2000) { + const taskTypes = ['llm_verification', 'backup', 'migration', 'documentation']; + const statuses = ['success', 'failed', 'in_progress', 'partial']; + const out = []; + for (let i = 0; i < size; i += 1) { + out.push({ + report_id: `r-${i}`, + task_id: `t-${i}`, + task_type: taskTypes[i % taskTypes.length], + status: statuses[i % statuses.length], + summary: `Report ${i}`, + updated_at: '2026-02-22T10:00:00Z' + }); + } + return out; +} + +describe('reports filter performance guard', () => { + it('applies task_type+status filter quickly on 2000 records', () => { + const dataset = makeDataset(2000); + + const start = Date.now(); + const result = applyFilters(dataset, { taskType: 'migration', status: 'failed' }); + const duration = Date.now() - start; + + expect(Array.isArray(result)).toBe(true); + expect(duration).toBeLessThan(100); + }); +}); + +// [/DEF:frontend.src.lib.components.reports.__tests__.reports_filter_performance:Module] \ No newline at end of file diff --git a/frontend/src/lib/components/reports/__tests__/reports_page.integration.test.js b/frontend/src/lib/components/reports/__tests__/reports_page.integration.test.js new file mode 100644 index 0000000..02601b1 --- /dev/null +++ b/frontend/src/lib/components/reports/__tests__/reports_page.integration.test.js @@ -0,0 +1,40 @@ +// [DEF:frontend.src.lib.components.reports.__tests__.reports_page.integration:Module] +// @TIER: CRITICAL +// @SEMANTICS: tests, reports, integration, mixed-types, rendering +// @PURPOSE: Integration-style checks for unified mixed-type reports rendering expectations. +// @LAYER: UI (Tests) +// @RELATION: TESTS -> frontend/src/routes/reports/+page.svelte +// @RELATION: TESTS -> frontend/src/lib/components/reports/ReportsList.svelte +// @INVARIANT: Mixed fixture includes all supported report types in one list. + +import { describe, it, expect } from 'vitest'; +import { mixedTaskReports } from './fixtures/reports.fixtures.js'; + +function collectVisibleTypeLabels(items) { + return items.map((item) => item.task_type); +} + +describe('Reports page integration - unified mixed type rendering', () => { + it('contains mixed reports from all primary task types in one payload', () => { + const labels = collectVisibleTypeLabels(mixedTaskReports); + + expect(labels).toContain('llm_verification'); + expect(labels).toContain('backup'); + expect(labels).toContain('migration'); + expect(labels).toContain('documentation'); + expect(mixedTaskReports.length).toBeGreaterThanOrEqual(4); + }); + + it('ensures canonical minimum fields are present for each report item', () => { + for (const report of mixedTaskReports) { + expect(typeof report.report_id).toBe('string'); + expect(typeof report.task_id).toBe('string'); + expect(typeof report.task_type).toBe('string'); + expect(typeof report.status).toBe('string'); + expect(typeof report.summary).toBe('string'); + expect(report.updated_at).toBeTruthy(); + } + }); +}); + +// [/DEF:frontend.src.lib.components.reports.__tests__.reports_page.integration:Module] \ No newline at end of file diff --git a/frontend/src/lib/components/reports/reportTypeProfiles.js b/frontend/src/lib/components/reports/reportTypeProfiles.js new file mode 100644 index 0000000..8a54da4 --- /dev/null +++ b/frontend/src/lib/components/reports/reportTypeProfiles.js @@ -0,0 +1,59 @@ +// [DEF:frontend.src.lib.components.reports.reportTypeProfiles:Module] +// @TIER: CRITICAL +// @SEMANTICS: reports, ui, profiles, fallback, mapping +// @PURPOSE: Deterministic mapping from report task_type to visual profile with one fallback. +// @LAYER: UI +// @RELATION: DEPENDS_ON -> frontend/src/lib/i18n/index.ts +// @INVARIANT: Unknown type always resolves to fallback profile. + +import { _ } from '$lib/i18n'; + +export const REPORT_TYPE_PROFILES = { + llm_verification: { + key: 'llm_verification', + label: 'LLM', + variant: 'bg-violet-100 text-violet-700', + icon: 'sparkles', + fallback: false + }, + backup: { + key: 'backup', + label: () => _('nav.backups'), + variant: 'bg-emerald-100 text-emerald-700', + icon: 'archive', + fallback: false + }, + migration: { + key: 'migration', + label: () => _('nav.migration'), + variant: 'bg-amber-100 text-amber-700', + icon: 'shuffle', + fallback: false + }, + documentation: { + key: 'documentation', + label: 'Documentation', + variant: 'bg-sky-100 text-sky-700', + icon: 'file-text', + fallback: false + }, + unknown: { + key: 'unknown', + label: () => _('reports.unknown_type'), + variant: 'bg-slate-100 text-slate-700', + icon: 'help-circle', + fallback: true + } +}; + +// [DEF:getReportTypeProfile:Function] +// @PURPOSE: Resolve visual profile by task type with guaranteed fallback. +// @PRE: taskType may be known/unknown/empty. +// @POST: Returns one profile object. +export function getReportTypeProfile(taskType) { + const key = typeof taskType === 'string' ? taskType : 'unknown'; + return REPORT_TYPE_PROFILES[key] || REPORT_TYPE_PROFILES.unknown; +} +// [/DEF:getReportTypeProfile:Function] + +// [/DEF:frontend.src.lib.components.reports.reportTypeProfiles:Module] \ No newline at end of file diff --git a/frontend/src/lib/i18n/locales/en.json b/frontend/src/lib/i18n/locales/en.json index 91042f5..ce9e03c 100644 --- a/frontend/src/lib/i18n/locales/en.json +++ b/frontend/src/lib/i18n/locales/en.json @@ -25,6 +25,7 @@ "migration": "Migration", "git": "Git", "tasks": "Tasks", + "reports": "Reports", "settings": "Settings", "tools": "Tools", "tools_search": "Dataset Search", @@ -179,6 +180,14 @@ "view_task": "View task", "empty": "No dashboards found" }, + "reports": { + "title": "Reports", + "empty": "No reports available.", + "filtered_empty": "No reports match your filters.", + "unknown_type": "Other / Unknown Type", + "not_provided": "Not provided", + "view_details": "View details" + }, "datasets": { "empty": "No datasets found", "table_name": "Table Name", diff --git a/frontend/src/lib/i18n/locales/ru.json b/frontend/src/lib/i18n/locales/ru.json index 6a67e6a..97b3d4f 100644 --- a/frontend/src/lib/i18n/locales/ru.json +++ b/frontend/src/lib/i18n/locales/ru.json @@ -25,6 +25,7 @@ "migration": "Миграция", "git": "Git", "tasks": "Задачи", + "reports": "Отчеты", "settings": "Настройки", "tools": "Инструменты", "tools_search": "Поиск датасетов", @@ -178,6 +179,14 @@ "view_task": "Просмотреть задачу", "empty": "Дашборды не найдены" }, + "reports": { + "title": "Отчеты", + "empty": "Отчеты отсутствуют.", + "filtered_empty": "Нет отчетов по выбранным фильтрам.", + "unknown_type": "Прочее / Неизвестный тип", + "not_provided": "Не указано", + "view_details": "Подробнее" + }, "datasets": { "empty": "Датасеты не найдены", "table_name": "Имя таблицы", diff --git a/frontend/src/lib/stores/__tests__/sidebar.test.js b/frontend/src/lib/stores/__tests__/sidebar.test.js index 0ea69b0..550db0d 100644 --- a/frontend/src/lib/stores/__tests__/sidebar.test.js +++ b/frontend/src/lib/stores/__tests__/sidebar.test.js @@ -14,6 +14,15 @@ vi.mock('$app/environment', () => ({ })); describe('SidebarStore', () => { + beforeEach(() => { + sidebarStore.set({ + isExpanded: true, + activeCategory: 'dashboards', + activeItem: '/dashboards', + isMobileOpen: false + }); + }); + // [DEF:test_sidebar_initial_state:Function] // @TEST: Store initializes with default values // @PRE: No localStorage state diff --git a/frontend/src/routes/reports/+page.svelte b/frontend/src/routes/reports/+page.svelte new file mode 100644 index 0000000..fdae042 --- /dev/null +++ b/frontend/src/routes/reports/+page.svelte @@ -0,0 +1,194 @@ + + + +
    + null} + actions={() => null} + /> + +
    +
    + + + + + + + +
    +
    + + {#if loading} +
    + {$t.common?.loading || 'Loading...'} +
    + {:else if error} +
    +

    {error}

    + +
    + {:else if !collection || collection.total === 0} +
    + {$t.reports?.empty || 'No reports available.'} +
    + {:else if collection.items.length === 0 && hasActiveFilters()} +
    +

    {$t.reports?.filtered_empty || 'No reports match your filters.'}

    + +
    + {:else} +
    +
    + +
    + +
    + {/if} +
    + + \ No newline at end of file diff --git a/frontend/src/routes/tasks/+page.svelte b/frontend/src/routes/tasks/+page.svelte index 07307aa..43a84bf 100644 --- a/frontend/src/routes/tasks/+page.svelte +++ b/frontend/src/routes/tasks/+page.svelte @@ -8,7 +8,7 @@ -->
    -
    +
    -
    -

    Результаты задач

    - +
    +
    +

    Результаты задач

    + +
    + +
    + + +
    + + {#if error} +
    + {error} +
    + {/if} + +
    + +
    + +
    + + Страница {currentPage} + +
    -

    Результат и логи

    {#if selectedTaskId} -
    +
    Логи задачи
    -
    +
    {:else} -
    +

    Выберите задачу из списка слева

    {/if} diff --git a/specs/019-superset-ux-redesign/tasks.md b/specs/019-superset-ux-redesign/tasks.md index 90e2fbd..1b07965 100644 --- a/specs/019-superset-ux-redesign/tasks.md +++ b/specs/019-superset-ux-redesign/tasks.md @@ -541,6 +541,12 @@ All implementation tasks MUST follow the Design-by-Contract specifications: - [x] T078 [P] [US5] Create unit tests for `TopNavbar.svelte` component in `frontend/src/lib/components/layout/__tests__/test_topNavbar.svelte.js` _Contract: @RELATION: VERIFIES -> frontend/src/lib/components/layout/TopNavbar.svelte_ _Test: Test sidebar store integration, activity store integration, task drawer integration, UX states_ +- [x] T079 [P] [US1] Create unit tests for `Breadcrumbs.svelte` component in `frontend/src/lib/components/layout/__tests__/test_breadcrumbs.svelte.js` + _Contract: @RELATION: VERIFIES -> frontend/src/lib/components/layout/Breadcrumbs.svelte_ + _Test: Test breadcrumb label formatting, deep-path truncation with ellipsis, and contract UX tags presence_ +- [x] T080 [P] [US1] Stabilize sidebar store legacy tests in `frontend/src/lib/stores/__tests__/sidebar.test.js` + _Contract: @RELATION: VERIFIES -> frontend/src/lib/stores/sidebar.js_ + _Test: Reset store state in `beforeEach` to prevent inter-test state leakage_ **Checkpoint**: Unit tests created for all core components @@ -560,5 +566,5 @@ All implementation tasks MUST follow the Design-by-Contract specifications: | US4 (Dataset Hub) Tasks | 18 | | US6 (Settings) Tasks | 8 | | Polish Tasks | 7 | -| Unit Tests Tasks | 9 | +| Unit Tests Tasks | 11 | | MVP Scope | Phases 1-5 (25 tasks) | diff --git a/specs/019-superset-ux-redesign/tests/coverage.md b/specs/019-superset-ux-redesign/tests/coverage.md new file mode 100644 index 0000000..ebee8c3 --- /dev/null +++ b/specs/019-superset-ux-redesign/tests/coverage.md @@ -0,0 +1,36 @@ +# Coverage Matrix: 019-superset-ux-redesign + +**Date**: 2026-02-21 +**Executed by**: Tester Agent + +## Coverage Matrix + +| Module | File | Has Tests | TIER | TEST_DATA Available | Notes | +|--------|------|-----------|------|---------------------|-------| +| SidebarStore | `frontend/src/lib/stores/sidebar.js` | ✅ | STANDARD | N/A | Store state, toggle, mobile, persistence covered | +| TaskDrawerStore | `frontend/src/lib/stores/taskDrawer.js` | ✅ | CRITICAL | ⚠️ Not defined in semantics/contracts | Open/close, mapping, retrieval covered | +| ActivityStore | `frontend/src/lib/stores/activity.js` | ✅ | STANDARD | N/A | Active count and recent task derivation covered | +| Sidebar | `frontend/src/lib/components/layout/Sidebar.svelte` | ✅ | CRITICAL | ⚠️ Not defined in semantics/contracts | UX state/store integration tests present | +| TaskDrawer | `frontend/src/lib/components/layout/TaskDrawer.svelte` | ✅ | CRITICAL | ⚠️ Not defined in semantics/contracts | Drawer state and resource-task interactions covered | +| TopNavbar | `frontend/src/lib/components/layout/TopNavbar.svelte` | ✅ | CRITICAL | ⚠️ Not defined in semantics/contracts | Activity/store integration and UX behaviors covered | +| Breadcrumbs | `frontend/src/lib/components/layout/Breadcrumbs.svelte` | ✅ | STANDARD | N/A | Added contract + truncation/label logic tests | +| DashboardsAPI | `backend/src/api/routes/dashboards.py` | ✅ | CRITICAL | ⚠️ Not defined in semantics/contracts | Existing backend tests present (not executed in this cycle) | +| DatasetsAPI | `backend/src/api/routes/datasets.py` | ✅ | CRITICAL | ⚠️ Not defined in semantics/contracts | Existing backend tests present (not executed in this cycle) | +| ResourceService | `backend/src/services/resource_service.py` | ✅ | STANDARD | N/A | Existing backend tests present (not executed in this cycle) | + +## Current Frontend Test Execution Snapshot + +- Test files: **9 passed** +- Tests: **82 passed** +- Failed: **0** +- Skipped: **0** + +Command: +```bash +cd frontend && npm run test +``` + +## Observations + +- No explicit `@TEST_DATA` fixtures were found for CRITICAL modules in `.ai/standards/semantics.md`; this file defines format requirements only. +- Coverage gap addressed: missing tests for `Breadcrumbs.svelte` added in co-located `__tests__` directory. \ No newline at end of file diff --git a/specs/019-superset-ux-redesign/tests/reports/2026-02-21-fix-report.md b/specs/019-superset-ux-redesign/tests/reports/2026-02-21-fix-report.md new file mode 100644 index 0000000..7f4636a --- /dev/null +++ b/specs/019-superset-ux-redesign/tests/reports/2026-02-21-fix-report.md @@ -0,0 +1,67 @@ +# Fix Report: 019-superset-ux-redesign - COMPLETED + +**Date**: 2026-02-21 +**Report**: specs/019-superset-ux-redesign/tests/reports/2026-02-21-report.md +**Fixer**: Coder Agent + +## Summary + +- Total Failed Tests: 0 +- Total Fixed: 0 +- Total Skipped: 0 + +## Failed Tests Analysis + +No failing tests were reported in `specs/019-superset-ux-redesign/tests/reports/2026-02-21-report.md`. + +### Informational Issues From Report + +#### Test: `src/lib/stores/__tests__/sidebar.test.js` + +**File**: `frontend/src/lib/stores/__tests__/sidebar.test.js` +**Error**: Historical flakiness due to state leakage (`isExpanded` assertion failed) + +**Root Cause**: Shared store state between tests in earlier version. + +**Fix Required**: None in this cycle; report confirms deterministic `beforeEach` reset already added. + +**Status**: Completed (pre-fixed before this cycle) + +--- + +#### Test: `src/lib/components/layout/__tests__/test_breadcrumbs.svelte.js` (initial approach) + +**File**: `frontend/src/lib/components/layout/__tests__/test_breadcrumbs.svelte.js` +**Error**: Historical Svelte runtime/render incompatibility with prior test approach. + +**Root Cause**: Previous mount strategy did not match current frontend test setup. + +**Fix Required**: None in this cycle; report confirms tests were reworked to contract/logic-focused checks and now pass. + +**Status**: Completed (pre-fixed before this cycle) + +## Fixes Applied + +No implementation or test modifications were required in this cycle because all tests already pass. + +**Semantic Integrity**: Preserved ✅ (no semantic anchors/tags were changed or removed) + +## Verification + +Command from test report: + +```bash +cd frontend && npm run test +``` + +Reported results: + +- Total: 82 +- Passed: 82 +- Failed: 0 +- Skipped: 0 + +## Next Steps + +- [ ] Run backend tests separately and resolve pre-existing auth/import issues if targeted by scope. +- [ ] Optionally execute frontend coverage run and publish numeric coverage report. \ No newline at end of file diff --git a/specs/019-superset-ux-redesign/tests/reports/2026-02-21-report.md b/specs/019-superset-ux-redesign/tests/reports/2026-02-21-report.md new file mode 100644 index 0000000..e11eac5 --- /dev/null +++ b/specs/019-superset-ux-redesign/tests/reports/2026-02-21-report.md @@ -0,0 +1,46 @@ +# Test Report: 019-superset-ux-redesign + +**Date**: 2026-02-21 +**Executed by**: Tester Agent + +## Coverage Summary + +| Module | Tests | Coverage % | +|--------|-------|------------| +| Breadcrumbs.svelte | 5 | N/A (behavioral/contract tests) | +| Frontend test suite total | 82 | N/A (coverage runner not executed) | + +## Test Results + +- Total: 82 +- Passed: 82 +- Failed: 0 +- Skipped: 0 + +Executed command: +```bash +cd frontend && npm run test +``` + +## Issues Found + +| Test | Error | Resolution | +|------|-------|------------| +| `src/lib/stores/__tests__/sidebar.test.js` | Flaky state leakage (`isExpanded` assertion failed) | Added deterministic `beforeEach` reset for `sidebarStore` | +| `src/lib/components/layout/__tests__/test_breadcrumbs.svelte.js` (initial approach) | Svelte render mode/runtime incompatibility in current test setup | Reworked into contract/logic-focused unit tests without client mount | + +## Changes Made + +- Added new co-located test file: + - `frontend/src/lib/components/layout/__tests__/test_breadcrumbs.svelte.js` +- Stabilized existing test file: + - `frontend/src/lib/stores/__tests__/sidebar.test.js` +- Added coverage matrix document: + - `specs/019-superset-ux-redesign/tests/coverage.md` + +## Next Steps + +- [x] Fix failed tests +- [x] Add more coverage for layout module (`Breadcrumbs.svelte`) +- [ ] Run backend test suite and address pre-existing backend import/auth issues separately +- [ ] Optionally add frontend `vitest --coverage` run and publish numeric coverage report \ No newline at end of file diff --git a/specs/020-task-reports-design/checklists/requirements.md b/specs/020-task-reports-design/checklists/requirements.md new file mode 100644 index 0000000..c419096 --- /dev/null +++ b/specs/020-task-reports-design/checklists/requirements.md @@ -0,0 +1,43 @@ +# Specification Quality Checklist: Unified Task Reports by Type + +**Purpose**: Validate specification completeness and quality before proceeding to planning +**Created**: 2026-02-22 +**Feature**: [spec.md](../spec.md) + +## Content Quality + +- [x] No implementation details (languages, frameworks, APIs) +- [x] Focused on user value and business needs +- [x] Written for non-technical stakeholders +- [x] All mandatory sections completed + +## UX Consistency + +- [x] Functional requirements fully support the 'Happy Path' in ux_reference.md +- [x] Error handling requirements match the 'Error Experience' in ux_reference.md +- [x] No requirements contradict the defined User Persona or Context + +## Requirement Completeness + +- [x] No [NEEDS CLARIFICATION] markers remain +- [x] Requirements are testable and unambiguous +- [x] Success criteria are measurable +- [x] Success criteria are technology-agnostic (no implementation details) +- [x] All acceptance scenarios are defined +- [x] Edge cases are identified +- [x] Scope is clearly bounded +- [x] Dependencies and assumptions identified + +## Feature Readiness + +- [x] All functional requirements have clear acceptance criteria +- [x] User scenarios cover primary flows +- [x] Feature meets measurable outcomes defined in Success Criteria +- [x] No implementation details leak into specification + +## Notes + +- Validation iteration: 1 +- Result: PASS +- No blocking issues found; specification is ready for `/speckit.plan` or `/speckit.clarify`. +- Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`. \ No newline at end of file diff --git a/specs/020-task-reports-design/contracts/modules.md b/specs/020-task-reports-design/contracts/modules.md new file mode 100644 index 0000000..a597ae9 --- /dev/null +++ b/specs/020-task-reports-design/contracts/modules.md @@ -0,0 +1,109 @@ +# Module Contracts: Unified Task Reports by Type + +## Backend Report Aggregation Module + +# [DEF:ReportsAggregationModule:Module] +# @TIER: CRITICAL +# @SEMANTICS: [reports, aggregation, normalization, task_outcomes] +# @PURPOSE: Aggregate heterogeneous task outcomes into a canonical report model for unified listing and detail retrieval. +# @LAYER: Domain +# @RELATION: DEPENDS_ON -> [DEF:TaskManagerModule] +# @RELATION: DEPENDS_ON -> [DEF:TaskPersistenceModule] +# @RELATION: CALLS -> [DEF:ReportsApiContract] +# @INVARIANT: Every returned report MUST include canonical fields {report_id, task_id, task_type, status, updated_at, summary}. +# @PRE: Query parameters are validated and within supported pagination/filter limits. +# @POST: Response contains normalized reports with deterministic ordering and total metadata. +# @POST: Unknown task type is mapped to fallback type "unknown" and remains visible. +# @POST: Partial payloads are rendered with placeholders, never causing report omission. +# [/DEF:ReportsAggregationModule] + +--- + +## Backend Reports API Contract + +# [DEF:ReportsApiContract:Module] +# @TIER: CRITICAL +# @SEMANTICS: [api, reports, contracts, pagination] +# @PURPOSE: Define backend HTTP contract for unified report list and report detail endpoints. +# @LAYER: Interface +# @RELATION: DEPENDS_ON -> [DEF:ReportsAggregationModule] +# @RELATION: IMPLEMENTS -> [DEF:Std:API_FastAPI] +# @INVARIANT: Endpoint responses are non-blocking reads and must not start long-running tasks. +# @PRE: Request is authenticated and authorized under existing report/task visibility rules. +# @POST: List endpoint returns {items, total, page, page_size, has_next, applied_filters}. +# @POST: Detail endpoint returns a single normalized report with diagnostics/next actions when available. +# @POST: Validation errors are explicit (400-range) and machine-readable. +# [/DEF:ReportsApiContract] + +--- + +## Frontend Unified Reports Page Contract + + +/** + * @TIER: CRITICAL + * @SEMANTICS: [ui, reports, filtering, detail_panel] + * @PURPOSE: Provide one unified report center with type-distinct visuals and fast operator triage flow. + * @LAYER: UI + * @RELATION: DEPENDS_ON -> [DEF:ReportsApiClient] + * @RELATION: BINDS_TO -> [DEF:ReportTypeProfileRegistry] + * @INVARIANT: Reports list remains readable and interactive under large history and mixed task types. + * @PRE: User is authenticated and has access to report data. + * @POST: User can identify report type from both text label and visual profile. + * @POST: User can filter by type/status and open detail without leaving report context. + * @UX_STATE: Loading -> Skeleton list displayed; filters visible but request controls disabled. + * @UX_STATE: Ready -> List of normalized reports shown with type badges and status indicators. + * @UX_STATE: NoData -> Friendly empty state with explanation when no reports exist at all. + * @UX_STATE: FilteredEmpty -> Message "No reports match your filters" with one-click clear action. + * @UX_STATE: Error -> Inline error block with retry action while preserving filter context. + * @UX_FEEDBACK: On filter apply, list updates with immediate visual acknowledgment. + * @UX_RECOVERY: Retry failed loads, clear filters, and continue reading partial reports with placeholders. + */ + + +--- + +## Frontend Reports API Client Contract + +# [DEF:ReportsApiClient:Module] +# @TIER: STANDARD +# @SEMANTICS: [frontend, api_client, reports] +# @PURPOSE: Wrap report API requests via existing request helpers and expose typed list/detail fetch methods. +# @LAYER: Infra +# @RELATION: DEPENDS_ON -> [DEF:api_module] +# @RELATION: CALLS -> [DEF:ReportsApiContract] +# @INVARIANT: Native fetch is not used directly; existing wrapper-based request path is preserved. +# @PRE: Valid auth token is present when required by backend. +# @POST: Returns parsed report payload or structured error object for UI-state mapping. +# [/DEF:ReportsApiClient] + +--- + +## Frontend Type Profile Registry Contract + +# [DEF:ReportTypeProfileRegistry:Module] +# @TIER: STANDARD +# @SEMANTICS: [presentation, report_types, fallback] +# @PURPOSE: Maintain deterministic mapping from task_type to visual profile metadata and fallback behavior. +# @LAYER: UI +# @RELATION: DEPENDS_ON -> [DEF:UnifiedReportsPage] +# @INVARIANT: Exactly one fallback profile exists and is used for unknown task types. +# @PRE: Input task_type may be known or unknown. +# @POST: Returns profile with display label and variant tokens required for rendering. +# [/DEF:ReportTypeProfileRegistry] + +--- + +## Contract Usage Simulation (Key Scenario) + +Scenario traced: Operator finds failed migration quickly and triages. + +1. `UnifiedReportsPage` requests filtered list (`status=failed`, `task_type=migration`) through `ReportsApiClient`. +2. `ReportsApiClient` calls `ReportsApiContract` list endpoint. +3. `ReportsAggregationModule` normalizes task records and returns canonical report items. +4. `UnifiedReportsPage` enters `Ready` `@UX_STATE`, rendering migration-specific visual profile. +5. Operator opens one report detail. +6. `ReportsApiContract` detail endpoint returns diagnostics + `next_actions`. +7. UI shows actionable failure context and recovery guidance without changing page context. + +Continuity check: No interface mismatch found across contracts for list/filter/detail path. \ No newline at end of file diff --git a/specs/020-task-reports-design/contracts/reports-api.openapi.yaml b/specs/020-task-reports-design/contracts/reports-api.openapi.yaml new file mode 100644 index 0000000..8fdb3b3 --- /dev/null +++ b/specs/020-task-reports-design/contracts/reports-api.openapi.yaml @@ -0,0 +1,272 @@ +openapi: 3.0.3 +info: + title: Unified Task Reports API + version: 1.0.0 + description: API contract for consolidated task reports across task types. + +servers: + - url: /api + +paths: + /reports: + get: + summary: List unified task reports + description: Returns paginated normalized reports with filtering and sorting. + operationId: listReports + parameters: + - in: query + name: page + schema: + type: integer + minimum: 1 + default: 1 + - in: query + name: page_size + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + - in: query + name: task_types + description: Comma-separated values + schema: + type: string + example: migration,backup + - in: query + name: statuses + description: Comma-separated values + schema: + type: string + example: failed,in_progress + - in: query + name: time_from + schema: + type: string + format: date-time + - in: query + name: time_to + schema: + type: string + format: date-time + - in: query + name: search + schema: + type: string + maxLength: 200 + - in: query + name: sort_by + schema: + type: string + enum: [updated_at, status, task_type] + default: updated_at + - in: query + name: sort_order + schema: + type: string + enum: [asc, desc] + default: desc + responses: + '200': + description: Paginated unified reports + content: + application/json: + schema: + $ref: '#/components/schemas/ReportCollection' + '400': + description: Invalid query parameters + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '401': + description: Unauthorized + '403': + description: Forbidden + + /reports/{report_id}: + get: + summary: Get report detail + description: Returns one normalized report with optional diagnostics and next actions. + operationId: getReportDetail + parameters: + - in: path + name: report_id + required: true + schema: + type: string + responses: + '200': + description: Report detail + content: + application/json: + schema: + $ref: '#/components/schemas/ReportDetailView' + '401': + description: Unauthorized + '403': + description: Forbidden + '404': + description: Report not found + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + +components: + schemas: + TaskType: + type: string + enum: + - llm_verification + - backup + - migration + - documentation + - unknown + + ReportStatus: + type: string + enum: + - success + - failed + - in_progress + - partial + + ReportSourceRef: + type: object + additionalProperties: true + description: Optional pointers to related domain objects (dashboard/dataset/environment). + + ErrorContext: + type: object + properties: + code: + type: string + message: + type: string + next_actions: + type: array + items: + type: string + required: [message] + + TaskReport: + type: object + properties: + report_id: + type: string + task_id: + type: string + task_type: + $ref: '#/components/schemas/TaskType' + status: + $ref: '#/components/schemas/ReportStatus' + started_at: + type: string + format: date-time + nullable: true + updated_at: + type: string + format: date-time + summary: + type: string + details: + type: object + nullable: true + additionalProperties: true + error_context: + $ref: '#/components/schemas/ErrorContext' + source_ref: + $ref: '#/components/schemas/ReportSourceRef' + required: + - report_id + - task_id + - task_type + - status + - updated_at + - summary + + ReportQueryEcho: + type: object + properties: + page: + type: integer + page_size: + type: integer + task_types: + type: array + items: + $ref: '#/components/schemas/TaskType' + statuses: + type: array + items: + $ref: '#/components/schemas/ReportStatus' + time_from: + type: string + format: date-time + nullable: true + time_to: + type: string + format: date-time + nullable: true + search: + type: string + nullable: true + sort_by: + type: string + enum: [updated_at, status, task_type] + sort_order: + type: string + enum: [asc, desc] + required: [page, page_size, sort_by, sort_order] + + ReportCollection: + type: object + properties: + items: + type: array + items: + $ref: '#/components/schemas/TaskReport' + total: + type: integer + minimum: 0 + page: + type: integer + minimum: 1 + page_size: + type: integer + minimum: 1 + has_next: + type: boolean + applied_filters: + $ref: '#/components/schemas/ReportQueryEcho' + required: [items, total, page, page_size, has_next, applied_filters] + + ReportDetailView: + type: object + properties: + report: + $ref: '#/components/schemas/TaskReport' + timeline: + type: array + items: + type: object + additionalProperties: true + diagnostics: + type: object + nullable: true + additionalProperties: true + next_actions: + type: array + items: + type: string + required: [report] + + ErrorResponse: + type: object + properties: + detail: + type: string + code: + type: string + required: [detail] \ No newline at end of file diff --git a/specs/020-task-reports-design/data-model.md b/specs/020-task-reports-design/data-model.md new file mode 100644 index 0000000..a7b0e7f --- /dev/null +++ b/specs/020-task-reports-design/data-model.md @@ -0,0 +1,143 @@ +# Data Model: Unified Task Reports by Type + +**Feature**: [`020-task-reports-design`](specs/020-task-reports-design) +**Spec**: [`spec.md`](specs/020-task-reports-design/spec.md) +**Research**: [`research.md`](specs/020-task-reports-design/research.md) + +## 1. Entity: TaskReport + +Represents a normalized, user-visible report entry for one task execution. + +### Fields + +| Field | Type | Required | Description | +|---|---|---|---| +| report_id | string | Yes | Stable unique identifier of report entry. | +| task_id | string | Yes | Source task identifier. | +| task_type | enum | Yes | `llm_verification`, `backup`, `migration`, `documentation`, `unknown`. | +| status | enum | Yes | `success`, `failed`, `in_progress`, `partial`. | +| started_at | datetime | No | Task start time if available. | +| updated_at | datetime | Yes | Last known report update timestamp. | +| summary | string | Yes | Short user-facing summary of outcome. | +| details | object | No | Type-specific details block for drill-down. | +| error_context | object | No | Failure/partial context with reason + recommended next action. | +| source_ref | object | No | Optional links to related resource (dataset/dashboard/environment). | + +### Validation Rules + +- `report_id` and `task_id` must be non-empty. +- `task_type` outside known values must map to `unknown`. +- `status` outside known values must be rejected or mapped by normalization policy. +- `summary` must be present (fallback to default summary if upstream is empty). + +### Lifecycle / State Transitions + +- `in_progress` → `success` +- `in_progress` → `failed` +- `in_progress` → `partial` +- `partial` may transition to `success` after follow-up action +- Terminal states (`success`, `failed`) are immutable except metadata enrichment + +--- + +## 2. Entity: ReportTypeProfile + +Defines presentation semantics used by frontend for each report category. + +### Fields + +| Field | Type | Required | Description | +|---|---|---|---| +| task_type | enum | Yes | Type key used for profile selection. | +| display_label | string | Yes | Explicit text label shown in report list/detail. | +| visual_variant | string | Yes | Variant token controlling style family. | +| icon_token | string | No | Optional icon semantic key. | +| emphasis_rules | array[string] | No | Defines which fields receive visual priority. | +| fallback | boolean | Yes | Marks profile as default fallback for unknown types. | + +### Validation Rules + +- Exactly one profile per known `task_type`. +- Exactly one fallback profile with `fallback=true`. +- `display_label` must be non-empty and localized in implementation. + +--- + +## 3. Entity: ReportQuery + +Represents user-selected filtering and ordering options for list retrieval. + +### Fields + +| Field | Type | Required | Description | +|---|---|---|---| +| page | integer | Yes | 1-based page index. | +| page_size | integer | Yes | Number of items per page. | +| task_types | array[enum] | No | Type filter list. | +| statuses | array[enum] | No | Status filter list. | +| time_from | datetime | No | Lower time bound. | +| time_to | datetime | No | Upper time bound. | +| search | string | No | Free text search over summary/details. | +| sort_by | enum | Yes | `updated_at`, `status`, `task_type`. | +| sort_order | enum | Yes | `asc`, `desc`. | + +### Validation Rules + +- `page >= 1`. +- `1 <= page_size <= 100`. +- `time_from <= time_to` when both are provided. +- Unsupported filter values are rejected with validation error. + +--- + +## 4. Entity: ReportCollection + +A paginated response containing normalized reports for unified listing. + +### Fields + +| Field | Type | Required | Description | +|---|---|---|---| +| items | array[TaskReport] | Yes | Current page of reports. | +| total | integer | Yes | Total count matching filters. | +| page | integer | Yes | Current page index. | +| page_size | integer | Yes | Page size used. | +| has_next | boolean | Yes | True when another page exists. | +| applied_filters | ReportQuery | Yes | Echo of effective filter/query. | + +--- + +## 5. Entity: ReportDetailView + +Detailed representation for a single selected report. + +### Fields + +| Field | Type | Required | Description | +|---|---|---|---| +| report | TaskReport | Yes | Base normalized report. | +| timeline | array[object] | No | Ordered key lifecycle events (start/fail/complete). | +| diagnostics | object | No | Extended detail payload for the type. | +| next_actions | array[string] | No | Human-readable recovery guidance. | + +### Validation Rules + +- Detail view must always include `report`. +- For `failed`/`partial` status, `next_actions` should be non-empty whenever actionable context exists. + +--- + +## 6. Relationships + +- `ReportCollection.items[*]` → `TaskReport` +- `TaskReport.task_type` → selects `ReportTypeProfile` +- `ReportQuery` → constrains `ReportCollection` +- `ReportDetailView.report` → exactly one `TaskReport` + +--- + +## 7. Scale Assumptions + +- Historical report volume may reach thousands of entries per environment. +- Query model is designed for server-side filtering and pagination. +- UI must remain usable even when only partial fields are available for some task types. \ No newline at end of file diff --git a/specs/020-task-reports-design/plan.md b/specs/020-task-reports-design/plan.md new file mode 100644 index 0000000..a59de85 --- /dev/null +++ b/specs/020-task-reports-design/plan.md @@ -0,0 +1,109 @@ +# Implementation Plan: Unified Task Reports by Type + +**Branch**: `020-task-reports-design` | **Date**: 2026-02-22 | **Spec**: [`/home/busya/dev/ss-tools/specs/020-task-reports-design/spec.md`](specs/020-task-reports-design/spec.md) +**Input**: Feature specification from [`/specs/020-task-reports-design/spec.md`](specs/020-task-reports-design/spec.md) + +## Summary + +Implement a unified reports experience that aggregates task outcomes across LLM documentation/verification, backups, migrations, and documentation into one report center with type-specific visual design. The approach extends existing task/result data flows and adds normalized report-view contracts so users can identify type, status, and next actions quickly while preserving current async task architecture and operational observability. + +## Technical Context + +**Language/Version**: Python 3.9+ (backend), Node.js 18+ (frontend) +**Primary Dependencies**: FastAPI, SvelteKit, Tailwind CSS, SQLAlchemy/Pydantic task models, existing task/websocket stack +**Storage**: SQLite task/result persistence (existing task DB), filesystem only for existing artifacts (no new primary store required) +**Testing**: pytest (backend), Vitest (frontend), API contract tests for report endpoints +**Target Platform**: Linux server backend + browser-based SPA frontend +**Project Type**: Web application (frontend + backend) +**Performance Goals**: Report list first render <2s for typical workload; filter response perceived immediate (<500ms UI update for already loaded data) +**Constraints**: Must reuse existing TaskManager async model; no blocking task APIs; preserve RBAC boundaries; avoid breaking current dashboards/datasets/task pages +**Scale/Scope**: Unified view for at least 4 report types; thousands of historical report entries, with pagination/filtering in UX + +## Constitution Check + +*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* + +| Gate | Status | Notes | +|---|---|---| +| Semantic Protocol Compliance ([`constitution.md`](.ai/standards/constitution.md)) | PASS | New/updated modules will define [DEF] contracts in [`contracts/modules.md`](specs/020-task-reports-design/contracts/modules.md). | +| Modular Plugin Architecture | PASS | Feature consumes plugin/task outputs; no hardcoded config paths; existing config/dependency mechanisms retained. | +| Unified Frontend Experience | PASS | Tailwind-first UI, reuse existing API wrappers, and route all user-facing strings through i18n files in implementation phase. | +| Security & RBAC | PASS | Report visibility remains under existing auth/session and permission checks; no permission bypass in plan. | +| Independent Testability | PASS | Spec already defines independent user stories and acceptance scenarios. | +| Asynchronous Execution | PASS | Long-running operations remain task-based; reporting is read/aggregation over async outcomes. | + +## Project Structure + +### Documentation (this feature) + +```text +specs/020-task-reports-design/ +├── plan.md +├── research.md +├── data-model.md +├── quickstart.md +├── contracts/ +│ ├── modules.md +│ └── reports-api.openapi.yaml +└── tasks.md +``` + +### Source Code (repository root) + +```text +backend/ +├── src/ +│ ├── api/ +│ │ └── routes/ +│ ├── services/ +│ ├── models/ +│ └── core/ +└── tests/ + +frontend/ +├── src/ +│ ├── lib/ +│ │ ├── components/ +│ │ ├── stores/ +│ │ └── api/ +│ └── routes/ +└── tests/ +``` + +**Structure Decision**: Use the existing web application split ([`backend/`](backend), [`frontend/`](frontend)) with feature additions in report-oriented API route/service and a dedicated frontend reports route/components. This minimizes architectural risk and conforms to existing module boundaries in [`PROJECT_MAP`](.ai/PROJECT_MAP.md). + +## Phase 0: Research Focus + +Research tasks derived from technical context and spec: + +1. Best strategy to normalize heterogeneous task outputs (LLM, backup, migration, documentation) into one report DTO without losing type-specific meaning. +2. Pagination/filter tradeoffs for large report history while preserving UX scan speed from [`ux_reference.md`](specs/020-task-reports-design/ux_reference.md). +3. Error/fallback taxonomy for unknown task type and partial payloads consistent with existing task status model. +4. RBAC and privacy implications of consolidated cross-type reporting. +5. Contract strategy for mapping UX states (Loading/Empty/FilteredEmpty/Error) to backend/frontend boundaries. + +## Phase 1: Design & Contracts Plan + +1. Validate architecture against UX: + - Ensure unified list + type-specific cards + fast filtering supports happy path. + - Ensure explicit handling for Loading/No Data/Filtered Empty/Failed report detail states. +2. Produce [`data-model.md`](specs/020-task-reports-design/data-model.md) from spec entities and lifecycle rules. +3. Produce [`contracts/modules.md`](specs/020-task-reports-design/contracts/modules.md) with DEF headers, TIER, PRE/POST, UX state tags where applicable. +4. Simulate one full scenario through contracts (failed migration report discovery and triage path). +5. Produce API contract at [`reports-api.openapi.yaml`](specs/020-task-reports-design/contracts/reports-api.openapi.yaml) for backend/frontend sync. +6. Produce [`quickstart.md`](specs/020-task-reports-design/quickstart.md) for implementation and verification flow. +7. Run agent context updater script and record result. + +## Complexity Tracking + +No constitution violations identified; section intentionally empty. + +## Test Data Reference + +| Component | TIER | Fixture Name | Location | +|---|---|---|---| +| Unified Reports API Contract | CRITICAL | mixed_task_reports | [`spec.md`](specs/020-task-reports-design/spec.md) | +| Reports UI State Handling | CRITICAL | unknown_type_partial_payload | [`spec.md`](specs/020-task-reports-design/spec.md) | +| Report Filtering & Discovery | STANDARD | failed_reports_filterable | [`spec.md`](specs/020-task-reports-design/spec.md) | + +**Note**: Tester implementation should materialize these fixtures in backend/frontend test suites during `/speckit.tasks` execution. diff --git a/specs/020-task-reports-design/quickstart.md b/specs/020-task-reports-design/quickstart.md new file mode 100644 index 0000000..300d971 --- /dev/null +++ b/specs/020-task-reports-design/quickstart.md @@ -0,0 +1,84 @@ +# Quickstart: Unified Task Reports by Type + +## Purpose + +Implement and validate the unified reports feature defined in: +- Spec: [`spec.md`](specs/020-task-reports-design/spec.md) +- UX reference: [`ux_reference.md`](specs/020-task-reports-design/ux_reference.md) +- Plan: [`plan.md`](specs/020-task-reports-design/plan.md) +- Data model: [`data-model.md`](specs/020-task-reports-design/data-model.md) +- Contracts: [`contracts/modules.md`](specs/020-task-reports-design/contracts/modules.md), [`contracts/reports-api.openapi.yaml`](specs/020-task-reports-design/contracts/reports-api.openapi.yaml) + +## 1) Backend implementation flow + +1. Add report API route module under existing API routes structure. +2. Implement report aggregation/normalization service using canonical `TaskReport` envelope + type-specific details. +3. Enforce server-side filtering and pagination according to OpenAPI contract. +4. Ensure unknown task types map to fallback `unknown` and partial payloads are still returned. +5. Keep read-only/non-blocking behavior for report endpoints. + +## 2) Frontend implementation flow + +1. Add unified reports page route and connect to existing API wrapper layer (no native fetch). +2. Implement list view with type-specific visual profiles and explicit text labels. +3. Implement filter toolbar (type/status/time/search) and empty/error/loading states. +4. Add detail panel/page for selected report with diagnostics and next actions. +5. Ensure all user-facing strings are i18n-ready. + +## 3) UX conformance checks (must pass) + +- Loading state shows skeleton placeholders. +- No-data state appears when there are no reports at all. +- Filtered-empty state appears for strict filter combinations and supports one-click clear. +- Failed report shows clear reason + suggested next actions. +- Unknown type is visible with neutral fallback style. + +## 4) Contract checks (must pass) + +- API payloads match [`reports-api.openapi.yaml`](specs/020-task-reports-design/contracts/reports-api.openapi.yaml). +- Canonical minimum fields always present in list and detail. +- Status and task_type values conform to enumerations. +- Pagination metadata (`total`, `has_next`, `applied_filters`) is consistent. + +## 5) Suggested validation commands + +Backend tests (use project venv convention): +```bash +cd backend && .venv/bin/python3 -m pytest +``` + +Frontend tests: +```bash +cd frontend && npm test +``` + +Optional targeted API contract checks: +```bash +cd backend && .venv/bin/python3 -m pytest tests -k reports +``` + +## 6) Validation execution results (implementation run) + +### Backend targeted reports tests + +Command: +```bash +cd backend && .venv/bin/python3 -m pytest tests/test_reports_api.py tests/test_report_normalizer.py tests/test_reports_detail_api.py tests/test_reports_openapi_conformance.py -q +``` + +Result: +- `tests/test_report_normalizer.py`: created and collected in run context. +- API-level tests requiring app import failed at collection in current environment due DB connection: + - `psycopg2.OperationalError` / `sqlalchemy.exc.OperationalError` + - connection refused to `localhost:5432` + +Interpretation: +- Reports code/tests are in place, but full backend validation in this environment is blocked by unavailable database service. +- Re-run same command in environment with reachable DB to complete final verification. + +## 7) Done criteria for planning handoff + +- All planning artifacts exist and are internally consistent. +- UX states in [`ux_reference.md`](specs/020-task-reports-design/ux_reference.md) are mapped in module contracts. +- OpenAPI contract is stable for backend/frontend parallel implementation. +- Ready to decompose into executable work items via `/speckit.tasks`. \ No newline at end of file diff --git a/specs/020-task-reports-design/research.md b/specs/020-task-reports-design/research.md new file mode 100644 index 0000000..ee5f7b8 --- /dev/null +++ b/specs/020-task-reports-design/research.md @@ -0,0 +1,93 @@ +# Phase 0 Research: Unified Task Reports by Type + +**Feature**: [`020-task-reports-design`](specs/020-task-reports-design) +**Input Spec**: [`spec.md`](specs/020-task-reports-design/spec.md) +**Related UX**: [`ux_reference.md`](specs/020-task-reports-design/ux_reference.md) + +## 1) Normalizing heterogeneous task outputs into one report model + +### Decision +Adopt a two-layer report model: +1. **Canonical Report Envelope** shared across all task types. +2. **Type-Specific Detail Block** preserved per task type (LLM verification/documentation, backup, migration, documentation). + +### Rationale +This preserves a uniform list/filter/sort experience while avoiding data loss from specialized task outcomes. It also aligns with the spec’s requirement for consistent minimum fields and type-specific design. + +### Alternatives considered +- **Single fully generic schema only**: rejected because rich type-specific context becomes flattened and less actionable. +- **Separate endpoints and UI per type**: rejected because it breaks unified-report UX goal and increases navigation friction. + +--- + +## 2) Pagination/filter strategy at report-history scale + +### Decision +Use server-driven pagination and filtering as source of truth, with optional client-side refinement for currently visible page. + +### Rationale +Large historical datasets require bounded payload sizes and stable response times. Server-side filtering supports scalable queries and predictable UX for “find failed report quickly” scenarios. + +### Alternatives considered +- **Client-only filtering over full dataset**: rejected due to high transfer/memory cost and slow initial load at scale. +- **Infinite scroll without explicit pagination metadata**: rejected due to weaker operational predictability and harder QA validation. + +--- + +## 3) Unknown type and partial payload fallback semantics + +### Decision +Define deterministic fallback rules: +- Unknown type → render neutral “Other/Unknown” profile. +- Missing fields → show explicit placeholder text (“Not provided”). +- Status normalization maps all backend states into a fixed view state set: Success, Failed, In Progress, Partial. + +### Rationale +This directly supports UX error-recovery expectations and prevents broken/blank interfaces when upstream task payloads vary. + +### Alternatives considered +- **Hide malformed/unknown reports**: rejected because it reduces visibility and can hide operational incidents. +- **Hard-fail rendering on missing fields**: rejected due to poor resilience and degraded operator trust. + +--- + +## 4) RBAC/privacy in consolidated reporting + +### Decision +Inherit existing task visibility and permission checks; do not broaden data exposure in this feature. + +### Rationale +Consolidation can accidentally reveal cross-domain details. Reusing current auth boundaries avoids privilege escalation and keeps rollout low risk. + +### Alternatives considered +- **Open read access to all reports**: rejected due to security/privacy risk. +- **Introduce new role system in this feature**: rejected as out of scope and high change risk for current release. + +--- + +## 5) UX state to contract mapping strategy + +### Decision +Map UX states from [`ux_reference.md`](specs/020-task-reports-design/ux_reference.md) into explicit module/API contracts using semantic tags: +- `@UX_STATE: Loading` +- `@UX_STATE: NoData` +- `@UX_STATE: FilteredEmpty` +- `@UX_STATE: Error` +- `@UX_STATE: Ready` + +### Rationale +The project constitution and semantics standard require UX to be treated as contract logic, not decoration. Explicit state contracts reduce ambiguity for implementation and testing. + +### Alternatives considered +- **Document states only in UX narrative**: rejected because it weakens enforceability and test traceability. +- **Encode states implicitly in code without contracts**: rejected due to lower semantic compliance and harder review. + +--- + +## Consolidated Research Outcomes for Planning + +- Canonical envelope + per-type details is the selected report modeling pattern. +- Server-side pagination/filtering is required for scalable history. +- Unknown/partial payloads must remain visible with fallback rendering. +- Existing RBAC boundaries remain authoritative for report visibility. +- UX states must be contract-bound in module definitions for implementation and QA traceability. \ No newline at end of file diff --git a/specs/020-task-reports-design/spec.md b/specs/020-task-reports-design/spec.md new file mode 100644 index 0000000..279e284 --- /dev/null +++ b/specs/020-task-reports-design/spec.md @@ -0,0 +1,111 @@ +# Feature Specification: Unified Task Reports by Type + +**Feature Branch**: `020-task-reports-design` +**Reference UX**: `ux_reference.md` (See specific folder) +**Created**: 2026-02-22 +**Status**: Draft +**Input**: User description: "отображения отчетов по всем возможным задачам, со своим дизайном для каждого тип - llm документирование/проверка, бэкапы, миграции, документация." + +## User Scenarios & Testing *(mandatory)* + +### User Story 1 - View all task reports in one place (Priority: P1) + +As an operator, I can open a single reports area and see reports for all available task types so I do not need to switch between multiple sections to understand system outcomes. + +**Why this priority**: Centralized visibility is the core value; without it, the feature does not solve the reporting fragmentation problem. + +**Independent Test**: Can be fully tested by opening the reports area with a mixed set of task records and confirming each supported type appears in one consolidated list with clear type identification. + +**Acceptance Scenarios**: + +1. **Given** reports exist for LLM checks, backups, migrations, and documentation tasks, **When** the user opens the reports section, **Then** the system shows all report entries in a unified view. +2. **Given** reports exist for only a subset of task types, **When** the user opens the reports section, **Then** the system still renders the available reports and clearly indicates missing types as empty or absent without errors. + +--- + +### User Story 2 - Recognize report type by distinct design (Priority: P2) + +As an operator, I can visually distinguish report types by dedicated design patterns so I can quickly interpret what kind of task produced each report. + +**Why this priority**: Type-specific design significantly improves speed of reading and reduces interpretation errors, but is secondary to having all reports visible. + +**Independent Test**: Can be tested by rendering one report per supported type and validating that each type follows a unique, consistent visual style and label convention. + +**Acceptance Scenarios**: + +1. **Given** a report of type "LLM documentation/verification", **When** it is displayed, **Then** it uses the design variant defined for that type and includes explicit type labeling. +2. **Given** a report of type "Backup", "Migration", or "Documentation", **When** each report is displayed, **Then** each uses its own dedicated design variant and remains visually distinguishable from others. + +--- + +### User Story 3 - Understand report details and outcomes quickly (Priority: P3) + +As an operator, I can open a report and immediately see key outcome details (status, summary, timestamps, and relevant context) so I can decide what action is needed next. + +**Why this priority**: Rich report readability improves operational response quality after the core listing and type differentiation are available. + +**Independent Test**: Can be tested by opening reports with successful and failed outcomes and confirming key fields are consistently present and understandable across all types. + +**Acceptance Scenarios**: + +1. **Given** a successful report, **When** the user views its details, **Then** the report clearly presents completion status, summary, and execution time context. +2. **Given** a failed or partial report, **When** the user views its details, **Then** the report clearly shows failure state, what failed, and actionable next-step guidance. + +--- + +### Edge Cases + +- A report arrives with an unknown or newly added task type; the system shows it using a safe generic report design without breaking the reports page. +- A task report exists but includes incomplete fields; the system displays available fields and explicit placeholders for missing values. +- The number of reports is large; users can still locate relevant reports through clear ordering and filtering by type/status/time. +- Multiple reports share the same timestamp; ordering remains stable and deterministic. + +## Requirements *(mandatory)* + +### Functional Requirements + +- **FR-001**: System MUST provide one consolidated reports view containing report entries from all supported task types. +- **FR-002**: System MUST support at minimum these report types as first-class categories: LLM documentation/verification, backup, migration, and documentation. +- **FR-003**: System MUST assign and render a dedicated visual design profile for each supported report type. +- **FR-004**: Users MUST be able to identify report type from both visual cues and explicit text labeling. +- **FR-005**: System MUST display for every report a consistent minimum detail set: task type, execution status, completion or update time, and short summary. +- **FR-006**: System MUST provide a detailed report view that includes outcome explanation and context needed for follow-up actions. +- **FR-007**: System MUST represent report states consistently across all types using uniform semantics. Supported states MUST include: `success`, `failed`, `running`, `partial`, and `pending`. +- **FR-008**: System MUST allow users to filter and group reports by type and status (e.g., grouping by date or type) to reduce time to find relevant items. +- **FR-009**: System MUST handle missing or partial report data gracefully by showing fallback text rather than blank or broken UI. +- **FR-010**: System MUST handle unsupported or unknown task types using a neutral fallback design that preserves visibility and readability. +- **FR-011**: System MUST preserve report readability and usability when report volume grows (e.g., clear ordering and manageable navigation behavior). +- **FR-012**: System MUST make error context visible for failed reports, including what failed and recovery-oriented guidance. + +### Key Entities *(include if feature involves data)* + +- **Task Report**: A user-visible summary of a task execution; key attributes include report identifier, task type, status, timestamps, summary, details, and severity/priority cues. +- **Report Type Profile**: A definition of the visual and textual presentation rules for a report category; includes type label, style variant, iconography cues, and emphasis rules. +- **Report Outcome**: A normalized status model for task results; includes state classification, message, error context (if any), and suggested next actions. +- **Report Collection View**: An ordered and filterable set of task reports; includes active filters, sorting mode, and pagination or incremental loading state. + +## Success Criteria *(mandatory)* + +### Measurable Outcomes + +- **SC-001**: 100% of reports belonging to the four target task types are visible from one unified reports entry point. +- **SC-002**: In usability checks, at least 90% of users correctly identify report type within 3 seconds for each of the four target types. +- **SC-003**: At least 90% of users can locate a failed report using type/status filtering in under 20 seconds. +- **SC-004**: At least 95% of displayed reports include all required minimum fields (type, status, time, summary) without manual refresh or workaround. +- **SC-005**: At least 85% of users report that report layouts are clear and visually distinct across task types. +- **SC-006**: Support requests related to “where to find task results” decrease by at least 40% within one release cycle after launch. + +--- + +## Assumptions + +- Existing task executions already produce reportable outcome data for the four target types. +- Access permissions for viewing reports follow current user role rules and are not expanded in this feature. +- Users primarily need read-oriented reporting with light interaction (view, filter, inspect details), not direct task execution from the reports screen. +- A fallback presentation for unknown task types is acceptable and preferable to hiding reports. + +## Dependencies + +- Availability and consistency of report-producing task outputs across LLM documentation/verification, backup, migration, and documentation workflows. +- Existing navigation path where users can access the unified reports section. +- Agreed product design language that allows distinct but coherent type-based visual patterns. diff --git a/specs/020-task-reports-design/tasks.md b/specs/020-task-reports-design/tasks.md new file mode 100644 index 0000000..be16f37 --- /dev/null +++ b/specs/020-task-reports-design/tasks.md @@ -0,0 +1,195 @@ +# Tasks: Unified Task Reports by Type + +**Input**: Design documents from [`/specs/020-task-reports-design/`](specs/020-task-reports-design) +**Prerequisites**: [`plan.md`](specs/020-task-reports-design/plan.md), [`spec.md`](specs/020-task-reports-design/spec.md), [`ux_reference.md`](specs/020-task-reports-design/ux_reference.md), [`research.md`](specs/020-task-reports-design/research.md), [`data-model.md`](specs/020-task-reports-design/data-model.md), [`contracts/`](specs/020-task-reports-design/contracts) + +**Tests**: Include contract/integration/UI tests for independent story validation. + +**Organization**: Tasks are grouped by user story to enable independent implementation and testing. + +## Format: `[ID] [P?] [Story] Description` + +--- + +## Phase 1: Setup (Shared Infrastructure) + +**Purpose**: Prepare report feature scaffolding and shared fixtures. + +- [x] T001 Create reports feature folder placeholders in `backend/src/services/reports/` and `frontend/src/lib/components/reports/` +- [x] T002 [P] Add report fixture set `mixed_task_reports` and `unknown_type_partial_payload` in `backend/tests/fixtures/reports/fixtures_reports.json` +- [x] T003 [P] Add frontend mock payload fixtures for report states in `frontend/src/lib/components/reports/__tests__/fixtures/reports.fixtures.js` +- [x] T004 Register i18n key placeholders for reports UI text in `frontend/src/lib/i18n/locales/en.json` and `frontend/src/lib/i18n/locales/ru.json` + +--- + +## Phase 2: Foundational (Blocking Prerequisites) + +**Purpose**: Build core report domain and API foundations used by all stories. + +- [x] T005 Implement canonical report schemas (`TaskReport`, `ReportQuery`, `ReportCollection`, `ReportDetailView`) in `backend/src/models/report.py` +- [x] T006 [P] Implement report type profile registry and unknown fallback mapping in `backend/src/services/reports/type_profiles.py` +- [x] T007 Implement report normalization service in `backend/src/services/reports/normalizer.py` +- [x] T008 Implement aggregation/query service with server-side filtering + pagination in `backend/src/services/reports/report_service.py` +- [x] T009 Add reports API route module with list/detail endpoints in `backend/src/api/routes/reports.py` (CRITICAL: PRE: authenticated/authorized request; POST: returns `{items,total,page,page_size,has_next,applied_filters}` and detail with diagnostics/next_actions; UX_STATE support via deterministic error payloads) +- [x] T010 Wire reports router into API registration in `backend/src/api/routes/__init__.py` and `backend/src/app.py` +- [x] T011 Create frontend reports API client using existing wrapper methods (no native fetch) in `frontend/src/lib/api/reports.js` (CRITICAL: PRE: valid auth context; POST: parsed payload or structured error for UI-state mapping) +- [x] T011a Verify `contracts/modules.md` alignment with `spec.md` requirements and ensure all [DEF] anchors are ready. + +**Checkpoint**: Foundational layer complete; user stories can proceed. + +--- + +## Phase 3: User Story 1 - View all task reports in one place (Priority: P1) 🎯 MVP + +**Goal**: Provide one consolidated report center that lists all task types in one view. + +**Independent Test**: Open reports page with mixed task fixtures and verify LLM/backup/migration/documentation reports are visible in one unified list. + +### Tests for User Story 1 + +- [x] T012 [P] [US1] Add backend contract tests for `GET /api/reports` pagination/filter defaults in `backend/tests/test_reports_api.py` +- [x] T013 [P] [US1] Add frontend integration test for unified mixed-type rendering in `frontend/src/lib/components/reports/__tests__/reports_page.integration.test.js` + +### Implementation for User Story 1 + +- [x] T014 [US1] Implement reports list endpoint handler in `backend/src/api/routes/reports.py` (CRITICAL: PRE: validated query params; POST: normalized deterministic ordering and canonical minimum fields) +- [x] T015 [P] [US1] Implement reports page route container in `frontend/src/routes/reports/+page.svelte` +- [x] T016 [P] [US1] Implement reports list component and row/card composition in `frontend/src/lib/components/reports/ReportsList.svelte` (CRITICAL: Include @UX_STATE Idle/Loading/Error and @TEST_DATA anchors) +- [x] T016a [US1] Implement grouping logic (by date/type) in `ReportsList.svelte` to satisfy FR-008. +- [x] T017 [US1] Implement loading/no-data/error UI states in reports page using UX reference in `frontend/src/routes/reports/+page.svelte` (CRITICAL: UX_STATE Loading/NoData/Error preserved) +- [x] T018 [US1] Add navigation entry to reports page in `frontend/src/lib/components/layout/Sidebar.svelte` +- [x] T019 [US1] Verify implementation matches [`ux_reference.md`](specs/020-task-reports-design/ux_reference.md) (Happy Path & Errors) + +**Checkpoint**: US1 independently functional and demo-ready as MVP. + +--- + +## Phase 4: User Story 2 - Recognize report type by distinct design (Priority: P2) + +**Goal**: Ensure each report type has a distinct and consistent visual design + explicit label. + +**Independent Test**: Render one report per type and confirm each has unique style profile and explicit task-type label. + +### Tests for User Story 2 + +- [x] T020 [P] [US2] Add frontend visual/state tests for type profile mapping and fallback in `frontend/src/lib/components/reports/__tests__/report_type_profiles.test.js` +- [x] T021 [P] [US2] Add backend normalization tests for unknown type fallback mapping in `backend/tests/test_report_normalizer.py` + +### Implementation for User Story 2 + +- [x] T022 [US2] Implement frontend report type profile registry in `frontend/src/lib/components/reports/reportTypeProfiles.js` (CRITICAL: PRE: known/unknown type input; POST: one fallback profile always returned) +- [x] T023 [US2] Apply type-specific badges, variants, and emphasis rules in `frontend/src/lib/components/reports/ReportCard.svelte` +- [x] T024 [US2] Add explicit textual type labels and accessibility labels in `frontend/src/lib/components/reports/ReportCard.svelte` +- [x] T025 [US2] Implement filtered-empty UX state with one-click reset action in `frontend/src/routes/reports/+page.svelte` (CRITICAL: UX_STATE FilteredEmpty preserved) +- [x] T026 [US2] Verify implementation matches [`ux_reference.md`](specs/020-task-reports-design/ux_reference.md) (Happy Path & Errors) + +**Checkpoint**: US2 independently functional with distinct visual semantics. + +--- + +## Phase 5: User Story 3 - Understand report details and outcomes quickly (Priority: P3) + +**Goal**: Add detailed report drill-down with clear outcome context and next actions. + +**Independent Test**: Open success and failed reports and confirm status, summary, timing, diagnostics, and actionable guidance are immediately visible. + +### Tests for User Story 3 + +- [x] T027 [P] [US3] Add backend contract tests for `GET /api/reports/{report_id}` in `backend/tests/test_reports_detail_api.py` +- [x] T028 [P] [US3] Add frontend detail-panel integration test for failed report recovery guidance in `frontend/src/lib/components/reports/__tests__/report_detail.integration.test.js` + +### Implementation for User Story 3 + +- [x] T029 [US3] Implement report detail endpoint in `backend/src/api/routes/reports.py` (CRITICAL: PRE: auth + report_id exists; POST: normalized detail + diagnostics + next_actions) +- [x] T030 [US3] Implement report detail service assembly in `backend/src/services/reports/report_service.py` (CRITICAL: POST: failed/partial include actionable context when available) +- [x] T031 [P] [US3] Implement report detail panel/page component in `frontend/src/lib/components/reports/ReportDetailPanel.svelte` +- [x] T032 [US3] Integrate list-to-detail interaction and context-preserving navigation in `frontend/src/routes/reports/+page.svelte` +- [x] T033 [US3] Implement partial-data placeholders and failed-report action hints in `frontend/src/lib/components/reports/ReportDetailPanel.svelte` (CRITICAL: UX_RECOVERY preserved) +- [x] T034 [US3] Verify implementation matches [`ux_reference.md`](specs/020-task-reports-design/ux_reference.md) (Happy Path & Errors) + +**Checkpoint**: US3 independently functional with complete detail and recovery guidance. + +--- + +## Phase 6: Polish & Cross-Cutting Concerns + +**Purpose**: Final consistency, performance, and documentation updates across all stories. + +- [x] T035 [P] Add API contract conformance checks against `specs/020-task-reports-design/contracts/reports-api.openapi.yaml` in `backend/tests/test_reports_openapi_conformance.py` (CRITICAL: Verify @UX_STATE and @TEST_DATA metadata compliance) +- [x] T036 [P] Add frontend performance guard test for filter responsiveness in `frontend/src/lib/components/reports/__tests__/reports_filter_performance.test.js` +- [x] T036a [P] Implement virtualization or pagination optimization for large lists (>1000 items) in `ReportsList.svelte` to satisfy FR-011. +- [x] T037 Update operational docs for reports usage and troubleshooting in `docs/settings.md` and `docs/design/resource_centric_layout.md` +- [x] T038 Run end-to-end quickstart validation and capture results in `specs/020-task-reports-design/quickstart.md` + +--- + +## Dependencies & Execution Order + +### Phase Dependencies + +- Phase 1 → no dependencies. +- Phase 2 depends on Phase 1 and blocks all user stories. +- Phase 3 (US1) depends on Phase 2. +- Phase 4 (US2) depends on Phase 2; can proceed after US1 baseline route/list exists. +- Phase 5 (US3) depends on Phase 2 and uses US1 list interaction. +- Phase 6 depends on completion of selected user stories. + +### User Story Dependency Graph + +- **US1 (P1)**: first deliverable (MVP). +- **US2 (P2)**: extends US1 presentation semantics. +- **US3 (P3)**: extends US1 with detail drill-down and diagnostics. + +Graph: `US1 -> {US2, US3}` + +### Parallel Opportunities + +- Setup fixture/i18n tasks: T002, T003, T004. +- Foundational tasks: T006 and T011 parallel with model scaffolding once T005 is done. +- US1 tests T012/T013 in parallel. +- US2 tests T020/T021 in parallel. +- US3 tests T027/T028 and UI detail task T031 in parallel after endpoint contract is stable. +- Cross-cutting checks T035/T036 parallel in Phase 6. + +--- + +## Parallel Example: User Story 1 + +```bash +Task: "T012 [US1] Add backend contract tests in backend/tests/test_reports_api.py" +Task: "T013 [US1] Add frontend integration test in frontend/src/lib/components/reports/__tests__/reports_page.integration.test.js" + +Task: "T015 [US1] Implement reports route in frontend/src/routes/reports/+page.svelte" +Task: "T016 [US1] Implement list component in frontend/src/lib/components/reports/ReportsList.svelte" +``` + +## Parallel Example: User Story 3 + +```bash +Task: "T027 [US3] Add backend detail contract tests in backend/tests/test_reports_detail_api.py" +Task: "T028 [US3] Add frontend detail integration test in frontend/src/lib/components/reports/__tests__/report_detail.integration.test.js" + +Task: "T030 [US3] Implement detail service assembly in backend/src/services/reports/report_service.py" +Task: "T031 [US3] Implement report detail panel in frontend/src/lib/components/reports/ReportDetailPanel.svelte" +``` + +--- + +## Implementation Strategy + +### MVP First (Recommended) + +1. Complete Phase 1 + Phase 2. +2. Complete Phase 3 (US1) and validate independent test. +3. Demo/deploy MVP unified report list. + +### Incremental Delivery + +1. Add US2 for visual differentiation after MVP list stability. +2. Add US3 for diagnostics/detail depth. +3. Finish Phase 6 polish and conformance. + +### UX Preservation Rule + +No task in this plan intentionally degrades the UX defined in [`ux_reference.md`](specs/020-task-reports-design/ux_reference.md). +Each user story contains a mandatory UX verification task: T019, T026, T034. \ No newline at end of file diff --git a/specs/020-task-reports-design/ux_reference.md b/specs/020-task-reports-design/ux_reference.md new file mode 100644 index 0000000..8727812 --- /dev/null +++ b/specs/020-task-reports-design/ux_reference.md @@ -0,0 +1,100 @@ +# UX Reference: Unified Task Reports by Type + +**Feature Branch**: `020-task-reports-design` +**Created**: 2026-02-22 +**Status**: Draft + +## 1. User Persona & Context + +* **Who is the user?**: Operations engineer or analytics platform administrator who monitors task outcomes. +* **What is their goal?**: Quickly understand results across all task categories and identify items that require action. +* **Context**: Working in the web interface during daily operational checks, often under time pressure and with mixed task activity (LLM checks, backups, migrations, documentation jobs). + +## 2. The "Happy Path" Narrative + +The user opens Reports and immediately sees a unified stream of all task outcomes. Each report card is visually distinct by task type, so the user can scan and recognize categories without reading everything line by line. They apply a status filter to find only failed items, open one report, and instantly understand what happened and what to do next. The page feels organized, predictable, and fast to scan even with many entries. The user resolves priorities without switching across multiple sections. + +## 3. Interface Mockups + +### UI Layout & Flow (if applicable) + +**Screen/Component**: Unified Reports Dashboard + +* **Layout**: + - Header row with page title, summary counters, and last update timestamp. + - Filter toolbar below header (Type, Status, Time Range, Search). + - Main content area with report cards/list rows sorted by latest update. + - Optional right-side detail panel or drill-in page for selected report. +* **Key Elements**: + * **Type Filter**: Multi-select control with options: LLM documentation/verification, Backup, Migration, Documentation. + * **Status Filter**: Values: Success, Failed, In Progress, Partial. + * **Report Card / Row**: Shows type badge, title, short summary, status indicator, timestamp, and quick action "View details". + * **Type Badge**: Explicit textual label + visual style (color/icon/pattern) unique per task type. + * **Empty State Block**: Guidance text and reset-filters action when no reports match current filters. +* **States**: + * **Default**: Mixed reports displayed with clear type distinctions and latest-first ordering. + * **Loading**: Skeleton placeholders in report list area; filters remain visible. + * **Success**: Updated reports appear with subtle confirmation cue ("Reports updated"). + * **No Data**: Friendly empty state, explains there are no reports yet for selected scope. + * **Filtered Empty**: "No reports match your filters" with one-click clear filter action. + +### Visual Language by Report Type + +1. **LLM Documentation/Verification** + - Emphasis: Review and validation. + - Visual cues: Analysis-style badge and prominent summary snippet with confidence/verification context. + - Reading focus: Findings, checks performed, verification result. + +2. **Backup** + - Emphasis: Safety and recoverability. + - Visual cues: Protection-style badge and quick visibility of snapshot/time/coverage outcomes. + - Reading focus: Completion confirmation, backup scope, recoverability notes. + +3. **Migration** + - Emphasis: Change progression and risk. + - Visual cues: Transition-style badge and timeline/progress context. + - Reading focus: Objects moved, status by stage, blockers or rollback guidance. + +4. **Documentation** + - Emphasis: Content updates and clarity. + - Visual cues: Document-style badge and concise change summary. + - Reading focus: What was updated, affected sections, quality/review notes. + +## 4. The "Error" Experience + +**Philosophy**: Show what went wrong in plain language, preserve user context, and provide immediate next steps. + +### Scenario A: Partial or Missing Report Data + +* **User Action**: Opens a report where some expected fields are absent. +* **System Response**: + * Missing values are shown as explicit placeholders (e.g., "Not provided") instead of blank spaces. + * An inline notice explains that report data is incomplete but still viewable. +* **Recovery**: User can continue reviewing available data and use suggested follow-up action (e.g., retry load or inspect source task). + +### Scenario B: Unknown Task Type + +* **System Response**: + * Report remains visible using a neutral fallback style labeled "Other / Unknown Type". + * A short note indicates this type is not yet mapped to a dedicated design profile. +* **Recovery**: User can still read status/details and proceed; no data is hidden or blocked. + +### Scenario C: No Reports Match Filters + +* **User Action**: Applies strict type + status filters and gets empty results. +* **System Response**: + * Clear empty-filter message in the content area. + * One-click actions: "Clear filters" and "Show all recent reports". +* **Recovery**: User restores broader scope without reloading the page. + +### Scenario D: Failed Report + +* **System Response**: + * Failure status is explicit and visually prominent. + * Detail view includes brief reason, impact summary, and recommended next action. +* **Recovery**: User can quickly decide whether to rerun, escalate, or investigate. + +## 5. Tone & Voice + +* **Style**: Concise, operational, confidence-building. +* **Terminology**: Use "Report", "Task Type", "Status", "Details", "Next Action"; avoid ambiguous shorthand. \ No newline at end of file