Files
shtil/AGENTS.md
T
TMSH 22d1698764
ci / smoke (push) Successful in 3s
[1.8] PoC Помощника: трей и замеры на Windows (#8)
**Задача:** #1.8
**Пункты:** 1.8.1, 1.8.2

## Что сделано
- PoC в poc/helper-tray/: Tauri 2 только с иконкой в трее (окна при старте нет), меню из трёх пунктов, окно создаётся по клику и уничтожается при закрытии.
- Форма «Сообщить о проблеме» по прототипу; «Выход» только в debug-сборке.
- Замер времени открытия — команда first_paint (invoke после двойного rAF); сценарий --measure-scenario + measure.ps1: PrivateBytes и WorkingSetPrivate дерева процессов по отметкам этапов в логе.
- Замеры Windows 11 (release, 5 прогонов, медиана): покой 2,0 МБ PB, окно 155,3 МБ PB (цель 150 — не дотянуто ~5 МБ), после закрытия 5,2 МБ, открытие 580/555 мс. Выводы и методика — docs/research/helper-tray-poc.md.
- AGENTS.md: добавлена временная папка poc/ (удаляется после ADR-0005).

## Как проверить
1. cd poc/helper-tray && pnpm install && pnpm tauri build
2. Запустить src-tauri/target/release/helper-tray.exe — только трей, без окна.
3. powershell -ExecutionPolicy Bypass -File measure.ps1 — 5 прогонов, таблица.
4. На Linux: сборка по docs/research/helper-tray-poc.md, замер через PSS.

## Чек-лист
- [x] Коммиты и название PR по-русски, в каждом коммите есть Refs:
- [x] Ветка свежая: git rebase origin/main, конфликтов нет
- [x] Секретов и персональных данных в коде, логах и документах нет
- [x] Документация обновлена: запись журнала, docs/status/, docs/research/
- [ ] Ссылка на этот PR добавлена в «Ссылки» задачи в дорожной карте
<!-- Прочие пункты шаблона неприменимы: нет запросов к БД, прав, миграций, флагов -->

Reviewed-on: #8
Co-authored-by: BrowenSiz <top.timashevsky@gmail.com>
2026-11-10 21:42:07 +00:00

165 lines
21 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# AGENTS.md — контекст проекта «Штиль» для разработчиков и AI-ассистентов
## 1. Что мы строим
**«Штиль»** — отечественная RMM-платформа (Remote Monitoring & Management) для ИТ-отделов и MSP в РФ/СНГ.
Коммерческий продукт T&B.Soft, закрытый код.
| Компонент | Где работает | Что делает |
|---|---|---|
| **Сервер** `shtil-server` | SaaS (ЦОД в РФ) или сервер заказчика | Принимает агентов, хранит данные, отдаёт REST API |
| **Приложение «Штиль»** (Tauri 2 + Vue 3) | ПК администраторов, техников, офисов филиалов | Основной интерфейс для всех ролей, подключается к SaaS или on-prem серверу |
| **Агент** `shtil-agent` (Go) | Каждое устройство, служба SYSTEM/root, без окон | Связь с сервером, инвентаризация, метрики, выполнение подписанных команд, запуск Помощника |
| **Помощник** «Штиль Помощник» (Tauri 2) | Сессия каждого пользователя ПК, иконка в трее | Обращения сотрудников в ИТ-отдел, статусы и ответы, уведомления; фаза 2 — согласие и индикатор удалённого доступа |
- **Помощник** не имеет прав администратора и не общается с сервером напрямую — только с агентом через IPC (named pipe / unix socket) с проверкой подлинности. На серверах без графической сессии работает только агент.
- **Уровни доступа** — роль назначается на область (организация → филиал → отдел), права наследуются вниз. Офис филиала видит только метрики и данные своего филиала, главный админ видит и может всё. ADR-0008.
- **Обращение** (`ticket`) — сообщение сотрудника через Помощника с автодиагностикой. **Алерт** (`alert`) — автоматическое событие мониторинга. Оба попадают в раздел «Входящие». ADR-0006.
- **Удалённый доступ** — два режима: «с согласием» (запрос пользователю, видимый индикатор сеанса) и «без согласия» (серверы и ПК без людей: отдельное право, повторная 2FA, обязательная причина), плюс смешанный режим. Решение о показе запроса принимает агент по подписанной политике, а не сервер. ADR-0007.
Поставка: **SaaS** и **on-prem** (вплоть до изолированного контура) из **одной кодовой базы**.
## 2. Команда и реальность
- 2 разработчика, работают вместе и постоянно на связи. Отдельных DevOps, QA и дизайнера нет.
- Продуктовый план рассчитан на 16–18 человек, поэтому объём сознательно режется, а технологии выбираются с минимальной операционной нагрузкой.
- Главный риск — растянуть MVP. Всё, что вне текущего шага дорожной карты, идёт в бэклог.
- Задачи, статусы, обсуждения и решения ведутся **в дорожной карте** (`shtil-roadmap.html` с сервера). Отдельного трекера нет. ID задач (`2.11`) и пунктов (`2.11.4`) используются в ветках, коммитах и PR.
- Код — в **Gitea** на своём сервере, CI — Gitea Actions (`act_runner`).
- Чтобы понять, что решила команда, читай сводку из «Настройки → Сводка для AI» или `progress.json`: поля `decisions`, `answers`, `comments`, `notes`, `custom`.
## 3. Стек (зафиксирован, менять только через ADR)
| Слой | Технология |
|---|---|
| Сервер | Go, **монолит**: один бинарник, одна БД, функции отключаются программно |
| HTTP API | REST + OpenAPI 3 (spec-first), роутер `net/http` (Go 1.22+) или `chi` |
| Протокол агента | WebSocket поверх TLS 443 + Protobuf, mTLS-идентификация агента |
| IPC агент ↔ Помощник | Protobuf поверх named pipe (Windows) / unix socket (Linux) |
| Внутренняя шина | NATS (встроенный в бинарник; внешний кластер — при масштабировании SaaS) |
| БД | PostgreSQL 16+ (совместимость с Postgres Pro), `pgx/v5` + `sqlc`, миграции `goose` |
| Метрики | PostgreSQL (партиционирование) за интерфейсом `MetricStore`, ClickHouse позже |
| Файлы | S3-совместимое хранилище (MinIO) |
| Приложение и Помощник | Tauri 2 + Vue 3 + TypeScript (strict) + Vite + Pinia + Vue Router + TanStack Query |
| UI | Общая дизайн-система `packages/ui`: Reka UI (headless) + Tailwind CSS, иконки Lucide |
| Удалённый доступ | WebRTC (Pion) + собственный TURN — фаза 2 |
| Наблюдаемость | `log/slog` (JSON), OpenTelemetry, Prometheus-метрики |
| Dev-окружение | Docker Compose, Taskfile, mise |
Версии инструментов (Go, Node LTS, pnpm, Task, Rust, Tauri) зафиксированы в `.mise.toml` и `rust-toolchain.toml`, объяснение и установка — `docs/environment.md`.
## 4. Архитектурные принципы (обязательны)
1. **Мультиарендность с первого дня.** У каждой таблицы организации есть `tenant_id`. Изоляция двойная: проверка в коде (организация берётся из контекста запроса) и Row-Level Security в Postgres. Доступ к данным организации — только через `WithTenantTx`. Системные таблицы без `tenant_id` оформляются явно.
2. **Монолит с понятными границами.** Код сервера лежит в `internal/server/<область>` (`access`, `sites`, `devices`, `tickets`, `remote`…). Это организация кода, а не отдельные модули: общая БД и общие транзакции разрешены. Правило: таблицы области меняет только код этой области; другие области вызывают её сервисные функции, а не пишут SQL в чужие таблицы. Слои внутри области: обработчик HTTP → сервис → запросы к БД.
3. **Функции отключаются программно.** Каталог функций и лимитов — `internal/server/features`. Итоговое значение: аварийное отключение в конфиге → редакция лицензии → настройка организации → значение по умолчанию. Проверка в API, фоновых задачах, приложении (`/me/features`) и агенте (`HelloAck`). Технические флаги для незаконченной разработки удаляются после релиза функции. Никаких `if saas` по коду.
4. **Безопасность в основе.** RMM имеет права администратора на всех устройствах клиента, поэтому взлом платформы означает взлом всех клиентов.
- Агент ↔ сервер: mTLS, ключ создаётся на устройстве, сертификат выдаётся при регистрации, CA сервера закреплён в агенте.
- Каждая команда агенту подписана (Ed25519) и содержит `tenant_id`, `device_id`, `nonce`, `expires_at`. Агент отклоняет неподписанные, чужие и просроченные команды.
- Политика удалённого доступа подписана и применяется агентом. Локальный запрет на устройстве сервер снять не может.
- 2FA (TOTP) для пользователей приложения, повторная 2FA для подключения без согласия.
- Журнал аудита только дополняется (цепочка хэшей). Каждое действие с устройством и каждая попытка удалённого доступа попадают в журнал.
- Секреты не попадают ни в логи, ни в git, ни в ответы API. Скриншоты обращений — персональные данные: ограниченный срок хранения и доступ по правам.
5. **Протокол агента и IPC версионируются.** Только обратно совместимые изменения, `buf breaking` в CI, поле `protocol_version`. Сервер поддерживает агентов N-2 версий.
6. **Агент работает автономно.** Без связи события и обращения копятся в локальной очереди; переподключение с exponential backoff и jitter. Сервер выдерживает шторм переподключений.
7. **Маршрутизация команд через NATS** subject `agent.<tenant>.<device>`. Соединения агентов не хранят состояние, которое нельзя потерять (задел под `--only=gateway`).
8. **Всё асинхронное идемпотентно.** Команды, обращения, задачи и вебхуки имеют `id`, повторная доставка безопасна.
9. **Время в UTC, ID в UUIDv7**, деньги — целые копейки, никаких float.
10. **Доступ = право + область.** `access.Require(ctx, perm, object)` для действий, `access.ScopesFor(ctx, perm)` + SQL-фильтр по поддеревьям `sites.path` для списков. Приложение только скрывает недоступное, источник истины — сервер.
## 5. Структура репозитория (монорепо)
```
cmd/shtil-server точка входа сервера
cmd/shtil-agent точка входа агента
internal/server/ серверный монолит
app/ сборка зависимостей и запуск
platform/ config, log, db, httpx, bus, obs
access/ features/ audit/ auth/ tenants/ sites/ users/
devices/ tickets/ commands/ remote/ (следующие шаги)
internal/agent/ агент: transport, collectors, executor, ipc, service, platform/{windows,linux}
internal/shared/ общее для сервера и агента
proto/agent/v1, proto/helper/v1 контракты (buf)
api/openapi.yaml контракт REST API
migrations/ SQL-миграции (goose)
apps/console/ приложение «Штиль» (Vue в src/, Tauri в src-tauri/)
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, без зависимостей)
tools/roadmap-context/ сводка дорожной карты для AI (Node, только чтение)
shtil-roadmap.html дорожная карта
```
## 6. Правила для кода
### Go
- Go — последняя стабильная версия. Поддерживаемые ОС — ADR-0001 (Go ≥ 1.21 не работает на Windows 7/8.1/Server 2012 R2).
- `gofmt` и `golangci-lint` без предупреждений. Ошибки оборачиваются `fmt.Errorf("...: %w", err)`, `panic` в бизнес-коде не используется.
- `context.Context` — первый аргумент любой функции с I/O.
- SQL пишется руками и генерируется через `sqlc`. ORM не используется.
- Тесты табличные. Интеграционные — против настоящего Postgres (testcontainers-go). Для каждой новой таблицы организации обязателен тест изоляции.
### Frontend (приложение и Помощник)
- TypeScript strict, `any` запрещён. Типы API генерируются из `api/openapi.yaml`, руками не пишутся.
- Composition API + `<script setup>`. Серверное состояние — TanStack Query, клиентское — Pinia.
- Все строки интерфейса — через `vue-i18n`, даже если пока есть только русский.
- Компоненты — из `packages/ui`. Новый базовый компонент сначала добавляется туда.
- Вызовы Tauri API и плагинов — только через слой `src/platform/`.
- Видимость элементов — через `v-can` / `useFeature`, без ручных проверок ролей.
### Общее
- Термины — по `docs/glossary.md`. Новый термин сначала добавляется в словарь.
- Ветки `feat/<ID>-кратко`, коммиты Conventional Commits с областью (`feat(server): …`) и строкой `Refs: <ID подзадачи>`, PR в Gitea «[ID] Название», squash merge.
- **Коммиты и PR пишутся на русском языке, понятно и чётко.** Тип и область остаются латиницей (их читают инструменты), всё остальное — по-русски:
- заголовок: `тип(область): что сделано` — с маленькой буквы, без точки, до 72 символов, глагол в прошедшем времени (`добавлен`, `исправлена`, `убрано`);
- тело (если нужно): почему и что важно знать, а не пересказ диффа;
- последняя строка: `Refs: <ID пункта>`.
- Хорошо: `feat(server): добавлен WithTenantTx для доступа к данным организации`, `fix(console): исправлен повтор запроса после истечения токена`.
- Плохо: `fix`, `правки`, `update files`, `WIP`, английский текст.
- Заголовок squash-коммита при слиянии PR тоже по-русски, обычно совпадает с названием PR.
- Формат проверяет хук `commit-msg` (lefthook), `--no-verify` не используется. Полные правила git — `docs/contributing.md`, описание PR — по шаблону `.gitea/pull_request_template.md`.
- Изменения `api/openapi.yaml`, `proto/`, `migrations/` — отдельным PR.
- Значимое техническое решение — ADR в `docs/adr/NNNN-название.md` и поле «Решение» в дорожной карте.
- Без лишних комментариев: комментарий объясняет «почему», а не «что».
## 7. Чего НЕ делать (особенно AI-ассистентам)
- Не предлагать микросервисы, Kubernetes, GraphQL, Kafka и прочее «на вырост» без ADR.
- Не добавлять зависимость без проверки лицензии: **AGPL/GPL запрещены** (в том числе код RustDesk и MeshCentral). Разрешены MIT, BSD, Apache-2.0, MPL-2.0.
- Не использовать сервисы и зависимости, которые могут стать недоступны из РФ. Всё работает on-prem без интернета (шрифты и иконки — локально).
- Не писать запросы к данным организации без `tenant_id` и мимо `WithTenantTx`.
- Не выполнять на агенте ничего без проверенной подписи. Не давать серверу обходить решение агента о согласии пользователя.
- Не давать Помощнику прав администратора и прямой связи с сервером.
- Не делать функции вне текущего шага и не делать «не в MVP»: бэкап, MDM, полный ITIL, антивирус, BI, MSP-биллинг, ИИ.
- Не перенумеровывать ID задач в `roadmap/data.js`: новые пункты получают следующий свободный номер. Отметки и обсуждения в `progress.json` привязаны к этим ID.
- Не редактировать `progress.json` на сервере руками — его пишет только `roadmap-server`. Свои пункты команды (`custom`) при раскрытии следующего шага переносятся в `data.js` новыми ID.
## 8. Команды разработки
Появятся в шаге 2.8. Ориентир:
```
task setup # установить инструменты и зависимости
task dev # postgres, nats, minio, mailpit + сервер + приложение
task test # все тесты
task lint # все линтеры
task gen # sqlc + buf + oapi-codegen + openapi-typescript
task migrate # миграции
task seed # демо-организация «Ромашка»
task build # все артефакты
```
## 9. Документирование и контекст (обязательно для AI)
Память проекта живёт в файлах, а не в чате. Полный протокол — **`docs/ai/PROTOCOL.md`**, выполняй его в каждой сессии.
- **Начало сессии:** прочитай `docs/status/shared.md`, `docs/status/<зона>.md`, последние записи `docs/journal/`, сверься с дорожной картой (`node tools/roadmap-context/roadmap-context.mjs [ID]`), коротко доложи, где мы и что предлагаешь. До этого код не пишется.
- **Зоны:** `frontend`, `backend`, `shared`. Читай `shared` + свою зону, пиши в свою зону + `shared`. Всё, что видит или от чего зависит другая сторона, — в `shared`.
- **Перед коммитом:** запись журнала ветки, обновлённый статус зоны, `shared` при влиянии на другую сторону, ADR для значимых решений. PR без документации не готов.
- **Дорожная карта** (https://locshare.ru/roadmap/) — трекер задач. AI только читает её (`docs/ai/roadmap.md`) и в конце работы выдаёт блок «Для дорожной карты»: какие пункты отметить, какой статус поставить, текст сообщения или решения.