Покой 1,6 МБ, окно 97,3 МБ, открытие 583/564 мс — цели #1.8 подтверждены на Windows 11. В AGENTS.md добавлена папка poc/. Refs: 1.8.1, 1.8.2
21 KiB
21 KiB
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. Архитектурные принципы (обязательны)
- Мультиарендность с первого дня. У каждой таблицы организации есть
tenant_id. Изоляция двойная: проверка в коде (организация берётся из контекста запроса) и Row-Level Security в Postgres. Доступ к данным организации — только черезWithTenantTx. Системные таблицы безtenant_idоформляются явно. - Монолит с понятными границами. Код сервера лежит в
internal/server/<область>(access,sites,devices,tickets,remote…). Это организация кода, а не отдельные модули: общая БД и общие транзакции разрешены. Правило: таблицы области меняет только код этой области; другие области вызывают её сервисные функции, а не пишут SQL в чужие таблицы. Слои внутри области: обработчик HTTP → сервис → запросы к БД. - Функции отключаются программно. Каталог функций и лимитов —
internal/server/features. Итоговое значение: аварийное отключение в конфиге → редакция лицензии → настройка организации → значение по умолчанию. Проверка в API, фоновых задачах, приложении (/me/features) и агенте (HelloAck). Технические флаги для незаконченной разработки удаляются после релиза функции. Никакихif saasпо коду. - Безопасность в основе. RMM имеет права администратора на всех устройствах клиента, поэтому взлом платформы означает взлом всех клиентов.
- Агент ↔ сервер: mTLS, ключ создаётся на устройстве, сертификат выдаётся при регистрации, CA сервера закреплён в агенте.
- Каждая команда агенту подписана (Ed25519) и содержит
tenant_id,device_id,nonce,expires_at. Агент отклоняет неподписанные, чужие и просроченные команды. - Политика удалённого доступа подписана и применяется агентом. Локальный запрет на устройстве сервер снять не может.
- 2FA (TOTP) для пользователей приложения, повторная 2FA для подключения без согласия.
- Журнал аудита только дополняется (цепочка хэшей). Каждое действие с устройством и каждая попытка удалённого доступа попадают в журнал.
- Секреты не попадают ни в логи, ни в git, ни в ответы API. Скриншоты обращений — персональные данные: ограниченный срок хранения и доступ по правам.
- Протокол агента и IPC версионируются. Только обратно совместимые изменения,
buf breakingв CI, полеprotocol_version. Сервер поддерживает агентов N-2 версий. - Агент работает автономно. Без связи события и обращения копятся в локальной очереди; переподключение с exponential backoff и jitter. Сервер выдерживает шторм переподключений.
- Маршрутизация команд через NATS subject
agent.<tenant>.<device>. Соединения агентов не хранят состояние, которое нельзя потерять (задел под--only=gateway). - Всё асинхронное идемпотентно. Команды, обращения, задачи и вебхуки имеют
id, повторная доставка безопасна. - Время в UTC, ID в UUIDv7, деньги — целые копейки, никаких float.
- Доступ = право + область.
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) и в конце работы выдаёт блок «Для дорожной карты»: какие пункты отметить, какой статус поставить, текст сообщения или решения.