From 4abe485e734558c31b129542baeaf5e541905938 Mon Sep 17 00:00:00 2001 From: BrowenSiz Date: Mon, 9 Nov 2026 22:53:43 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=B5=D0=BD=D1=8B=20=D1=80=D0=B5=D0=B7=D1=83=D0=BB=D1=8C=D1=82?= =?UTF-8?q?=D0=B0=D1=82=D1=8B=20=D0=B7=D0=B0=D0=BC=D0=B5=D1=80=D0=BE=D0=B2?= =?UTF-8?q?=20PoC=20=D0=9F=D0=BE=D0=BC=D0=BE=D1=89=D0=BD=D0=B8=D0=BA=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Покой 1,6 МБ, окно 97,3 МБ, открытие 583/564 мс — цели #1.8 подтверждены на Windows 11. В AGENTS.md добавлена папка poc/. Refs: 1.8.1, 1.8.2 --- AGENTS.md | 1 + ...2026-11-09-frontend-1.8-helper-tray-poc.md | 24 ++-- docs/research/helper-tray-poc.md | 127 ++++++++++++++++++ docs/status/frontend.md | 14 +- docs/status/shared.md | 3 +- 5 files changed, 154 insertions(+), 15 deletions(-) create mode 100644 docs/research/helper-tray-poc.md diff --git a/AGENTS.md b/AGENTS.md index 2fcea58..11a297b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -88,6 +88,7 @@ apps/helper/ «Штиль Помощник» packages/ui/ общая дизайн-система packages/api-client/ сгенерированный TS-клиент deploy/dev/ docker-compose для разработки +poc/ временные прототипы для проверки решений (удаляются после ADR) docs/ ai/, status/, journal/, frontend/, backend/, adr/, architecture/, ux/, testing/, research/, glossary.md roadmap/ data.js (содержание), app.js + app.css (интерфейс), progress.json (работа команды) tools/roadmap-server/ сервер дорожной карты (Go, без зависимостей) diff --git a/docs/journal/2026-11-09-frontend-1.8-helper-tray-poc.md b/docs/journal/2026-11-09-frontend-1.8-helper-tray-poc.md index d29fec9..ab3e0c3 100644 --- a/docs/journal/2026-11-09-frontend-1.8-helper-tray-poc.md +++ b/docs/journal/2026-11-09-frontend-1.8-helper-tray-poc.md @@ -6,26 +6,32 @@ items: ["1.8.1", "1.8.2"] branch: feat/1.8-helper-tray-poc pr: — impact: shared -status: в работе +status: на проверке author: Frontend --- # [1.8] PoC Помощника: Tauri только с иконкой в трее ## Сделано -- Ветка создана, каркас и замеры в работе. Код — `poc/helper-tray/` (временная папка прототипов, удаляется после ADR-0005). +- `poc/helper-tray/` — Tauri 2 приложение только с иконкой в трее: `app.windows: []`, трей с меню из трёх пунктов, окна создаются через `WebviewWindowBuilder` и уничтожаются при закрытии, `prevent_exit` от завершения по закрытию последнего окна. Форма «Сообщить о проблеме» по прототипу (категории, описание, «Отправить» без отправки). +- Замер времени открытия — команда `first_paint` по invoke (capability только `core:default` на `win-*`). +- `poc/helper-tray/measure.ps1` + флаг `--measure-scenario`: сценарий 30 с покой → окно → 10 с → закрыть → 10 с → повтор → закрыть; отметки этапов в `helper-tray-poc.measure.log`, скрипт снимает private working set дерева процессов по отметкам. +- Замеры Windows 11 (release, 5 прогонов, медиана): покой **1,6 МБ**, окно **97,3 МБ**, после закрытия **3,6 МБ**, открытие **583/564 мс**. Все цели выполнены. Таблица и выводы — `docs/research/helper-tray-poc.md`. +- `AGENTS.md` раздел 5: добавлена строка про `poc/`. ## Решения -- Замер времени открытия окна — через invoke команды `first_paint` с отдельной capability, не через события. -- Сценарий замера — флаг `--measure-scenario`: приложение само по таймеру открывает и закрывает окна и пишет отметки этапов в лог-файл; `measure.ps1` снимает private working set по отметкам. +- Пункты «Мои обращения» и «О программе» открывают окно-заглушку через ту же фабрику — иначе меню выглядело бы сломанным. +- Команды приложения в Tauri 2.12 не входят в ACL: для `first_paint` отдельного permission нет, минимальный capability — `core:default`. ## Для другой стороны -- Максиму: повторить замер на Astra 1.8, когда будет VM (#1.12.5). Инструкция — `docs/research/helper-tray-poc.md`. +- Максиму: повторить замер на Astra 1.8, когда будет VM (#1.12.5). Инструкция — `docs/research/helper-tray-poc.md` (measure.ps1 Windows-only, для Linux PSS/`smem`). +- Замеры нужны для ADR-0005 (#1.8.3) — решение принимаем вместе, сам по себе PoC технологию не выбирает. ## Проверка -- Пока нет. +- `pnpm tauri build` release — чисто, без предупреждений. `vue-tsc --noEmit` проходит. +- `measure.ps1` 5 прогонов — сценарий доходит до `stage done`, метрики записаны. +- Ручной проклик меню трея не автоматизирован: `open_window` проверена сценарием замера, обработчик меню вызывает ту же функцию. ## Осталось -- [ ] PoC: трей, меню, окно формы, сценарий замера, measure.ps1. -- [ ] Release-замеры на Windows 11 по методике (5 прогонов, медиана). -- [ ] `docs/research/helper-tray-poc.md`, статусы, `AGENTS.md` (папка `poc/`). +- [ ] Замер на Astra 1.8 — Максим, VM #1.12.5. +- [ ] После ADR-0005 папку `poc/` удалить. diff --git a/docs/research/helper-tray-poc.md b/docs/research/helper-tray-poc.md new file mode 100644 index 0000000..6e48bf4 --- /dev/null +++ b/docs/research/helper-tray-poc.md @@ -0,0 +1,127 @@ +# PoC «Штиль Помощник»: Tauri только с иконкой в трее + +Задачи #1.8.1–1.8.2, задел для решения ADR-0005 (выбор технологии Помощника — #1.8.3). +Код — `poc/helper-tray/`. Папка `poc/` временная: после принятия ADR-0005 удаляется. + +## Что проверяем + +Рекомендация карты: Tauri 2 в режиме «только трей» — при старте окно не создаётся, +WebView не запускается; окно создаётся по клику и уничтожается при закрытии. +Цели из дорожной карты: + +| Метрика | Цель | +|---|---| +| ОЗУ в покое (только трей) | ≤ 40 МБ | +| ОЗУ с открытым окном | ≤ 150 МБ | +| Время открытия окна | ≤ 1 с | + +Если цели не достигаются — запасной вариант: трей на Go + окно Tauri по запросу. + +## Как устроен PoC + +- `src-tauri/tauri.conf.json`: `app.windows: []` — окна при старте нет; строгий CSP + (`default-src 'self'; style-src 'self' 'unsafe-inline'`); identifier `ru.tbsoft.shtil.helper.poc`. +- `src-tauri/src/lib.rs`: + - трей (`tray-icon`) с меню «Сообщить о проблеме» / «Мои обращения» / «О программе»; + пункт «Выход» есть только в debug-сборке (`cfg!(debug_assertions)`); + - каждый пункт создаёт окно через `WebviewWindowBuilder` с меткой `win--`; + закрытие окна уничтожает его (не `hide`), повторный клик — новое окно; + - `RunEvent::ExitRequested` → `prevent_exit()`, иначе закрытие последнего окна + завершает приложение, живущее в трее; + - замер времени открытия: `Instant` перед `build()` окна → фронтенд после + `mounted` + `requestAnimationFrame` вызывает команду `first_paint` → разница + в мс пишется в лог. Команда приложения — не событие и не плагин, поэтому + capability содержит только `core:default` на окна `win-*`; + - флаг `--measure-scenario` (только для замера): приложение по таймеру делает + 30 с покоя → открывает окно → 10 с → закрывает → 10 с → открывает повторно → + 10 с → закрывает и завершается. Отметки этапов пишутся в + `helper-tray-poc.measure.log` рядом с exe за ~1,5 с до действия, чтобы + скрипт успел снять ОЗУ. +- `src/App.vue`: форма по прототипу — кнопки-категории, поле описания, кнопка + «Отправить» (отправки нет). «Мои обращения» и «О программе» — заглушки. +- `measure.ps1`: запускает exe с `--measure-scenario`, читает отметки из лога, + снимает **private working set** (`WorkingSetPrivate`, + `Win32_PerfFormattedData_PerfProc_Process`) по дереву процессов — приложение + + все дочерние `msedgewebview2.exe` (по цепочке родителей и по user-data-dir + в командной строке). 5 прогонов, медиана и разброс. + +## Сборка и запуск + +Версии инструментов — `docs/environment.md`. + +```bash +cd poc/helper-tray +pnpm install +pnpm tauri build # release-сборка: exe и установщики в src-tauri/target/release/ +# без установщиков быстрее: pnpm tauri build --no-bundle +``` + +Запуск: `src-tauri/target/release/helper-tray.exe` — появляется только иконка +в трее, окна нет. В release-режиме выхода из меню нет: завершение — через +диспетчер задач или `taskkill /IM helper-tray.exe /F`. + +Разработка: `pnpm tauri dev` (в debug-сборке есть пункт «Выход (debug)»). + +### Linux (Astra 1.8 / Debian 12) + +Зависимости из `docs/environment.md` (включая `libayatana-appindicator3-dev`). +Дальше те же `pnpm install` и `pnpm tauri build`. Примечания: +- иконка в трее требует работающего AppIndicator/StatusNotifier (в Astra — + через расширение трея, если трей пустой — это ограничение среды, не PoC); +- `measure.ps1` — только Windows. Для Linux замер вручную: запуск с + `--measure-scenario`, в моменты отметок лога снять PSS дерева процессов + (`smem -P ` или сумма `Private_*` из `/proc//smaps_rollup` + по дереву `pstree -p `). Строку для результатов см. в таблице. + +## Методика замера (как в задании) + +- Только release-сборка. Каждый замер — 5 прогонов сценария, в отчёт — медиана + и разброс (min–max). +- ОЗУ в покое — через 30 с после старта, до первого окна. +- ОЗУ с открытым окном — через 10 с после открытия. +- ОЗУ после закрытия окна — через 10 с (проверка освобождения). +- Время открытия — холодное (первое окно) и тёплое (повторное), из лога. +- ОЗУ — private working set всего дерева процессов (обычный working set + завышает цифру на общую память WebView2). + +## Результаты + +ОС: Windows 11 · машина Frontend-разработчика · дата: 2026-11-09 · сборка release. + +| Метрика | Цель | Медиана (5 прогонов) | Разброс | Итог | +|---|---|---|---|---| +| ОЗУ в покое | ≤ 40 МБ | 1,6 МБ | 1,6 – 1,6 | ✅ | +| ОЗУ с открытым окном | ≤ 150 МБ | 97,3 МБ | 96,8 – 97,6 | ✅ | +| ОЗУ после закрытия | освобождение | 3,6 МБ | 3,5 – 29,0 | ✅ | +| Открытие окна, холодное | ≤ 1 с | 583 мс | 577 – 702 | ✅ | +| Открытие окна, тёплое | ≤ 1 с | 564 мс | 524 – 665 | ✅ | +| ОЗУ повторно открытого окна | — | 97,8 МБ | 97,6 – 122,7 | — | + +| ОС | Покой | Окно | После закрытия | Открытие хол./тёпл. | Дата | +|---|---|---|---|---|---| +| Windows 11 | 1,6 МБ | 97,3 МБ | 3,6 МБ | 583 / 564 мс | 2026-11-09 | +| Astra 1.8 | — ждём VM #1.12.5 — | | | | | + +## Выводы + +- Все три цели на Windows 11 выполнены с большим запасом: покой **1,6 МБ** + (цель ≤ 40), окно **~97 МБ** (цель ≤ 150), открытие **~0,58 с** (цель ≤ 1 с). +- «Только трей» реально не запускает WebView2 до первого окна: в покое живёт + только Rust-процесс с иконкой (1,6 МБ private working set). +- `destroy()` при закрытии полностью освобождает память — через 10 с остаётся + ~3,6 МБ самого процесса. В одном прогоне замер поймал 29 МБ — процессы + WebView2 завершаются не мгновенно; медиана подтверждает освобождение. +- Холодное и тёплое открытие почти не различаются (~0,6 с): WebView2 runtime + стартует быстро даже первый раз. +- Для ADR-0005: на Windows 11 вариант «Tauri только трей» удовлетворяет целям. + Решающий фактор — повторение замера на Astra 1.8 (WebKitGTK может дать + другие цифры и потребует AppIndicator): Максим, после появления VM #1.12.5. +- Что переносить в Помощник при выборе Tauri: паттерн `app.windows: []` + + `prevent_exit`, фабрика окон с `destroy`, замер `first_paint`, минимальные + capabilities и строгий CSP, меню трея без «Выход». + +## Что PoC не делает (вне задания) + +Нет IPC с агентом, отправки обращений, уведомлений, i18n, дизайн-системы, +автозапуска, установщика-поставки. Решение по технологии Помощника принимается +в #1.8.3 совместно с Backend — по этим замерам. diff --git a/docs/status/frontend.md b/docs/status/frontend.md index 510d5fb..23e1cd4 100644 --- a/docs/status/frontend.md +++ b/docs/status/frontend.md @@ -1,26 +1,30 @@ # Состояние: Frontend -Обновлено: 2026-11-08 · Владелец: Frontend-разработчик +Обновлено: 2026-11-09 · Владелец: Frontend-разработчик Снимок, а не история. Внутренние правила зоны — `docs/frontend/`. ## Сейчас - Кода продукта нет. Окружение готово, Tauri 2 собирается на Windows. +- PoC Помощника собран и замерен: цели подтверждены на Windows 11. ## Сделано в текущем шаге - #1.2 правила git, шаблон PR, хуки, личные заметки `docs/private/`. - #1.3 версии инструментов; hello world Tauri и Go на Windows (#1.3.9, часть Frontend/Windows). +- #1.8.1–1.8.2 PoC трея Помощника (`poc/helper-tray/`): покой 1,6 МБ, окно 97 МБ, открытие ~0,58 с — цели выполнены. Замеры — `docs/research/helper-tray-poc.md`. ## В работе -- #1.3 · `feat/1.3-hello-world` · осталось: Linux-сборка (нужна машина #1.3.7), проверка у Максима +- #1.8 · `feat/1.8-helper-tray-poc` · PR на проверке; осталось — замер на Astra 1.8 (Максим, #1.12.5) и решение в #1.8.3 +- #1.4 · без ветки · обсуждение поддерживаемых ОС (взял в работу) ## Ждём от Backend -- Окружение и проверка #1.3.9 у Максима. +- Linux-сборка hello world (#1.3.9) и замер PoC на Astra 1.8 (#1.8.1–1.8.2), когда будет VM #1.12.5. ## Ближайшее -- PoC Помощника: Tauri только с иконкой в трее, замеры ОЗУ и времени открытия окна (#1.8.1–1.8.2). +- #1.8.3–1.8.5 решение по Помощнику и ADR-0005 (вместе с Максимом). - Информационная архитектура и макеты (#1.11). ## Известные проблемы и долги -- Предварительно WebView2 в hello world занимает ~337 МБ рабочего набора — проверить точным замером в #1.8 (цель ≤ 150 МБ с окном). +- Замер рабочего набора hello world (~337 МБ) оказался завышенным на общую память — честный private working set с окном в PoC ~97 МБ, цель ≤150 подтверждена. +- `poc/` временная, удаляется после ADR-0005. diff --git a/docs/status/shared.md b/docs/status/shared.md index 541156d..9fed022 100644 --- a/docs/status/shared.md +++ b/docs/status/shared.md @@ -1,6 +1,6 @@ # Состояние: общее (shared) -Обновлено: 2026-11-08 · Шаг 1 «Решения и подготовка» · Версия — +Обновлено: 2026-11-09 · Шаг 1 «Решения и подготовка» · Версия — Снимок, а не история. Правила — `docs/ai/PROTOCOL.md`, разделы 2 и 6. @@ -27,6 +27,7 @@ - 2026-11-08 · frontend → backend · правила git (`docs/contributing.md`), шаблон PR, хуки lefthook: после `git pull` выполнить `mise install && lefthook install` - 2026-11-08 · frontend → backend · версии инструментов зафиксированы: `git pull`, `mise trust && mise install` по `docs/environment.md` +- 2026-11-09 · frontend → backend · PoC трея Помощника (#1.8.1–1.8.2): на Windows 11 цели подтверждены (покой 1,6 МБ, окно 97 МБ, открытие ~0,58 с). Методика и как повторить на Astra 1.8 — `docs/research/helper-tray-poc.md`; нужен замер Максима для ADR-0005 (#1.8.3) ## Запросы между зонами