Покой 1,6 МБ, окно 97,3 МБ, открытие 583/564 мс — цели #1.8 подтверждены на Windows 11. В AGENTS.md добавлена папка poc/. Refs: 1.8.1, 1.8.2
165 lines
21 KiB
Markdown
165 lines
21 KiB
Markdown
# 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`) и в конце работы выдаёт блок «Для дорожной карты»: какие пункты отметить, какой статус поставить, текст сообщения или решения.
|