firefly-ui/docs/agents/kickoff.md

$impeccable делаем Firefly UI: новый интерфейс к моему Firefly III. Это отдельный SvelteKit-клиент поверх его API, узнаваемый Firefly по раскладке, но красивый, быстрый и целиком управляемый с клавиатуры. К утру он должен работать на https://firefly.hhhhh.dev, на тех же адресах, что и сам Firefly. Пользователь один, я: power user, люблю vim-навигацию.

Сначала 15 минут со мной, потом я сплю, дальше ты сам до утра.

Старт, пока я рядом

1. Прочитай код Firefly (ниже, что и где), без скринов и без запуска. Составь для себя карту: страницы, что на каждой, какие эндпоинты API за ней стоят, чего в API нет.
2. impeccable init с интервью, жёстко, минут на 15. Спрашивай про вкус, плотность, что меня бесит в Firefly и что я в нём люблю. Ответы в PRODUCT.md и docs/agents/decisions.md.
3. Один раунд вопросов по «Что нужно от меня» (ниже), до 4 штук, у каждого дефолт. Не отвечу за 10 минут: бери дефолты и пиши их в decisions.md с пометкой «допущение».
4. Дальше всё без меня.

Что это за продукт

Мне нравится сама система Firefly III и его раскладка, к ней я привык. Пользоваться им невозможно: таблицы рендерятся криво, отчёты и способ их получения ужасны, поиск странный, редактор транзакций глючит, с клавиатуры не работает почти ничего. В v6.7 автор выкинул старый интерфейс (v1 на Twig и v2 на Alpine) и оставил только новый v3 (Blade, Alpine, AdminLTE 4). Сам он пишет, что v3 сырой (changelog.md, v6.7.1, Known issues).

Нужно надмножество обычного Firefly. Всё, что он умеет, плюс то, чего ему не хватает. Это не «привет, Claude, сделай финансовое приложение». Человек, привыкший к Firefly, открывает его и сразу узнаёт: то же меню, те же страницы, те же блоки на тех же местах. Только сделано хорошо.

Как работать над каждой страницей:

1. Посмотри, как страница выглядела в v1 и как выглядит в v3: скрин со стенда, шаблон и контроллер.
2. Пойми, что автор, вероятно, хотел этим сказать. Одна строка на страницу в docs/agents/pages.md.
3. Сделай нашу версию. Раскладка и места элементов как в Firefly, чтобы рука находила. Таблицы, формы, навигация и клавиатура сделаны заново и хорошо.
4. Где можно выпендриться, выпендрись: дашборд, страницы счетов, бюджетов, категорий, отчёты, всё со статистикой и графиками. Выпендрёж не должен ломать узнаваемость.
5. Скрин нашей версии рядом со скрином v1 в docs/agents/demos/<страница>/.

Что читать

• Исходники Firefly III: ~/projects/contributions/firefly-iii. Если на машине его нет: git clone https://github.com/firefly-iii/firefly-iii ~/projects/contributions/firefly-iii. Это чужой репо, ничего в нём не меняй и рабочую копию не переключай. Старые версии читай через git show <тег>:<путь> или отдельный git worktree во временном каталоге.
  • v6.6.6: последний релиз со старыми интерфейсами. v1 лежит в resources/views/*.twig (кроме v2/), v2 в resources/views/v2 и resources/assets/v2. Отсюда раскладка, меню, состав страниц, формы.
  • Последний тег (сейчас v6.7.9): v3 в resources/views, resources/assets/v3. Отсюда текущие возможности и новые экраны.
  • routes/web.php: адреса страниц. Наши экраны живут по тем же путям.
  • routes/api.php, app/Api/V1: что умеет API. Типы генерируй из OpenAPI-спеки (https://github.com/firefly-iii/api-docs, yaml), руками их не пиши.
  • changelog.md и issues на GitHub с меткой про layout: что у людей болит в v3.
• Firefly Pico (https://github.com/cioraneanu/firefly-pico): сторонний фронт на Nuxt поверх того же API. Бери только грабли API, которые они уже нашли. Вид оттуда не брать.
• claddcn-svelte (https://git.kotikot.com/lib/claddcn-svelte): тема cladd для shadcn-svelte, уже поставлена в этот репо (src/routes/claddcn.css, #lib/components/ui). README там: утилиты cladd-*, акценты, Surface.
• Деплой: ~/projects/infra/komodo (если нет: git clone git@git.kotikot.com:infra/komodo.git).
  • fleet/personal/personal-main/fireflyiii/: стек Firefly (stack.toml, site.caddy). Firefly на :latest с auto_update, так и остаётся.
  • scripts/new-app-stack.py и docs/architecture.md, раздел «Деплой приложений»: как завести стек приложения из шаблона.
  • fleet/personal/personal-main/lodge/: живой образец такого стека.

Исследуй параллельными субагентами, быстро.

Устройство

• SPA на SvelteKit (adapter-static), раздаётся serve.ts на Bun, как задал шаблон. Своего бэкенда нет, всё через /api/v1 Firefly.
• Авторизация через Firefly. Вход, MFA и выход остаются его страницами. После входа Firefly ставит куку laravel_token (CreateFreshApiToken в bootstrap/app.php), и API принимает её с CSRF-заголовком. Так ходит и сам v3: resources/assets/v3/js/boot/axios.js. Для этого клиент обязан жить на том же домене. На 401 полная перезагрузка на /login, после входа возврат туда, где был.
• Риск, проверить первым: кука выдаётся только на web-ответах Laravel, а наши страницы отдаёт не Laravel. Узнай, сколько она живёт и как её продлевать, пока вкладка открыта. Решение и проверку запиши в decisions.md.
• Пути. Каждый экран живёт по тому же адресу, что в Firefly (/accounts/asset, /transactions/show/12, /budgets). Закладки и ссылки продолжают работать. Всё, чего у нас нет, отдаёт сам Firefly: /api, /oauth, /login, /profile, /two-factor, cron-URL, автоматизации, POST-запросы его форм. Переход из клиента на такую страницу делается полной загрузкой. Нужен переключатель «открыть эту страницу в старом интерфейсе» (клавиша плюс пункт палитры), который работает на любом адресе. Маршрутизация живёт в site.caddy стека fireflyiii. Отказ от нового интерфейса это откат одного файла, опиши его в report.md.
• Firefly обновляется сам, поэтому клиент не должен молча ломаться. Типы из спеки и make smoke: прогон основных запросов против локального fireflyiii/core:latest. Версию API клиент читает из /api/v1/about. Если она уехала вперёд, показывает это одной строкой в подвале.
• В dev Vite проксирует на локальный Firefly всё, что не наше, чтобы вход и куки работали как на проде (vite.config.ts, .env).
• SvelteKit здесь третий: алиас #lib (subpath imports в package.json), а не $lib. components.json уже переведён.

Стенд для отсмотра

Поднимай на этой машине в докере. Имя compose-проекта ffui-*, порты случайные высокие, трогать только своё.

• fireflyiii/core:version-6.6.6 с FIREFLY_III_LAYOUT=v1 (для сравнения можно и v2).
• fireflyiii/core:latest: на нём v3 и на нём же разрабатывается клиент.
• База у каждого своя: sqlite или mariadb, как быстрее заведётся.
• Одни и те же демо-данные в обоих через scripts/seed по API. Это отдельный скрипт, моков во фронте нет. Данные правдоподобные: 6–12 месяцев истории; счета (основные, сберегательные, кредитка, кредит), расходные и доходные; сплиты, переводы, две-три валюты, бюджеты с лимитами, категории, теги, подписки (bills), копилки, группы объектов, повторяющиеся транзакции и пара правил. Снос данных тем же скриптом.
• Эталонные скрины v1 и v3 каждой страницы: docs/agents/reference/<страница>/{v1,v3}.png.

Что должно быть к утру, по приоритету

Объём не режь, делай всё по списку. Порядок нужен только на случай, если время кончится: тогда режь снизу. Первый пункт доведи до конца.

1. Каркас на проде. Узнаваемая раскладка Firefly v1 (боковое меню того же состава и порядка, шапка, хлебные крошки, выбор периода как у Firefly). Вход через Firefly. Палитра команд (⌘K / Ctrl+K) по страницам, счетам, бюджетам, категориям, тегам и действиям. Vim-навигация: j/k по строкам, gg/G, / поиск, g-переходы (g d дашборд, g t транзакции и так далее), ? шпаргалка. Переключатель в старый интерфейс. Маршрутизация путей, как описано выше. Приёмка: на https://firefly.hhhhh.dev после входа открывается новый дашборд. /rules открывает старую страницу Firefly. /api/v1/about с токеном отвечает. Выход и повторный вход возвращают на страницу, где был. Клавишей открывается та же страница в старом интерфейсе.
2. Транзакции. Списки по типам и по счёту. Нормальные таблицы: плотные, выравнивание сумм, валюты, сплиты раскрываются на месте. Множественный выбор с клавиатуры и массовые действия (категория, бюджет, теги, удаление). Поиск на языке запросов Firefly с автодополнением операторов и значений, запрос живёт в URL. Редактор транзакции страницей, без модалки: создание, правка, сплиты, клон, удаление, ссылки между транзакциями, вложения. Автодополнение счетов, категорий, бюджетов, тегов. Сохранение ⌘Enter. Быстрый ввод с любой страницы. Приёмка: на стенде ввести с клавиатуры, без мыши, расход со сплитом на две категории, найти его поиском, поменять категорию массовым действием, удалить.
3. Счета и дашборд. Счета по типам (список, просмотр с графиком баланса и транзакциями за период, создание и правка). Дашборд с тем же составом блоков, что в Firefly, нарисованный заново.
4. Бюджеты (лимиты по периодам, доступный бюджет, траты против лимита), категории, теги, подписки (bills), копилки, группы объектов.
5. Отчёты. Генератор как в Firefly (тип, счета, период), но сразу живая страница: параметры в URL, меняются на месте, графики красивые, данные из insight- и chart-эндпоинтов. Главное место для выпендрёжа.
6. Остальное с API: валюты и курсы, вложения, типы ссылок, настройки (preferences), экспорт, финансовые группы (administrations).
7. Автоматизации (правила, группы правил, повторяющиеся транзакции, вебхуки): списки и просмотр можно, создание и правка уходят полной загрузкой в старый интерфейс Firefly.

Чего не делаем: редактирование автоматизаций (только старый UI); то, чего нет в API (профиль, пароль, MFA, OAuth-клиенты, админка пользователей): это ссылки в старый UI. Если сверку счёта (reconcile) или смену типа транзакции нельзя честно сделать через API, они тоже остаются в старом UI, а в decisions.md записано почему.

Данные

Разработка и проверка идут только на стенде с демо-данными. Прод это мои настоящие финансы. На проде только чтение и один смоук записи: транзакция с тегом ffui-smoke создаётся и удаляется, после смоука на проде не остаётся ничего твоего.

Дизайн

impeccable, режим Operate, claddcn-svelte (уже стоит). PRODUCT.md по итогам интервью.

• Вкус: узнаваемый Firefly. Палитра «примерно как у Firefly, только не уродская»: возьми его синий и цвета сумм (доход, расход, перевод) из v1 и v3, приведи в порядок через акценты claddcn. Не розовый msos. Светлая и тёмная тема, по умолчанию как в системе.
• Плотность как у инструмента для power user: таблицы плотные, числа моноширинные и выровнены, ничего не прячется за наведением.
• Без попапов. Редактирование страницей или на месте. Подтверждение удаления повторным нажатием на месте, а не диалогом.
• Силы вкладывать в: таблицы транзакций и редактор; дашборд и отчёты (графики); палитру и клавиатуру. Остальное спокойное.
• Не надо: таблетки, пульсация, скелетоны, тосты, длинные тире, висячие предлоги, некликабельные кнопки, подписи под блоками, жаргон. Карточки одной высоты. Фильтры, период и вкладки в URL. ПКМ вместо трёх точек. Ответ там, где нажал.
• Тексты интерфейса как в Firefly (язык решим в интервью). Числа и даты по локали из настроек Firefly пользователя.

Как работаем

• Карта страниц и контракт API в docs/agents/pages.md и docs/agents/api-contract.md, потом экраны параллельно субагентами.
• Ядро по приоритетам доводи до приёмки. Дальше пространство твоё: всё, что сделает продукт лучше, делай без вопроса, смелые ставки приветствуются. Условие одно: каждая такая вещь описана в tour.md в блоке «сверх кикоффа» со строкой «зачем».
• Чего в кикоффе нет, не придумывай. Нашёл дыру, назови дыру. Если репо устроен иначе, чем тут написано, следуй репо.
• Чужие процессы и контейнеры на машине не трогай. Только свои PID, своё дерево. Никаких pkill -f, prune, git reset в общих копиях. Субагентам то же.
• Проверка глазами (eyes): headless chromium, 1440×900, 1920×1080 и 390×844. Каждый экран, рядом с эталоном v1. Посмотри сам, исправь одним заходом, сними ещё раз. Скрины в docs/agents/demos.
• make fmt и make check после каждого куска.
• Коммиты через /commit в dev. Деплой: сервер personal-main, домен firefly.hhhhh.dev. Новый стек приложения через scripts/new-app-stack.py в infra/komodo, маршрутизация в fleet/personal/personal-main/fireflyiii/site.caddy, выкатка через kom. После деплоя доказать, что доехало: kom и живой адрес.
• Главный сценарий (пункты 1 и 2) пройди на проде целиком в рамках смоука выше, потом проверь, что твоих данных не осталось.
• Не заканчивай ход, пока работают фоновые агенты или идёт деплой.

Что нужно от меня (спроси в раунде вопросов)

1. Права на деплой: можно ли пушить в infra/komodo (main) новый стек и правку site.caddy у fireflyiii и выкатывать через kom без меня. Дефолт: да, только эти два каталога. Проверь kom-ключом этой машины, что он вообще разрешает. Если отказ, обходить нельзя: всё готовишь, а выкатку оставляешь мне с точной командой в report.md.
2. Смоук на проде: одна транзакция с тегом ffui-smoke, создать и удалить. Дефолт: да.
3. Язык интерфейса. Дефолт: английский, как подписи Firefly v1; форматы по локали пользователя.
4. Что открывается на корне домена: новый интерфейс (старый по переключателю) или старый (новый на /app). Дефолт: новый на тех же путях.

Утром

Два файла в docs/agents и короткий отчёт в чат простым языком:

• report.md: адрес; что работает и чем проверено; что не проверено вживую; что не сделано и почему; где угадывал (особенно про API); как откатить маршрутизацию одним шагом; что бы ещё закрыл. Всё, что обещал в раунде вопросов, тут есть.
• tour.md: по экрану одна строка «что это, как попасть (адрес, клавиша, ПКМ), зачем». Отдельно полная раскладка клавиш. Отдельно блок «сверх кикоффа» в том же формате. Все скрытые аффордансы перечислены: меню по ПКМ, клавиши, тумблеры, переключатель в старый UI.

Когда я вернусь, первым ходом проведи меня по tour.md, потом правки.