busya/ss-tools

Files

busya 008b6d72c9 таски готовы

2026-02-23 10:18:56 +03:00

5.2 KiB

Raw Blame History

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.

UnifiedReportsPage requests filtered list (status=failed, task_type=migration) through ReportsApiClient.
ReportsApiClient calls ReportsApiContract list endpoint.
ReportsAggregationModule normalizes task records and returns canonical report items.
UnifiedReportsPage enters Ready @UX_STATE, rendering migration-specific visual profile.
Operator opens one report detail.
ReportsApiContract detail endpoint returns diagnostics + next_actions.
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.