4.2 KiB
Phase 0 Research: Unified Task Reports by Type
Feature: 020-task-reports-design
Input Spec: spec.md
Related UX: ux_reference.md
1) Normalizing heterogeneous task outputs into one report model
Decision
Adopt a two-layer report model:
- Canonical Report Envelope shared across all task types.
- 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 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.