# UX Reference: Task Logging System (Separated Per-Task Logs)

**Feature Branch**: `018-task-logging-v2`
**Created**: 2026-02-07
**Status**: Draft

## 1. User Persona & Context

*   **Who is the user?**: System Administrator / DevOps Engineer / Developer.
*   **What is their goal?**: Monitor task execution in real-time, debug failures by isolating logs from specific components (e.g., Superset API vs. Git operations), and review historical logs of completed tasks.
*   **Context**: Using the web dashboard to run migrations, backups, or LLM analysis.

## 2. The "Happy Path" Narrative

The user starts a migration task and immediately sees the log panel. As the task progresses, logs appear with clear color-coded tags indicating their source (e.g., `[superset_api]`, `[git]`). The user notices a warning from the `superset_api` source, clicks the "Source" filter, and selects "superset_api" to isolate those messages. The view instantly updates to show only API-related logs, allowing the user to quickly identify a rate-limiting warning. Once the task finishes, the user refreshes the page, and the logs are still there, fully searchable and filterable.

## 3. Interface Mockups

### UI Layout & Flow

**Screen/Component**: TaskLogPanel (within Task Details)

*   **Layout**: A header with filter controls, followed by a scrollable log area.
*   **Key Elements**:
    *   **Level Filter**: Dropdown (All, Info, Warning, Error, Debug).
    *   **Source Filter**: Dropdown (All, plugin, superset_api, storage, etc.).
    *   **Search Input**: Text field with "Search logs..." placeholder.
    *   **Log Area**: Monospace font, alternating row backgrounds.
    *   **Progress Bar**: Inline bar appearing within a log row when a component reports progress.
*   **States**:
    *   **Default**: Shows all logs for the current task.
    *   **Filtering**: Log list updates as filters are changed (live for running tasks via WS).
    *   **Auto-scroll**: Enabled by default; a "Jump to Bottom" button appears if the user scrolls up.

## 4. The "Error" Experience

### Scenario A: Log Loading Failure

*   **User Action**: Opens a historical task with thousands of logs.
*   **System Response**: A small inline notification: "Failed to load full log history. [Retry]".
*   **Recovery**: Clicking "Retry" re-triggers the REST API call.

### Scenario B: WebSocket Disconnect

*   **System Response**: The log panel shows a "Reconnecting..." status indicator.
*   **Recovery**: System automatically reconnects; once back, it fetches missing logs since the last received timestamp.

## 5. Tone & Voice

*   **Style**: Technical, precise, and informative.
*   **Terminology**: Use "Source" for component identification, "Level" for severity, and "Persistence" for saved logs.