257 lines
21 KiB
Markdown
257 lines
21 KiB
Markdown
# UI-спека Ratatoskr (Fyne Desktop)
|
||
|
||
Статус: утверждается. Черновик, обсуждаем дальше (архитектура обмена UI <-> Core).
|
||
|
||
Стек: **Go + Fyne** (свежая стабильная версия). Платформа: **Windows** (Linux пока не поддерживаем).
|
||
|
||
---
|
||
|
||
## 1. Цель и роль UI
|
||
|
||
1. UI — **полноценный инструмент** (не только админ-панель): управляет всем, чем управляет Telegram, и становится **основным** интерфейсом.
|
||
2. Один пользователь, один человек (без multi-user / мультисессии).
|
||
3. UI должен уметь **всё, что умеет Telegram-интерфейс**, и станет основным; Telegram остаётся как один из каналов.
|
||
4. UI — **графическая оболочка самого приложения** (одна программа), не отдельный process.
|
||
5. Внутри оболочки запускается **ботик сам**; UI — это лишь ещё одна реализация `chat.Channel`.
|
||
6. Запуск: **обычный запуск бинаря** → UI. Режим без UI — только по флагу **`--noui`**.
|
||
- Логика: UI включён по умолчанию, headless — опционально (`--noui`).
|
||
7. Трей-иконка не нужна.
|
||
8. При закрытии окна — **сворачивать** (не завершать процесс). Для полного выхода — **отдельная кнопка** «Завершить», чтобы бот остановился.
|
||
9. Конфиг-секции редактировать в UI пока не нужно; **hot-reload конфига** — желательно, если реализуемо (запланировать как «если возможно — да»).
|
||
|
||
## 2. Компоновка (layout)
|
||
|
||
- Базовый grid по умолчанию:
|
||
- **слева — список задач** (широкая колонка),
|
||
- **по центру/право — рабочая область** (в ней живёт «работа бота» / live-шаги);
|
||
- рабочая область может **разделяться на сплит-панели** (2×2, не считая левой колонки с задачами).
|
||
- Табы пока **не делаем** (первый этап).
|
||
- Панели должны быть **сворачиваемыми** (хотя бы левая колонка с задачами).
|
||
- Сохранение layout (положение/размеры панелей) — **нужно**, переживает перезапуск приложения (Fyne Preferences).
|
||
- Окно: **на весь экран по умолчанию**.
|
||
- Нижняя панель: **вкладки «Логи», «Состояние»**:
|
||
- **Логи** — ведение логов (поток системных логов);
|
||
- **Состояние** — живое состояние текущих задач / на каком статусе сейчас задача.
|
||
- Верхняя панель: **меню**, пока только пункт «О программе» (About → About).
|
||
- Тема: **тёмная**, без переключателя темы; стартуем с **дефолтной темы Fyne**.
|
||
- Локаль: **en** (интерфейс на английском).
|
||
|
||
## 3. Данные задач
|
||
|
||
- Задачи отображаются **списком** слева: **краткое название + служебное** (воркшоп).
|
||
- Детализация списка (статус/фильтры/поиск/сортировка/по умолчание/пагинация) — **дорабатываем потом**.
|
||
- В деталях задачи (рабочая область) показываем все перечисленные поля:
|
||
- Title, Goal, Why, AC (acceptance criteria), Repo(s), Tag (task_tag), статус, CreatedAt/UpdatedAt, вложенные трассы (traces), история чата (history), включая (session id opencode).
|
||
- История чата из БД (user/assistant) — лента сообщений.
|
||
- Трейсы агентов (аналист/dev/reviewer) — дерево шагов/ходов + raw output.
|
||
- Live-шаги (LiveRegistry) — восстановить и показывать в реальном времени.
|
||
|
||
## 4. Действия с задачами
|
||
|
||
- UI поддерживает все действия, доступные в TG: создание задачи, изменение, **approve**, **rework доработка**, **cancel**, **retry**, закрытие (skip/continue), статусы — в рамках валидных переходов.
|
||
- Создание задачи — форма с полями (Title, Goal/Why, Repos, AC) (какие обязательные — уточнить).
|
||
- Работа с статусами: эмуляция команд `/approve`, `/retry`, `/cancel` и т.п. (валидные переходы по state machine)
|
||
- Подтверждения опасных действий (удаление задачи, и т.п.).
|
||
- Редактирование полей (repo, AC, tags) из UI — по необходимости.
|
||
|
||
## 7. Мониторинг системы
|
||
|
||
- Показывать **логи** (готовый поток из `log`), **фреймы состояния** бота:
|
||
- статус opencode serve/pool, коннекции, активные сессии.
|
||
- Live-статус задач (`/status N`) эквивалентом — во вкладке «Состояние».
|
||
- Нужен индикатор занятости агента («опенкод думает/dev writing…»).
|
||
|
||
## 8. Настройки / конфиг
|
||
|
||
- Настройки в UI пока **не выводим**; секреты никоим образом не показываем.
|
||
- Кнопка «Завершить» (выход приложения) — в меню.
|
||
- Перезапуск бота из UI — пока не надо.
|
||
|
||
## 9. Живое обновление / консистентность
|
||
|
||
- **Шина событий (event-bus)** — запланирована: UI получает события из ядра (новые задачи, изменение статусов, live-шаги, логи). Явно нужен.
|
||
- UI и Telegram — **оболочки** вокруг одного ядра; обмен через **интерфейс (абстракцию)**, не зашумляя ядро.
|
||
- Консистентность между TG и UI при параллельных изменениях — через события ядра; архитектура обмена — см. раздел 12.
|
||
|
||
## 10. Технические
|
||
|
||
- **Fyne**: свежая стабильная (последняя).
|
||
- **Абстракция БД**: доступ к storage через **интерфейс** (не прямиком к *storage.Storage) для тестируемости.
|
||
- Пакет: **`internal/ui`** (+ подпакеты при необходимости).
|
||
- Тесты: юнит-тесты модели, **без e2e/UI-тестов** пока.
|
||
- Использование данных: **вся история** (без ограничения по времени).
|
||
|
||
## 11. Скоуп первого этапа
|
||
|
||
- Минимальный UI, покрывающий **функционал Telegram-интерфейса** (все команды/действия).
|
||
- Также UI — основной интерфейс (TG остаётся каналом).
|
||
|
||
---
|
||
|
||
## 12. Архитектура обмена UI ↔ Core (best practices)
|
||
|
||
### 12.1. Слои и направление зависимостей
|
||
|
||
```
|
||
┌──────────────┐ команды → ┌─────────────────┐ заказы/готовое → ┌──────────────┐
|
||
│ UI (Fyne) │ ───────────▶ │ Application / │ ─────────────────▶ │ Domain/core │
|
||
│ «представ- │ │ UseCase слой │ события (events) │ (model) │
|
||
│ ление» │ ◀─────────── │ │ ◀────────────────── │ │
|
||
└──────────────┘ события ← └─────────────────┘ └──────────────┘
|
||
```
|
||
|
||
- **Core** (`internal/core`.ProcessTurn — state-machine) **не трогаем**. Он — источник правды.
|
||
- **App** (`internal/app`) — use-case/композиция: политика «одна активная задача на чат», `Notify`, роутинг команд.
|
||
- **UI** — ещё одна реализация `chat.Channel` (параллельно Telegram). Уже есть идеальный «port»: интерфейс `Channel{Run, OnMessage, Send, Ask, Close}`.
|
||
|
||
### 12.2. UI получает состояние, а не управляет Core'ом (uni-directional data flow)
|
||
|
||
- Core **мутирует состояние** (БД, worker, аналитик). UI — только **читает снимки** и реагирует на события, обновляя своё view-model (не БД и не core).
|
||
- Действия UI = **команды** (`CreateTask`, `ApproveTask`, `RetryTask`, `CancelTask`, `ContinueTask`), которые вызывают use-case в Core.
|
||
- Это даёт: единый источник правды, простую отладку, лёгкое тестирование без UI.
|
||
|
||
### 12.3. Обмен = событийная шина (event bus / pub-sub)
|
||
|
||
- **Core — публикует** доменные события, UI — **подписчик**:
|
||
- `TaskCreated{id, chatID}`
|
||
- `TaskStatusChanged{id, from, to}` (ready/approved/running/success/failed/timeout…)
|
||
- `TaskHistoryAppended{id, role, content}`
|
||
- `TraceAppended{id, agent, status, output}`
|
||
- `AgentActivity{id, agent, stage}` (live-шаги, индикаторы занятости)
|
||
- `LogLine` (системные логи для вкладки «Логи»)
|
||
- **Направление однонаправленное**: core/worker/analyst не знают, кто подписан; никаких прямых вызовов Fyne из core!
|
||
- Реализация малая: `Bus` с `Subscribe/Unsubscribe/Publish` + buffered channels (`n`-подписчиков или `select`); паттерн уже есть в `chat.Router` (внутренний `incoming` channel).
|
||
- Сигнатуры событий использовать **и для консистентности** TG↔UI (оба канала — простые подписчики/клиенты шины).
|
||
|
||
### 12.4. Модель потоков Fyne (v2.6+) и `fyne.Do`
|
||
|
||
- Fyne с v2.6.0 выполняет все события/колбэки **на одной главной goroutine**.
|
||
- Фоновые goroutine (worker, opencode polling, ход core) **не должны модифицировать UI напрямую**.
|
||
- Любое обновление виджетов из своей goroutine — через:
|
||
- `fyne.Do(func(){ widget.X = …; widget.Refresh() })` — очередь в следующий кадр;
|
||
- `fyne.DoAndWait(...)` — когда надо дождаться завершения;
|
||
- унифицировать с **binding** (`binding.String`, `binding.List`) — через `fyne.Do` не требуется, но проще явно.
|
||
- Подписчик шины ставит snapshot в очередь UI-обновления и вызывает `fyne.Do`.
|
||
|
||
### 12.5. Чтение-модель на UI: снапшоты, не мутабельные указатели
|
||
|
||
- UI получает **копии** записей (Task, history, traces) через абстракцию БД (см. раздел 10).
|
||
- Никаких референсов на разделяемые контейнеры core; используются лёгкие view-копии (Value-типы/DT-коды) — нет гонок bottom-up.
|
||
|
||
### 12.6. Жизненный цикл: Core ≠ UI
|
||
|
||
- Core (бот) живёт независимо от окна. Закрытие окна = **сворачивание** (Core продолжает).
|
||
- Полный выход — только кнопка «Завершить» → `app.Quit()` (Worker.Stop → router.Close → pool.Close → store.Close).
|
||
- `--noui` → core запускается без создания окна.
|
||
|
||
### 12.7. Скоуп реализации (поэтапно)
|
||
|
||
- [x] **Фаза 1**: `internal/ui` — Store-абстракция (копии), окно как `chat.Channel`,
|
||
команды через канал, snapshots из БД. Fyne-реализация — `internal/ui/desktop`
|
||
(build-tag `cgo`, требует компилятор C для GLFW).
|
||
- [x] **Фаза 2**: `internal/events` — Bus/Hub, Core публикует события, UI подписывается
|
||
через `Controller` (статусы, история, live-шаги, логи).
|
||
- [ ] **Фаза 3**: консистентность TG↔UI через общий маршрутизатор/шину (`UserID`, `chat.Router`).
|
||
|
||
Примечание: окно (Фаза 1) собирается только с cgo; на машинах без C-компилятора
|
||
приложение работает headless (UI=nil). Реальное окно полноценно проверяется
|
||
на машине с MinGW-w64/gcc (`go build -ldflags ...`), здесь — только typecheck.
|
||
|
||
### 12.8. Структура UI-кода: компоненты-виджеты (рефакторинг)
|
||
|
||
`internal/ui` (без Fyne) — контракты + Nil-реализации + юнит-тесты. Fyne-код —
|
||
только в `internal/ui/desktop/*`, один файл — одна панель. `desktop/window.go`
|
||
становится чистой компоновкой.
|
||
|
||
Каждый компонент:
|
||
- **интерфейс** в `internal/ui/<panel>.go` (контракт для тестов/headless);
|
||
- **Nil-реализация** в том же файле (headless/тесты);
|
||
- **Fyne-реализация** в `internal/ui/desktop/<panel>.go`.
|
||
|
||
### 12.9. Контракт виджета «Логи» (LogPanel)
|
||
|
||
Панель «Логи» — поток системных логов из `events.LogLine` (уровень + строка).
|
||
|
||
- `Append(level, text)` — добавить запись лога; уровень нормализуется к одному
|
||
из четырёх (`ui.NormalizeLogLevel`: error/warning/info/debug, неизвестные →
|
||
info); при превышении лимита старые записи отбрасываются (буфер ограничен,
|
||
не расти бесконечно).
|
||
- **Фильтр уровней**: над лентой — выпадающий список с чекбоксами
|
||
(error/warning/info/debug). По умолчанию отмечены все уровни (виден полный
|
||
лог); показываются только записи выбранных уровней; изменение набора сразу
|
||
перерисовывает ленту — и по уже загруженным записям, и для вновь
|
||
поступающих. Если ни один уровень не выбран — лента пуста (без ошибок).
|
||
- Контейнер виджета — отдаётся окну для встраивания в таб «Логи» (строка
|
||
фильтра + Scroll с лентой).
|
||
- Обновление содержимого — на потоке Fyne (внутри панели `fyne.Do`), не из
|
||
горутины Hub.
|
||
|
||
### 12.10. Контракт виджета «Список задач» (TaskListPanel)
|
||
|
||
Список задач — левая панель окна: все задачи (`storage.Task`) строками.
|
||
|
||
- `SetTasks(tasks)` — заменить снимок списка и перерисовать виджет. Данные —
|
||
копии из Store (спец 12.5).
|
||
- `OnSelect(fn)` — колбэк клика по строке; окно грузит детали выбранной задачи
|
||
(это `task_detail`, отдельный компонент). Состояние выбора живёт в окне.
|
||
- Выбранная строка подсвечивается (`Select`/`Unselect`), окно управляет ею.
|
||
- Строка = `taskTitle(t)` (pure-функция, тестируется без Fyne).
|
||
- Обновление — на потоке Fyne; вызывающий уже внутри `fyne.Do`, панель сама
|
||
виджет не трогает из горутин Hub.
|
||
|
||
### 12.11. Контракт виджета «Детали задачи» (TaskDetailPanel)
|
||
|
||
Детали выбранной задачи — верх `right`-сплита: заголовок, статус, детали
|
||
(цель + репозитории).
|
||
|
||
- `ShowTask(t)` — рендер из снимка `storage.Task`: заголовок (bold), статус
|
||
(italic), детали = `TaskDetailText(t)`.
|
||
- `ShowEmpty()` — сброс к placeholder («—» / пусто) при недоступной задаче.
|
||
- Строка деталей = pure `TaskDetailText(t)` (цель + репо), тестируется без Fyne.
|
||
- Обновление — на потоке Fyne; вызывающий уже внутри `fyne.Do`.
|
||
- Диалог и «Состояние» — отдельные панели (chat_panel, state_panel), здесь
|
||
не участвуют; окно оркестрирует загрузку всех панелей по выбору задачи.
|
||
|
||
### 12.12. Контракт виджета «Диалог» (ChatPanel)
|
||
|
||
Диалог — транскрипт общения с выбранной задачей + композитор (поле ввода и
|
||
кнопки команд).
|
||
|
||
- Транскрипт:
|
||
- `SetTranscript(text)` — полный рендер истории выбранной задачи;
|
||
- `Append(text)` — добавить строку; при превышении лимита старые строки
|
||
отбрасываются (буфер ограничен);
|
||
- `Clear()` — очистить при недоступной задаче.
|
||
- Композитор: поле ввода + кнопки команд, подключённые к `ui.Commands` через
|
||
`SetCommands(c)` (ввод → `SendText`, кнопки → Start/Approve/Skip/Retry/Cancel).
|
||
- Кнопка «Перезапустить» — полный аналог Telegram-команды `/retry N`: отправляет
|
||
`/retry N` тем же путём, что и ручной ввод (Commands → Router → Core).
|
||
Активна только для вкладки с привязанной задачей; окно сообщает ID задачи
|
||
через `SetBoundTask(taskID)` (при создании вкладки в `addTab` и при привязке
|
||
свободной вкладки в `bindTaskSession`); `0` — кнопка неактивна.
|
||
- Доставка: окно (как chat.Channel) рендерит `Send`/`Ask`/историю через
|
||
`Append`; строка роли = pure `FormatRole(role)` (👤/🤖).
|
||
- Обновление — на потоке Fyne; вызывающий уже внутри `fyne.Do`.
|
||
|
||
### 12.13. Контракт виджета «Состояние» (StatePanel)
|
||
|
||
Панель «Состояние» — агенты + трейсы выбранной задачи: снимок и live-строки.
|
||
|
||
- `SetText(text)` — полный рендер снимка трасс выбранной задачи.
|
||
- `Append(text)` — добавить строку; при превышении лимита старые строки
|
||
отбрасываются (буфер ограничен).
|
||
- Строка снимка = pure `StateText(traces)` (агент: статус, session).
|
||
- Live-строки (чистые хелперы, окно зовёт `Append` с готовой строкой):
|
||
- `TraceLine(agent, status)` — добавлен/обновлён трейс субагента;
|
||
- `ActivityLine(agent, stage)` — смена этапа агента;
|
||
- `TaskStatusText(e)` — изменение статуса задачи (бейдж + ID).
|
||
- Обновление — на потоке Fyne; вызывающий уже внутри `fyne.Do`.
|
||
|
||
---
|
||
|
||
## Открытые пункты (TODO)
|
||
|
||
- [ ] Точно определить set сплит-панелей (2x2 центр) и как добавляются
|
||
- [ ] Обязательные поля формы создания задачи
|
||
- [ ] Подробности виджета списка задач (после первого мильстон)
|
||
- [x] Архитектура обмена UI<->Core (раздел 12 — принципы; детальные контракты событий/интерфейсов — следующая итерация) |