93 lines
4.2 KiB
Markdown
93 lines
4.2 KiB
Markdown
# 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. |