таски готовы

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.