85 lines
3.6 KiB
Markdown
85 lines
3.6 KiB
Markdown
# UX Reference: LLM Chat Assistant for Project Operations
|
||
|
||
**Feature Branch**: `021-llm-project-assistant`
|
||
**Created**: 2026-02-23
|
||
**Status**: Draft
|
||
|
||
## 1. User Persona & Context
|
||
|
||
* **Who is the user?**: Platform operator, dashboard engineer, or admin managing Superset operations.
|
||
* **What is their goal?**: Execute routine and critical project operations quickly via natural language with safe controls.
|
||
* **Context**: User is already in `ss-tools` web interface and wants to avoid jumping between Git, migration, backup, and task pages.
|
||
|
||
## 2. The "Happy Path" Narrative
|
||
|
||
The user opens assistant chat from the main interface and enters a natural command to run an operation. Assistant immediately recognizes intent, validates permissions, and either executes directly or asks for confirmation if operation is risky. For long-running actions, assistant responds instantly with `task_id` and where to track progress. User can ask follow-up status questions in the same chat and receives concise operational answers.
|
||
|
||
## 3. Interface Mockups
|
||
|
||
### UI Layout & Flow (if applicable)
|
||
|
||
**Screen/Component**: Assistant Chat Panel
|
||
|
||
* **Layout**:
|
||
- Right-side drawer or modal panel with message history.
|
||
- Input area at bottom with send action and command examples shortcut.
|
||
- Message cards with role (User/Assistant), timestamp, state badge.
|
||
* **Key Elements**:
|
||
* **Chat Input**: Supports free-text commands in RU/EN.
|
||
* **State Badge**: `started`, `success`, `failed`, `needs_confirmation`, `denied`.
|
||
* **Confirmation Card**: Explicit confirm/cancel buttons for risky actions.
|
||
* **Task Link Chip**: `task_id` chip with quick open in Task Drawer.
|
||
* **Suggestions Block**: "Try command" examples for supported domains.
|
||
* **States**:
|
||
* **Default**: Empty or recent history shown, examples visible.
|
||
* **Parsing**: Inline "Analyzing command..." loading state.
|
||
* **Needs Confirmation**: Warning card with operation summary and target environment.
|
||
* **Started**: Immediate message with `task_id` and tracking hint.
|
||
* **Error**: Error card with reason and recovery suggestion.
|
||
|
||
### Interaction Examples
|
||
|
||
```text
|
||
User: запусти миграцию с dev на prod для дашборда 42
|
||
Assistant: Операция рискованная (target=production). Подтвердите запуск.
|
||
[Confirm] [Cancel]
|
||
|
||
User: confirm
|
||
Assistant: Миграция запущена. task_id=task-8f13. Прогресс: Task Drawer / Reports.
|
||
```
|
||
|
||
## 4. The "Error" Experience
|
||
|
||
**Philosophy**: Never silently fail. Show what happened, why, and what to do next.
|
||
|
||
### Scenario A: Ambiguous Command
|
||
|
||
* **User Action**: "сделай задачу для дашборда 42"
|
||
* **System Response**:
|
||
* Assistant does not execute immediately.
|
||
* Returns clarification question with options (Git branch / migration / backup / analysis).
|
||
* **Recovery**: User selects one option or reformulates command.
|
||
|
||
### Scenario B: Permission Denied
|
||
|
||
* **User Action**: Non-admin requests production deploy.
|
||
* **System Response**:
|
||
* Assistant returns `denied` state with minimal permission reason.
|
||
* No task is created.
|
||
* **Recovery**: User requests access or uses allowed operation.
|
||
|
||
### Scenario C: Confirmation Timeout
|
||
|
||
* **System Response**: "Confirmation expired. Operation was not executed."
|
||
* **Recovery**: User reissues command.
|
||
|
||
### Scenario D: Downstream Failure After Start
|
||
|
||
* **System Response**: Assistant returns `task_id` and indicates task moved to failed state with short error summary.
|
||
* **Recovery**: Open task logs/reports using provided link/action.
|
||
|
||
## 5. Tone & Voice
|
||
|
||
* **Style**: Operational, concise, explicit.
|
||
* **Terminology**: Use "command", "task", "confirmation", "status", "task_id"; avoid vague wording.
|