таски готовы

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.