8.0 KiB
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:
- 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.
- 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:
- 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.
- 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:
- Given a successful report, When the user views its details, Then the report clearly presents completion status, summary, and execution time context.
- 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, andpending. - 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.