Fimeg/Redflag
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Redflag/docs/historical/UX_ISSUE_ANALYSIS_scan_history.md

6.8 KiB
Raw Permalink Blame History

UX Issue Analysis: Generic "SCAN" in History vs Per-Subsystem Scan Buttons

Date: 2025-12-18
Status: UX Issue Identified - Not a Bug
Severity: Medium (Confusing but functional)

Problem Statement

The UI shows individual "Scan" buttons for each subsystem (docker, storage, system, updates), but the history page displays only the generic action "SCAN" without indicating which subsystem was scanned. This creates confusion:

  • User scans storage → History shows "SCAN"
  • User scans system → History shows "SCAN"
  • User scans docker → History shows "SCAN"

Result: Cannot distinguish which scan ran from history alone.

Root Cause Analysis

✅ What's Working Correctly

  1. UI Layer (AgentHealth.tsx)

    • Lines 423-435: Each subsystem has distinct "Scan" button
    • Line 425: handleTriggerScan(subsystem.subsystem) passes subsystem name
    • ✅ Correct: Per-subsystem scan triggers

  2. Backend API (subsystems.go)

    • Line 239: commandType := "scan_" + subsystem
    • Creates distinct commands: "scan_storage", "scan_system", "scan_docker", etc.
    • ✅ Correct: Backend distinguishes scan types

  3. Agent Handling (main.go)

    • Lines 887-890: Each scan type has dedicated handler
    • ✅ Correct: Different scan types processed appropriately

❌ Where It Breaks Down

History Logging/Display

When scan results are logged to the history table, the action field is set to generic "scan" instead of the specific scan type.

Current Flow:

User clicks "Scan Storage" → API: "scan_storage" → Agent: handles storage scan → History: action="scan" → UI displays: "SCAN"
User clicks "Scan Docker"  → API: "scan_docker"   → Agent: handles docker scan  → History: action="scan" → UI displays: "SCAN"

Result: Both appear identical in history despite scanning different things.

File: aggregator-web/src/components/HistoryTimeline.tsx:367

<span className="font-medium text-gray-900 capitalize">
  {entry.action}  {/* Just shows "scan" for all */}
</span>

Where the Data Exists

The subsystem information is available in the system:

  1. AgentCommand table: command_type field stores "scan_storage", "scan_system", etc.
  2. AgentSubsystem table: subsystem field stores subsystem names
  3. Backend handlers: Each has access to which subsystem is being scanned

BUT: When creating HistoryEntry, only generic "scan" is stored in the action field.

User Impact

Current User Experience:

  1. User clicks "Scan" button on Storage subsystem
  2. Scan runs successfully, results appear
  3. User checks History page
  4. Sees: "SCAN - Success - 4 updates found"
  5. User can't tell if that was Storage scan or System scan or Docker scan
  6. User has to navigate back to AgentHealth to check scan results
  7. If multiple scans run, history is a generic list of indistinguishable "SCAN" entries

Real-World Scenario:

History shows:
- [14:20] SCAN → Success → 4 updates found (0s duration)
- [14:19] SCAN → Success → 461 updates found (2s duration)  
- [14:18] SCAN → Success → 0 updates found (1s duration)

Which scan found which updates? Unknown without context.

Why This Matters

  1. Debugging Difficulty: When investigating scan issues, cannot quickly identify which subsystem scan failed
  2. Audit Trail: Cannot reconstruct scan history to understand system state over time
  3. UX Confusion: User interface suggests per-subsystem control, but history doesn't reflect that granularity
  4. Operational Visibility: System administrators can't see which types of scans run most frequently

Why This Happened

Architecture Decision History:

  1. Early Design: Simple command system with generic actions ("scan", "install", "upgrade")
  2. Subsystem Expansion: Added docker, storage, system scans later
  3. Database Schema: Didn't evolve to include scan type metadata
  4. UI Display: Shows action field directly without parsing/augmenting

The Problem: Database schema and history logging didn't evolve with feature expansion.

Potential Solutions (Not Immediate Changes)

Option 1: Store full command type in history.action

  • Change: Store "scan_storage" instead of "scan"
  • Impact: Most backward compatible
  • UI Change: History shows "scan_storage", "scan_system", "scan_docker"

Option 2: Add subsystem column to history table

  • Add: subsystem field to history/logs table
  • Migration: Update existing scan entries
  • UI Change: Display "SCAN (storage)", "SCAN (system)" etc.

Option 3: Parse in UI

  • Keep: action="scan" in DB
  • Add: metadata field with subsystem context
  • UI: Display "{subsystem} scan" with icon per subsystem type

Option 4: Reconstructed from command results

  • Parse: The stdout/results to determine scan type
  • UI: "SCAN - Storage: 4 updates found"
  • Complexity: Fragile, depends on output format

Recommended Solution

Option 2 is best:

  1. Add subsystem column to history table
  2. Populate during scan result logging
  3. Update UI to display: <icon> {subsystem} scan
  4. Add subsystem-specific icons to history view

Example:

History would show:
- [14:20] 💾 Storage Scan → Success → 4 updates found
- [14:19] 📦 DNF Scan → Success → 461 updates found
- [14:18] 🐳 Docker Scan → Success → 0 updates found

Scope of Change

Backend:

  • Database migration: Add subsystem column
  • Query updates: Select subsystem field
  • Logging: Pass subsystem when creating history entries

Frontend:

  • Type update: Add subsystem to HistoryEntry interface
  • Display logic: Show subsystem name and icon
  • Filter enhancement: Filter by subsystem type

Files to Modify:

  • Database schema and queries
  • HistoryEntry interface in HistoryTimeline.tsx
  • Display logic in HistoryTimeline.tsx
  • History creation in multiple places

Severity Assessment

Impact: Medium (confusing but functional)
Urgency: Low (doesn't break functionality)
User Frustration: Moderate-High (creates confusion, impedes debugging)
Recommended Action: Plan for future enhancement, but not a production blocker

How to Address This

For Now: Document the limitation
Short Term: Add note to UI explaining all scans show as "SCAN"
Medium Term: Implement Option 2 or similar fix
Long Term: Review other places where generic actions need context

Conclusion

This is NOT a bug - the system works correctly:

  • Scans run for correct subsystems
  • Results are accurate
  • Backend distinguishes scan types

This IS a UX issue - the presentation is confusing:

  • History doesn't show which subsystem was scanned
  • Impedes debugging and audit trails
  • Creates cognitive dissonance with per-subsystem UI

The Fix: Add subsystem context to history logging/display (planned for future enhancement)

Reference in New Issue View Git Blame Copy Permalink