From a1ce4bdb8a3b14f6b47dacd799970e8dbb9dc62d Mon Sep 17 00:00:00 2001 From: BrowenSiz Date: Sun, 8 Nov 2026 17:14:44 +0300 Subject: [PATCH] docs: AI documentation protocol and roadmap context tool MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Протокол работы AI-ассистентов, зоны frontend/backend/shared, статусы, журнал, шаблоны и скрипт сводки дорожной карты. Refs: 1.2.3 Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- AGENTS.md | 153 ++++++++++++++++ docs/README.md | 28 +++ docs/ai/PROTOCOL.md | 150 +++++++++++++++ docs/ai/roadmap.md | 59 ++++++ docs/ai/templates/adr.md | 22 +++ docs/ai/templates/journal-entry.md | 34 ++++ docs/ai/templates/module.md | 22 +++ docs/backend/README.md | 15 ++ docs/frontend/README.md | 25 +++ .../2026-11-08-shared-1.2-ai-docs-protocol.md | 37 ++++ docs/journal/README.md | 8 + docs/status/backend.md | 24 +++ docs/status/frontend.md | 24 +++ docs/status/shared.md | 32 ++++ tools/roadmap-context/roadmap-context.mjs | 171 ++++++++++++++++++ 15 files changed, 804 insertions(+) create mode 100644 AGENTS.md create mode 100644 docs/README.md create mode 100644 docs/ai/PROTOCOL.md create mode 100644 docs/ai/roadmap.md create mode 100644 docs/ai/templates/adr.md create mode 100644 docs/ai/templates/journal-entry.md create mode 100644 docs/ai/templates/module.md create mode 100644 docs/backend/README.md create mode 100644 docs/frontend/README.md create mode 100644 docs/journal/2026-11-08-shared-1.2-ai-docs-protocol.md create mode 100644 docs/journal/README.md create mode 100644 docs/status/backend.md create mode 100644 docs/status/frontend.md create mode 100644 docs/status/shared.md create mode 100644 tools/roadmap-context/roadmap-context.mjs diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..cb0f4f9 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,153 @@ +# 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 | + +## 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..`. Соединения агентов не хранят состояние, которое нельзя потерять (задел под `--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 для разработки +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 + `