таски готовы

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
+
+<!-- [DEF:UnifiedReportsPage:Component] -->
+/**
+ * @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.
+ */
+<!-- [/DEF:UnifiedReportsPage] -->
+
+---
+
+## 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.