105 lines
9.0 KiB
Markdown
105 lines
9.0 KiB
Markdown
# UX Reference: Dataset Lifecycle Workspace
|
||
|
||
**Feature Branch**: `030-dataset-lifecycle-workspace`
|
||
**Created**: 2026-05-19
|
||
**Status**: Draft
|
||
|
||
## 1. User Persona & Context
|
||
|
||
- **Who is the user?**: Data Analyst / Data Engineer, работающий с датасетами Apache Superset через ss-tools. Технически подкован, понимает структуру таблиц, колонок и метрик.
|
||
- **What is their goal?**: Быстро оценить состояние датасетов (какие без маппинга, какие без описаний), просмотреть детали конкретного датасета, отредактировать описания колонок/метрик, запустить bulk-операции (маппинг, генерация документации).
|
||
- **Context**: Работает в браузере на десктопе (1920×1080) или ноутбуке (1366×768). Может использовать планшет. Всегда в рамках выбранного окружения (dev/staging/prod).
|
||
|
||
## 2. The "Happy Path" Narrative
|
||
|
||
Аналитик открывает страницу датасетов и сразу видит Stats Bar: 142 датасета всего, 38 без маппинга, 89 с описанием, 12 связаны с дашбордами. Он кликает "⚠️ Без маппинга" — список слева мгновенно фильтруется до 38 датасетов. Выбирает первый датасет в списке — справа без перезагрузки открывается детальная панель: хедер с именем таблицы и схемой, секция колонок с progress-индикаторами описаний, секция метрик. Видит колонку без описания, кликает "✏️ Добавить описание" — появляется textarea, вводит описание, сохраняет. Описание мгновенно отображается. Затем выделяет 3 датасета через чекбоксы, внизу появляется панель — запускает "Маппинг колонок" для всех трёх одним кликом.
|
||
|
||
## 3. Interface Mockups
|
||
|
||
### UI Layout & Flow
|
||
|
||
**Page**: `/datasets`
|
||
|
||
- **Layout**: Двухколоночный split-view (40/60) на десктопе. При < 768px — одноколоночный с slide-over для деталей.
|
||
- **Key Elements**:
|
||
- **Stats Bar**: 4 метрики в строке вверху, каждая — кнопка-фильтр с иконкой, числом и подписью. Активная метрика подсвечена (primary background).
|
||
- **Left Panel**: Список карточек датасетов с поиском и пагинацией. Каждая карточка содержит чекбокс.
|
||
- **Right Panel**: Детальная панель с хедером, таблицами колонок/метрик, связанными дашбордами.
|
||
- **Bulk Action Bar**: Fixed bottom panel, slides up when 2+ datasets selected.
|
||
- **Map Columns Modal**: Reused from existing implementation.
|
||
- **Generate Docs Modal**: Reused from existing implementation.
|
||
- **Contract Mapping**:
|
||
- **`@UX_STATE`**:
|
||
- `Loading` — Stats Bar skeleton + Left panel skeleton (5 placeholder cards).
|
||
- `Loaded` — Stats Bar with counts + left panel cards + right panel placeholder ("Выберите датасет").
|
||
- `Loaded-Detail` — Right panel filled with dataset details.
|
||
- `Filtered` — Stats Bar with active metric highlighted + filtered card list.
|
||
- `Selecting` — Checkboxes checked on cards + floating bulk action panel visible.
|
||
- `Editing` — Inline textarea open on a column/metric row.
|
||
- `Saving` — Textarea disabled with spinner, save button shows "Сохранение...".
|
||
- `Error-Detail` — Right panel error banner with retry.
|
||
- `Error-List` — Full page error banner with retry.
|
||
- **`@UX_FEEDBACK`**:
|
||
- Stats Bar metric click → instant list filter + metric highlight.
|
||
- Dataset card click → right panel loads detail (spinner then content).
|
||
- Save description → "✓ Сохранено" toast + textarea closes.
|
||
- Save error → red border on textarea + "⚠️ Ошибка сохранения" below.
|
||
- Slide-over (mobile) → smooth slide from right with backdrop.
|
||
- **`@UX_RECOVERY`**:
|
||
- API error in right panel → click "Retry" to reload dataset detail.
|
||
- API error in list → click "Retry" to reload full list.
|
||
- Save conflict → show warning "Данные были изменены другим пользователем. Обновить?"
|
||
- Network offline → show offline banner, auto-retry on reconnect.
|
||
- **`@UX_REACTIVITY`**:
|
||
- `$state` for: `selectedDatasetId`, `activeFilter`, `selectedIds`, `editingCell`
|
||
- `$derived` for: `filteredDatasets` (based on `activeFilter` + `searchQuery`)
|
||
- `$effect` for: loading dataset detail when `selectedDatasetId` changes
|
||
- `$props` for: reusable card component (`DatasetCard.svelte`), detail panel component (`DatasetDetailPanel.svelte`)
|
||
- **States**:
|
||
- **Idle/Default**: Stats Bar shows counts, left panel shows paginated cards, right panel shows "Выберите датасет для просмотра деталей" placeholder.
|
||
- **Loading**: Skeleton loaders for Stats Bar (4 count placeholders), Left Panel (5 card placeholders with shimmer), Right Panel placeholder.
|
||
- **Success**: All data loaded, interactions responsive (filter, select, edit).
|
||
- **Error/Degraded**: If list fails → full page error. If detail fails → error in right panel only, list still navigable.
|
||
|
||
## 4. The "Error" Experience
|
||
|
||
**Philosophy**: Не просто сообщить об ошибке, а дать пользователю путь к восстановлению.
|
||
|
||
**Semantic Requirement**: Every documented failure path here should map to `@UX_RECOVERY` and, where relevant, `@UX_FEEDBACK` in the generated component contracts.
|
||
|
||
### Scenario A: API 503 (Superset недоступен)
|
||
|
||
- **User Action**: Открывает страницу датасетов.
|
||
- **System Response**:
|
||
- (UI) Full-page error banner: "⚠️ Не удалось загрузить датасеты. Сервер Superset временно недоступен." + кнопка "Повторить".
|
||
- Stats Bar скрыт или показывает "--" для всех метрик.
|
||
- **Recovery**: Кнопка "Retry" перезагружает список. Автоматический retry через 30s.
|
||
|
||
### Scenario B: Ошибка загрузки деталей датасета
|
||
|
||
- **User Action**: Кликает на карточку датасета в левой панели.
|
||
- **System Response**:
|
||
- (UI) В правой панели появляется ошибка: "⚠️ Не удалось загрузить детали датасета." + кнопка "Повторить".
|
||
- Левая панель остаётся рабочей — пользователь может выбрать другой датасет.
|
||
- **Recovery**: Клик "Retry" перезагружает детали. Список остаётся навигабельным.
|
||
|
||
### Scenario C: Ошибка сохранения описания (inline edit)
|
||
|
||
- **User Action**: Вводит описание в textarea, нажимает "Сохранить".
|
||
- **System Response**:
|
||
- (UI) Красная обводка textarea + сообщение под ней: "⚠️ Ошибка сохранения. Проверьте соединение и попробуйте снова."
|
||
- Textarea остаётся открытой с введённым текстом (не теряется).
|
||
- **Recovery**: Повторное нажатие "Сохранить" либо "Отмена" для выхода без сохранения.
|
||
|
||
### Scenario D: Конфликт при сохранении (409 Conflict)
|
||
|
||
- **User Action**: Сохраняет описание, но данные были изменены другим пользователем.
|
||
- **System Response**:
|
||
- (UI) Предупреждение: "⚠️ Данные были изменены. Обновить страницу?" с кнопками "Обновить" и "Отмена".
|
||
- **Recovery**: Кнопка "Обновить" перезагружает детали датасета.
|
||
|
||
## 5. Tone & Voice
|
||
|
||
- **Style**: Concise, technical, task-oriented. Русский и английский.
|
||
- **Terminology**: "Датасет" (не "таблица" или "источник данных"), "Маппинг" (не "сопоставление"), "Колонка" (не "столбец" или "поле"), "Метрика" (не "показатель").
|