Compare commits

...
2 Commits
Author SHA1 Message Date
TMSH 891dd7207c docs: добавлены функции Помощника по фазам и черновик ADR-0005
ci / smoke (pull_request) Successful in 3s
- docs/architecture/helper.md: фаза 1 (обращения), фаза 2 (удалённый
  доступ, уведомления, захват экрана), границы, черновой список IPC
- docs/adr/0005-agent-and-helper.md: статус «Предложено», решение
  по технологии открыто до замера на Astra 1.8 (#1.8.3)

Refs: 1.8.4, 1.8.5
2026-11-11 00:54:05 +03:00
TMSH d107393a90 docs: добавлена запись журнала ветки функций Помощника
Refs: 1.8.4, 1.8.5
2026-11-11 00:52:57 +03:00
5 changed files with 132 additions and 4 deletions

No files matched your search

+37
View File
@@ -0,0 +1,37 @@
# ADR-0005: ПО на устройстве — Агент и Помощник
- **Статус:** Предложено
- **Дата:** 2026-11-11
- **Задача:** #1.8
- **Участники:** Oleg, Максим
- **Зоны:** shared
## Контекст
Пользователю нужен интерфейс на ПК: сообщить о проблеме, видеть статус обращения, подтвердить удалённое подключение. Агент — служба в Session 0 (Windows) / systemd (Linux) и физически не может показывать окна. Значит на устройстве два компонента: служба-агент и «Штиль Помощник» в сессии пользователя. Оставалось выбрать технологию Помощника: критерии — в покое ≤ 40 МБ ОЗУ, с открытым окном ≤ 150 МБ, открытие ≤ 1 с, общий UI-стек с приложением, работа в изолированном контуре.
## Решение
*Черновик до решения #1.8.3: архитектура подтверждена, выбор технологии ждёт замер на Astra 1.8.*
- На устройстве два компонента: **агент** (служба, SYSTEM/root, единственный канал к серверу по mTLS) и **Помощник** (процесс в сессии пользователя, иконка в трее, без прав администратора).
- Помощник общается только с агентом по IPC (named pipe / unix socket, Protobuf, `proto/helper/v1`); агент проверяет подлинность Помощника (путь, подпись бинарника, пользователь сессии).
- Запуск: Windows — агент отслеживает входы и запускает Помощника в сессиях; Linux — XDG autostart, агент контролирует наличие. Пункта «Выход» нет, при падении агент перезапускает.
- Один установщик «агент + Помощник»; на серверах Помощник по умолчанию выключен. Иконка и название переопределяются конфигом (white-label для MSP).
- **Технология (предложение):** Tauri 2 в режиме «только трей»: окна нет при старте, форма создаётся по клику и уничтожается при закрытии. Подтверждено PoC (`poc/helper-tray`, `docs/research/helper-tray-poc.md`): Windows 11, release, медиана из 5 прогонов — покой 2,0 МБ PrivateBytes, открытие 580/555 мс, окно 155,3 МБ PrivateBytes (цель 150 — превышение ~5 МБ признано допустимым, т.к. расход даёт WebView2-движок, общий с приложением).
- Функции Помощника по фазам — `docs/architecture/helper.md`.
## Рассмотренные варианты
| Вариант | Плюсы | Минусы |
|---|---|---|
| **Tauri 2 трей + окно на WebView** | Общий UI-стек и дизайн-система с приложением, один язык для команды, WebView2 уже есть на Windows | Окно ~155 МБ PB > цели 150; на Linux зависит от WebKitGTK 4.1 |
| Трей на Go + окно Tauri по запросу | Покой ещё ниже (~2–3 МБ и так 2 МБ) | Окно всё равно на WebView — выигрыша по памяти с окном нет; второй стек IPC/сборки; выигрыш только в покое, который и так 20× ниже цели |
| Нативный трей + нативные окна (Go/Qt/winfrey) | Минимум памяти | Нет общего UI с приложением, два UI-стека, дороже поддержка — отклонено по трудозатратам |
## Последствия
- Нужны `proto/helper/v1` (черновик методов — `docs/architecture/helper.md`) и каркас `apps/helper/` на следующих шагах.
- Запасной путь при провале цели на Astra/РЕД ОС: трей на Go, окно Tauri по запросу.
- Решение пересматривается, если замер на Astra 1.8 (#1.12.5) покажет окно значительно выше ~160 МБ или открытие > 1 с.
- `poc/` удаляется после принятия ADR.
+56
View File
@@ -0,0 +1,56 @@
# Помощник «Штиль» — функции по фазам
- **Задача:** #1.8.4 · **Статус:** черновик, утверждается решением #1.8.3 → ADR-0005
- Источники: карточка #1.8 (диаграмма), #1.9 (обращения), #1.10 (удалённый доступ)
## Роль и ограничения
Помощник — процесс в сессии пользователя, единственный компонент на устройстве с интерфейсом.
- Прав администратора нет, установки драйверов/служб не требует.
- С сервером напрямую не общается — только с агентом по IPC (named pipe / unix socket, Protobuf).
- Запуск: Windows — агентом при входе пользователя (служба в Session 0 окон не имеет); Linux — XDG autostart, агент контролирует наличие.
- Пункта «Выход» нет; при падении агент перезапускает.
- На серверах не ставится по умолчанию (параметр установки).
- Устанавливается одним инсталлятором с агентом; иконка и название переопределяются конфигом (white-label).
## Фаза 1 — обращения (MVP)
| Функция | Содержание |
|---|---|
| Иконка в трее | Меню: «Сообщить о проблеме», «Мои обращения», «О программе». Без окон при старте; окно создаётся по клику и уничтожается при закрытии |
| Форма обращения | Категории-кнопки: Не печатает · Нет сети/интернета · Медленно работает · Не работает программа · Нужен доступ или ПО · Другое. Описание (обязательно, ≤ 2000), срочность (обычная / срочно — работа стоит), контакт (телефон/кабинет, запоминается) |
| Скриншот | Снимается автоматически, показывается превью, кнопка «Убрать». Организация может отключить политикой |
| Отправка | Помощник → агент по IPC. Агент добавляет автодиагностику и отправляет; без связи копит в своей очереди — у Помощника очереди нет |
| «Мои обращения» | Последние 10: статус и ответы администратора, простая переписка внутри обращения |
| «О программе» | Версия, организация, статус связи с агентом |
## Фаза 2 — удалённый доступ и уведомления
| Функция | Содержание |
|---|---|
| Диалог согласия | Кто подключается и причина. Кнопки: Разрешить / Только просмотр / Отклонить. Нет ответа 30 с — отказ |
| Индикатор сеанса | Красная рамка по краю экрана + панель «К вам подключён {имя} · {время} · Завершить». Пользователь может прервать сеанс в любой момент |
| Захват экрана | По команде агента: служба в Session 0 рабочий стол не видит, снимает только процесс сессии. Передача потока агенту |
| Уведомления | Всплывающие: ответ по обращению, сообщения от администратора, события сеанса удалённого доступа |
## Чего Помощник не делает
- Не хранит данные дольше сессии, не имеет своей БД и очереди.
- Не показывает настроек пользователю (кроме white-label через конфиг агента).
- Не принимает решений по безопасности: показ диалога согласия решает агент по подписанной политике.
- Не работает в Session 0 и без графической сессии.
## Черновой список методов IPC (`proto/helper/v1`)
Для оценки поверхности протокола, детали — в #1.8.5 и позже.
| Метод | Направление | Фаза |
|---|---|---|
| `TicketSubmit` | Помощник → агент | 1 |
| `TicketList` / `TicketReply` | Помощник ↔ агент | 1 |
| `ConsentRequest` / `ConsentResponse` | агент → Помощник → агент | 2 |
| `SessionIndicator` (start/stop) | агент → Помощник | 2 |
| `Notify` | агент → Помощник | 2 |
| `ScreenCapture` (start/stop) | агент → Помощник | 2 |
| `GetState` | Помощник → агент | 1 (статус связи для «О программе») |
@@ -0,0 +1,33 @@
---
date: 2026-11-11
zone: frontend
task: "1.8"
items: ["1.8.4", "1.8.5"]
branch: feat/1.8-helper-functions
pr: —
impact: shared
status: в работе
author: Frontend
---
# [1.8] Функции Помощника по фазам и черновик ADR-0005
## Сделано
- `docs/architecture/helper.md` — список функций Помощника по фазам (#1.8.4): роль и ограничения, фаза 1 (обращения), фаза 2 (удалённый доступ, уведомления, захват экрана), границы, черновой список методов IPC.
- `docs/adr/0005-agent-and-helper.md` — черновик ADR-0005 со статусом «Предложено» (#1.8.5): архитектура «агент + Помощник», варианты технологии с результатами PoC. Решение по технологии открыто — ждёт замер на Astra 1.8 (#1.8.3, В1).
## Решения
- Захват экрана отнесён к Помощнику (фаза 2): агент в Session 0 рабочий стол не видит, снимать экран может только процесс в сессии пользователя — по команде агента.
- Локальная очередь обращений живёт в агенте, не в Помощнике: Помощник без прав, хранить данные дольше сессии не должен.
- Всплывающие уведомления — фаза 2 (по карте); в фазе 1 статусы и ответы видны в «Мои обращения».
## Для другой стороны
- Максиму: посмотреть черновой список методов IPC в конце `docs/architecture/helper.md` — это заготовка под `proto/helper/v1`.
- ADR-0005 в статусе «Предложено» — финальное решение после замера на Astra 1.8 (#1.8.3).
## Проверка
- Документы, кода нет. Сверено с картой: #1.8 (диаграмма, вопросы В2–В5), #1.9 (поля формы, автодиагностика), #1.10 (режимы доступа, диалог согласия, индикатор).
## Осталось
- [ ] Ответы на вопросы В1–В5 и решение в #1.8.3 — после замера Максима на Astra 1.8 (VM #1.12.5).
- [ ] ADR-0005 перевести в «Принято» при записи решения (#1.8.5).
+4 -3
View File
@@ -1,6 +1,6 @@
# Состояние: Frontend
Обновлено: 2026-11-09 · Владелец: Frontend-разработчик
Обновлено: 2026-11-11 · Владелец: Frontend-разработчик
Снимок, а не история. Внутренние правила зоны — `docs/frontend/`.
@@ -11,11 +11,12 @@
## Сделано в текущем шаге
- #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/`): покой 2,0 МБ PB, окно 155,3 МБ PB (цель 150 не дотянута ~5 МБ), открытие ~0,58 с. Замеры — `docs/research/helper-tray-poc.md`.
- #1.8.1–1.8.2 PoC трея Помощника (`poc/helper-tray/`): покой 2,0 МБ PB, окно 155,3 МБ PB (цель 150 не дотянута ~5 МБ), открытие ~0,58 с. Замеры — `docs/research/helper-tray-poc.md`. PR #8 смержен.
- #1.8.4 список функций Помощника по фазам — `docs/architecture/helper.md`; черновик ADR-0005 «Предложено» — `docs/adr/0005-agent-and-helper.md`.
## В работе
<!-- - #ID · ветка · что осталось -->
- #1.8 · `feat/1.8-helper-tray-poc` · PR на проверке; осталось — замер на Astra 1.8 (Максим, #1.12.5) и решение в #1.8.3
- #1.8 · `feat/1.8-helper-functions` · осталось — замер на Astra 1.8 (Максим, #1.12.5) и решение в #1.8.3
- #1.4 · без ветки · обсуждение поддерживаемых ОС (взял в работу)
## Ждём от Backend
+2 -1
View File
@@ -1,6 +1,6 @@
# Состояние: общее (shared)
Обновлено: 2026-11-09 · Шаг 1 «Решения и подготовка» · Версия —
Обновлено: 2026-11-11 · Шаг 1 «Решения и подготовка» · Версия —
Снимок, а не история. Правила — `docs/ai/PROTOCOL.md`, разделы 2 и 6.
@@ -28,6 +28,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 по PrivateBytes покой 2,0 МБ (≤40 ✅), окно 155,3 МБ (цель 150 — не дотянуто ~5 МБ), открытие ~0,58 с ✅. Методика и как повторить на Astra 1.8 — `docs/research/helper-tray-poc.md`; нужен замер Максима для ADR-0005 (#1.8.3)
- 2026-11-11 · frontend → backend · функции Помощника по фазам (#1.8.4) — `docs/architecture/helper.md` с черновым списком методов IPC для `proto/helper/v1`; черновик ADR-0005 «Предложено» — `docs/adr/0005-agent-and-helper.md`
## Запросы между зонами
<!-- Формат: - [ ] YYYY-MM-DD · от зоны → к зоне · что нужно · зачем · #ID -->