docs: AI documentation protocol and roadmap context tool
Протокол работы 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>
This commit is contained in:
1 parent
699e6bbd57
commit
a1ce4bdb8a
15 files changed
+804
No files matched your search
@@ -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.<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 для разработки
|
||||
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.
|
||||
- Изменения `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`) и в конце работы выдаёт блок «Для дорожной карты»: какие пункты отметить, какой статус поставить, текст сообщения или решения.
|
||||
@@ -0,0 +1,28 @@
|
||||
# Документация «Штиль»
|
||||
|
||||
Начните с `AGENTS.md` (правила проекта), затем `docs/ai/PROTOCOL.md` (как работать с контекстом и документировать).
|
||||
|
||||
## Порядок чтения для новой сессии
|
||||
1. `AGENTS.md`
|
||||
2. `docs/ai/PROTOCOL.md`
|
||||
3. `docs/status/shared.md` + `docs/status/<ваша зона>.md`
|
||||
4. Последние записи `docs/journal/`
|
||||
5. Дорожная карта: `node tools/roadmap-context/roadmap-context.mjs`
|
||||
|
||||
## Карта
|
||||
|
||||
| Папка / файл | Зона | Что внутри |
|
||||
|---|---|---|
|
||||
| `ai/` | shared | Протокол AI, сверка с дорожной картой, шаблоны |
|
||||
| `status/` | shared + зоны | Снимок текущего состояния: общее, Frontend, Backend |
|
||||
| `journal/` | все | История работы: одна запись на ветку/PR |
|
||||
| `adr/` | shared | Архитектурные решения `NNNN-название.md` |
|
||||
| `architecture/` | shared | ERD, правила БД, протокол агента, IPC Помощника |
|
||||
| `ux/` | shared | Информационная архитектура, макеты, сценарии |
|
||||
| `testing/` | shared | Тестовый стенд, сценарии доступа |
|
||||
| `research/` | shared | Интервью, исследования рынка |
|
||||
| `frontend/` | frontend | Внутренние правила Frontend: дизайн-система, компоненты, соглашения |
|
||||
| `backend/` | backend | Внутренние правила Backend: области сервера, агент, эксплуатация |
|
||||
| `glossary.md` | shared | Словарь терминов (#2.1) |
|
||||
| `features.md` | shared | Каталог функций и лимитов (#2.3) |
|
||||
| `contributing.md` | shared | Ветки, коммиты, PR, версии (#1.2.9) |
|
||||
@@ -0,0 +1,150 @@
|
||||
# Протокол AI-ассистента: контекст и документирование
|
||||
|
||||
Обязателен для любого AI-ассистента в репозитории «Штиль» (Devin, Windsurf, Cursor, Claude Code и др.) у обоих разработчиков.
|
||||
Читается сразу после `AGENTS.md`. Цель: ассистент в любой новой сессии за 1–2 минуты понимает, где проект, что сделано на Frontend и Backend, что делать дальше, и **сам поддерживает эту память в актуальном виде**.
|
||||
|
||||
---
|
||||
|
||||
## 1. Где что хранится (источники истины)
|
||||
|
||||
| Что | Где | Кто пишет |
|
||||
|---|---|---|
|
||||
| План, задачи, статусы, исполнители, обсуждения, решения команды | Дорожная карта (`docs/ai/roadmap.md`) | Люди в интерфейсе карты. **AI только читает** |
|
||||
| Правила проекта, стек, запреты | `AGENTS.md` | Люди; AI предлагает правки |
|
||||
| Как работает AI с памятью проекта | `docs/ai/` (этот файл) | Люди; AI предлагает правки |
|
||||
| Текущее состояние «здесь и сейчас» | `docs/status/{shared,frontend,backend}.md` | AI в каждом PR |
|
||||
| История: что сделано, почему, что осталось | `docs/journal/` — одна запись на ветку/PR | AI в каждом PR |
|
||||
| Значимые решения | `docs/adr/NNNN-*.md` | AI готовит, люди принимают |
|
||||
| Как устроена каждая часть системы | `docs/architecture/`, `docs/frontend/`, `docs/backend/`, `docs/ux/`, `docs/testing/` | AI при появлении нового модуля/паттерна |
|
||||
| Контракты | `api/openapi.yaml`, `proto/`, `migrations/` | Отдельный PR, обсуждение с обоими |
|
||||
| Термины | `docs/glossary.md` | Сначала словарь, потом код |
|
||||
|
||||
**Приоритет при расхождении:** код и контракты (как сделано) → ADR (как решили) → дорожная карта (статусы и решения команды) → `docs/status` → `docs/journal` → память чата. Нашёл расхождение — сообщи пользователю и предложи исправление, не выбирай молча.
|
||||
|
||||
**Не дублировать.** Дорожная карта отвечает на «что и в каком статусе», `docs/` — на «как сделано и почему». В `docs/` ссылайся на задачи по ID (`#2.11`, `#2.11.4`), не переписывай их текст.
|
||||
|
||||
---
|
||||
|
||||
## 2. Зоны ответственности
|
||||
|
||||
| Зона | Владелец | Пути | Что документируется |
|
||||
|---|---|---|---|
|
||||
| `frontend` | Frontend-разработчик | `apps/console/src/`, `apps/helper/src/`, `apps/*/src-tauri/`, `packages/ui/`, `docs/frontend/` | Дизайн-система, токены, компоненты, вёрстка, состояние, роутинг, i18n, слой `src/platform/`, Tauri-оболочка |
|
||||
| `backend` | Backend-разработчик | `cmd/`, `internal/`, `deploy/`, `tools/` (кроме `roadmap-context`), `docs/backend/` | Сервер, агент, БД, NATS, безопасность, сборка, окружение |
|
||||
| `shared` | Оба | `api/`, `proto/`, `migrations/`, `packages/api-client/`, `docs/adr/`, `docs/architecture/`, `docs/ux/`, `docs/glossary.md`, `docs/features.md`, `docs/status/shared.md`, `AGENTS.md`, `docs/ai/`, `tools/roadmap-context/`, `roadmap/`, `Taskfile.yml`, `.gitea/`, `.mise.toml` | Всё, что видит или от чего зависит другая сторона |
|
||||
|
||||
Правила зон:
|
||||
- **Читаешь:** `shared` + свою зону. Чужую зону — только если задача её касается (например, Frontend подключает эндпоинт и смотрит `docs/backend/` по нему).
|
||||
- **Пишешь:** свою зону + `shared`. Документы чужой зоны не редактируешь. Нашёл в них ошибку или нужна правка у другой стороны — запись в «Запросы между зонами» в `docs/status/shared.md`.
|
||||
- Чисто внутренние вещи зоны (дизайн-правила, вёрстка, внутренняя организация сервиса) остаются в документах зоны и **не попадают** в `shared`. Ассистент другой стороны их не читает и не тратит на них контекст.
|
||||
- **Как определить зону сессии:** 1) пользователь назвал её («зона: frontend»); 2) она задана в личных правилах разработчика (раздел 8); 3) по путям файлов задачи. Задача затрагивает обе зоны — работай как `shared` и спроси, кто делает вторую часть.
|
||||
|
||||
### Что обязательно идёт в `shared` (impact: shared)
|
||||
|
||||
- изменения `api/openapi.yaml`, `proto/`, `migrations/`, сгенерированного клиента;
|
||||
- права, роли, области, каталог функций и лимитов, коды ошибок и формат ответов;
|
||||
- новые или изменённые переменные окружения, конфиг, порты, команды `task`, CI, зависимости уровня репозитория;
|
||||
- поведение, которое видит другая сторона (новый эндпоинт готов, поле стало обязательным, формат даты изменился, эндпоинт нужен фронту);
|
||||
- безопасность: аутентификация, токены, CSP и capabilities Tauri, хранение секретов, аудит;
|
||||
- новые термины, ADR, решения из чата, отклонения от плана дорожной карты, блокеры для другой стороны.
|
||||
|
||||
---
|
||||
|
||||
## 3. Начало сессии
|
||||
|
||||
Выполни по порядку и **не начинай писать код, пока не сделал шаги 1–5**:
|
||||
|
||||
1. `AGENTS.md` (обычно подгружается сам) и этот файл.
|
||||
2. `docs/status/shared.md` и `docs/status/<зона>.md`.
|
||||
3. Журнал: последние 5 записей своей зоны и все записи `impact: shared` новее твоей последней записи (`docs/journal/`, имена файлов сортируются по дате).
|
||||
4. Дорожная карта: `node tools/roadmap-context/roadmap-context.mjs` (текущий шаг) и `... <ID задачи>` для задачи сессии. Подробности и запасные варианты — `docs/ai/roadmap.md`.
|
||||
5. Git: текущая ветка, `git status`, `git log --oneline -15 origin/main`. Есть ли смерженные PR другой стороны после последнего обновления статуса.
|
||||
6. Отчитайся пользователю (не больше 10 строк):
|
||||
- где мы: фаза, шаг, задача и её статус в карте;
|
||||
- что изменилось с прошлой сессии, в том числе у другой стороны;
|
||||
- открытые вопросы, блокеры, запросы к этой зоне;
|
||||
- расхождения между картой, документами и кодом;
|
||||
- что предлагаешь сделать сейчас.
|
||||
|
||||
Задача вне текущего шага, без ID или в статусе «Выполнено» — предупреди и предложи: взять задачу текущего шага, добавить «свой пункт» в карту или записать в бэклог.
|
||||
|
||||
---
|
||||
|
||||
## 4. Во время работы
|
||||
|
||||
- Работа идёт в ветке `feat/<ID>-кратко` (`AGENTS.md`, раздел 6). Запись журнала этой ветки создаётся в первом же коммите и дополняется по ходу.
|
||||
- **Решение принято в чате** — сразу в раздел «Решения» записи журнала. Значимое (влияет на архитектуру, контракт, безопасность, другую сторону, его дорого отменить) — черновик ADR по шаблону и текст для поля «Решение» в карте.
|
||||
- **Отклонился от плана** (пункт сделан иначе, не нужен, нужен новый) — раздел «Отклонения от плана» и предложение для карты.
|
||||
- **Нашёл что-то вне шага** — раздел «Идеи и бэклог», не реализуй.
|
||||
- **Нужно что-то от другой стороны** — запрос в `docs/status/shared.md` и текст сообщения типа «Вопрос» или «Блокер» для карты.
|
||||
- **Контракт меняется** — отдельный PR (только контракт + запись `shared`), потом реализация.
|
||||
- Не держи важное только в чате: если завтра сессия начнётся с нуля, всё нужное должно быть в файлах.
|
||||
|
||||
---
|
||||
|
||||
## 5. Перед коммитом и в конце сессии
|
||||
|
||||
Документация — часть PR. PR без обновлённой документации не готов к ревью.
|
||||
|
||||
Чек-лист:
|
||||
- [ ] Запись журнала ветки обновлена: сделано, решения, проверка, что осталось (`docs/ai/templates/journal-entry.md`).
|
||||
- [ ] `docs/status/<зона>.md` отражает текущее состояние: заменить устаревшее, а не дописать снизу.
|
||||
- [ ] Если есть impact `shared` — обновлён `docs/status/shared.md` (раздел «Готово для другой стороны» или «Запросы между зонами»).
|
||||
- [ ] Новый модуль, экран, компонент, паттерн, эндпоинт — описание в документах зоны (`docs/ai/templates/module.md`).
|
||||
- [ ] Значимое решение — `docs/adr/NNNN-*.md` (`docs/ai/templates/adr.md`), статус «Предложено» до одобрения людьми.
|
||||
- [ ] Новый термин — `docs/glossary.md`. Новая команда или правило — предложение правки `AGENTS.md`.
|
||||
- [ ] Секретов, паролей, токенов, внутренних адресов стенда и персональных данных в документах нет.
|
||||
- [ ] Блок **«Для дорожной карты»** выведен пользователю в чат:
|
||||
```
|
||||
Задача: #2.11 → статус: На проверке
|
||||
Отметить пункты: 2.11.4, 2.11.6
|
||||
Сообщение (Комментарий/Вопрос/Блокер/Решение): <текст>
|
||||
Поле «Решение»: <текст, если есть>
|
||||
Ссылка: PR <URL> (после открытия)
|
||||
```
|
||||
Человек переносит это в карту сам. Описание PR можно взять кнопкой «Для PR» в задаче карты.
|
||||
|
||||
Документы коммитятся в той же ветке, что и код (`docs(<область>): …` или вместе с кодом), с той же строкой `Refs: <ID>`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Форматы и размеры
|
||||
|
||||
- Язык — русский, термины по `docs/glossary.md`, идентификаторы кода — как в коде.
|
||||
- Пиши факты: что сделано, где лежит (относительный путь), как проверить. Без воды, пересказа кода и мотивационных фраз.
|
||||
- `docs/status/*.md` — до 120 строк. Это снимок, не история: выполненное старше одного шага удаляется (оно есть в журнале).
|
||||
- Запись журнала — до 60 строк. Одна запись на ветку/PR, не на каждый чат.
|
||||
- Имя записи журнала: `docs/journal/YYYY-MM-DD-<зона>-<ID>-<кратко>.md`, дата — день создания ветки. Пример: `2026-11-20-frontend-2.13-design-tokens.md`.
|
||||
- Описание модуля — в документах зоны или `docs/architecture/`, если его используют обе стороны.
|
||||
- Ссылки на задачи — `#ID`, на код — относительный путь, на ADR — `ADR-0008`.
|
||||
- Дата — `YYYY-MM-DD`, время, если нужно, — UTC.
|
||||
|
||||
---
|
||||
|
||||
## 7. Конфликты и совместная работа
|
||||
|
||||
- Свою зону и свой журнал правит только её владелец, поэтому конфликты возможны только в `shared`-файлах. При конфликте в `docs/status/shared.md` сохраняются записи обеих сторон.
|
||||
- Пункт в «Запросах между зонами» закрывает тот, кто выполнил: удаляет строку и добавляет запись в «Готово для другой стороны».
|
||||
- В конце шага (ритм «Конец шага» в карте) один из разработчиков просит ассистента: «подведи итог шага» → ассистент сверяет карту, журнал и код, чистит `docs/status/*`, выдаёт список несовпадений и текст для ретро.
|
||||
|
||||
---
|
||||
|
||||
## 8. Личные правила разработчика (не в git)
|
||||
|
||||
Каждый добавляет в правила своего AI-инструмента (глобальные правила Windsurf/Devin, `~/.config/devin/`, User Rules в Cursor и т.п.) короткий блок. Пример для Frontend:
|
||||
|
||||
```
|
||||
Проект «Штиль». Я — Frontend-разработчик, моя зона: frontend.
|
||||
В начале каждой сессии выполняй docs/ai/PROTOCOL.md (раздел 3), в конце — раздел 5.
|
||||
Backend-документацию читай только когда задача касается API/контрактов.
|
||||
```
|
||||
|
||||
Для Backend — то же с зоной `backend`.
|
||||
|
||||
Стартовая фраза новой сессии, если правила не настроены:
|
||||
|
||||
```
|
||||
Зона: frontend. Задача: #2.13. Выполни начало сессии по docs/ai/PROTOCOL.md.
|
||||
```
|
||||
|
||||
Конец сессии: `Заверши сессию по docs/ai/PROTOCOL.md (раздел 5).`
|
||||
@@ -0,0 +1,59 @@
|
||||
# Сверка с дорожной картой
|
||||
|
||||
Дорожная карта — единственный трекер задач команды: https://locshare.ru/roadmap/
|
||||
AI-ассистент **только читает** её. Изменения в карту вносят люди через интерфейс; ассистент готовит для них текст (блок «Для дорожной карты», `PROTOCOL.md`, раздел 5).
|
||||
|
||||
## Основной способ
|
||||
|
||||
```
|
||||
node tools/roadmap-context/roadmap-context.mjs # текущий шаг, статусы задач, последние изменения
|
||||
node tools/roadmap-context/roadmap-context.mjs 2 # обзор шага 2
|
||||
node tools/roadmap-context/roadmap-context.mjs 2.11 # задача полностью: описание, вопросы и ответы, решение, пункты, обсуждение, ссылки
|
||||
node tools/roadmap-context/roadmap-context.mjs --all # всё подробно (много текста, только при подведении итогов шага)
|
||||
```
|
||||
|
||||
План (`data.js`) берётся из `roadmap/data.js` в репозитории, если файл есть, иначе с сервера. Если локальная копия отличается от сервера, скрипт выводит предупреждение — сообщи об этом пользователю. Прогресс всегда берётся с сервера.
|
||||
|
||||
Переменные окружения (задаются локально, в git не попадают):
|
||||
|
||||
| Переменная | По умолчанию | Назначение |
|
||||
|---|---|---|
|
||||
| `ROADMAP_URL` | `https://locshare.ru/roadmap` | Адрес roadmap-server |
|
||||
| `ROADMAP_AUTH` | — | `логин:пароль` для Basic Auth, когда на сервере включён пароль |
|
||||
| `ROADMAP_DATA` | `roadmap/data.js` | Путь к локальному плану |
|
||||
|
||||
## Что проверять
|
||||
|
||||
В начале сессии:
|
||||
- текущий шаг (`meta.current`) и есть ли задача сессии в этом шаге;
|
||||
- статус задачи и исполнители: не делает ли её уже другой человек;
|
||||
- ответы на вопросы `В1…Вn` и поле «Решение» — это решения команды, они обязательны к исполнению;
|
||||
- незакрытые сообщения «Блокер» и «Вопрос» по задаче;
|
||||
- «свои пункты» команды — работа, которой нет в плане, но она согласована.
|
||||
|
||||
Расхождения, о которых нужно сказать пользователю:
|
||||
- в коде/журнале пункт сделан, а в карте не отмечен (или наоборот);
|
||||
- решение в карте противоречит ADR или коду;
|
||||
- задача «В работе» у другого человека, а мы её трогаем;
|
||||
- работа идёт по задаче вне текущего шага.
|
||||
|
||||
## Как устроены данные (для разбора вручную)
|
||||
|
||||
| Запрос | Что возвращает |
|
||||
|---|---|
|
||||
| `GET {ROADMAP_URL}/api/health` | `{"revision": N}` — номер ревизии, растёт при каждом изменении |
|
||||
| `GET {ROADMAP_URL}/api/progress` | JSON `shtil-roadmap-progress/2` — работа команды |
|
||||
| `GET {ROADMAP_URL}/roadmap/data.js` | Содержание плана: `window.SHTIL_ROADMAP = { meta, areas, types, phases[].steps[].tasks[] }` |
|
||||
|
||||
Разделы `progress`: `members` (id → имя, роль), `tasks` (статус `todo/doing/review/done/blocked`, `assignees`, `priority`, `due`), `items` (ID пункта → `done`), `decisions` (статус `open/discuss/accepted/postponed`, `text`), `answers` (ключ `<задача>~<номер вопроса>`), `comments` (`task`, `kind`: `comment/question/proposal/blocker/decision`, `resolved`, `deleted`), `notes`, `custom` (свои пункты), `links`.
|
||||
|
||||
**Запрещено:** `POST /api/ops` и любые другие запросы на запись, правка `progress.json`, перенумерация ID в `data.js`.
|
||||
|
||||
## Если сервер недоступен
|
||||
|
||||
1. Попросить пользователя: «Настройки → Сводка для AI» → скопировать и вставить в чат (или скачать `.md`).
|
||||
2. Работать по `roadmap/data.js` и `docs/status/*`, явно предупредив, что статусы могут быть устаревшими.
|
||||
|
||||
## Раскрытие следующего шага
|
||||
|
||||
В конце шага пользователь передаёт ассистенту «Сводку для AI» и комментарий. Ассистент обновляет `roadmap/data.js` по правилам из шапки файла: новые пункты получают следующий свободный номер, «свои пункты» из `custom` переносятся в план новыми ID, `meta.current` и `meta.changelog` обновляются. Это отдельный PR `docs(roadmap): …`.
|
||||
@@ -0,0 +1,22 @@
|
||||
# ADR-NNNN: Название решения
|
||||
|
||||
- **Статус:** Предложено | Принято | Отклонено | Заменено ADR-NNNN
|
||||
- **Дата:** YYYY-MM-DD
|
||||
- **Задача:** #1.5
|
||||
- **Участники:** Имя, Имя
|
||||
- **Зоны:** shared | frontend | backend
|
||||
|
||||
## Контекст
|
||||
Какая проблема, какие ограничения и факты. 3–6 предложений.
|
||||
|
||||
## Решение
|
||||
Что решили, конкретно и проверяемо.
|
||||
|
||||
## Рассмотренные варианты
|
||||
| Вариант | Плюсы | Минусы |
|
||||
|---|---|---|
|
||||
| | | |
|
||||
|
||||
## Последствия
|
||||
- Что становится проще, что сложнее, что нужно сделать (с ID задач).
|
||||
- Как понять, что решение пора пересмотреть.
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
date: YYYY-MM-DD
|
||||
zone: frontend | backend | shared
|
||||
task: "2.13"
|
||||
items: ["2.13.1", "2.13.2"]
|
||||
branch: feat/2.13-design-tokens
|
||||
pr: —
|
||||
impact: none | shared
|
||||
status: в работе | на проверке | смержено
|
||||
author: Имя
|
||||
---
|
||||
|
||||
# [2.13] Кратко, что делаем
|
||||
|
||||
## Сделано
|
||||
- Что сделано и где лежит (`путь/к/файлу`). Отмеченный пункт карты — с его ID.
|
||||
|
||||
## Решения
|
||||
- Что решили и почему. Значимое → ADR-NNNN.
|
||||
|
||||
## Для другой стороны
|
||||
<!-- Только при impact: shared. Что изменилось для другой зоны и что ей нужно сделать. Иначе удалить раздел. -->
|
||||
|
||||
## Отклонения от плана
|
||||
<!-- Пункт сделан иначе / не нужен / появился новый. Иначе удалить раздел. -->
|
||||
|
||||
## Проверка
|
||||
- Какие тесты, линтеры, ручные проверки пройдены.
|
||||
|
||||
## Осталось
|
||||
- [ ] Что не доделано в этой ветке.
|
||||
|
||||
## Идеи и бэклог
|
||||
<!-- Найдено вне текущего шага, не делали. Иначе удалить раздел. -->
|
||||
@@ -0,0 +1,22 @@
|
||||
# Название модуля / экрана / компонента
|
||||
|
||||
- **Зона:** frontend | backend | shared
|
||||
- **Где в коде:** `путь/`
|
||||
- **Задачи:** #2.14, #3.2
|
||||
- **Связанные ADR и документы:** ADR-0008, `docs/architecture/...`
|
||||
|
||||
## Назначение
|
||||
Что делает и чего НЕ делает. 2–4 предложения.
|
||||
|
||||
## Как устроено
|
||||
Ключевые части, поток данных, точки расширения. Схема — если помогает.
|
||||
|
||||
## Контракт и зависимости
|
||||
- Эндпоинты / сообщения proto / таблицы / компоненты `packages/ui`, от которых зависит.
|
||||
- Права и функции (`perm.*`, `features.*`), которые проверяются.
|
||||
|
||||
## Правила и подводные камни
|
||||
- То, что нельзя нарушать, и то, на чём легко ошибиться.
|
||||
|
||||
## Как проверить
|
||||
- Тесты, команды, ручной сценарий.
|
||||
@@ -0,0 +1,15 @@
|
||||
# Backend: документы зоны
|
||||
|
||||
Зона `backend` (`docs/ai/PROTOCOL.md`, раздел 2): сервер `shtil-server`, агент `shtil-agent`, БД, окружение, сборка.
|
||||
Здесь — внутренние правила Backend, которые не нужны Frontend. Всё, что влияет на API, протокол, права, функции, конфиг, — в `shared`.
|
||||
|
||||
## Документы
|
||||
|
||||
| Файл | О чём | Появится в |
|
||||
|---|---|---|
|
||||
| `conventions.md` | Структура `internal/server/<область>`, слои, ошибки, логи, тесты, транзакции | #2.10 |
|
||||
| `areas/<область>.md` | Область сервера (`access`, `sites`, `audit`…): таблицы, сервисные функции, права, события NATS | по мере появления |
|
||||
| `agent.md` | Устройство агента: транспорт, сборщики, очередь, исполнитель, платформенные части | шаг 4–5 |
|
||||
| `operations.md` | Запуск, конфиг, переменные окружения, миграции, диагностика | #2.8 |
|
||||
|
||||
Шаблон для областей и модулей — `docs/ai/templates/module.md`. Общая архитектура, ERD, правила БД, IPC — `docs/architecture/` (shared).
|
||||
@@ -0,0 +1,25 @@
|
||||
# Frontend: документы зоны
|
||||
|
||||
Зона `frontend` (`docs/ai/PROTOCOL.md`, раздел 2): приложение «Штиль» (`apps/console`), «Штиль Помощник» (`apps/helper`), дизайн-система `packages/ui`.
|
||||
Здесь — внутренние правила Frontend, которые не нужны Backend. Всё, что влияет на API, права, функции, безопасность Tauri, — в `shared`.
|
||||
|
||||
## Документы
|
||||
|
||||
| Файл | О чём | Появится в |
|
||||
|---|---|---|
|
||||
| `design-system.md` | Токены (цвета, отступы, радиусы, тени), темы, типографика, иконки, правила вёрстки | #2.13 |
|
||||
| `components.md` | Каталог компонентов `packages/ui`: назначение, варианты, когда какой использовать | #2.13 |
|
||||
| `conventions.md` | Структура `src/`, именование, состояние (Pinia / TanStack Query), роутинг, i18n, обработка ошибок API | #2.14 |
|
||||
| `platform-layer.md` | Слой `src/platform/`: Tauri API, хранилище ключей, профили серверов | #2.14 |
|
||||
| `screens/<экран>.md` | Экран: назначение, данные, права, состояния (загрузка, пусто, ошибка) | по мере появления |
|
||||
|
||||
Шаблон для экранов и модулей — `docs/ai/templates/module.md`. Информационная архитектура и макеты (общие для обеих сторон) — `docs/ux/`.
|
||||
|
||||
## Исходные данные из дорожной карты (до решений #1.11 и #2.13)
|
||||
|
||||
Это рекомендации карты, а не принятые решения. После решения перенести в `design-system.md` и удалить отсюда.
|
||||
- Шрифты Unbounded, Manrope, JetBrains Mono — локально, без CDN. Иконки — Lucide.
|
||||
- Темы светлая и тёмная, по умолчанию — системная. Минимальный размер окна 1280×720.
|
||||
- Меню ≤ 11 пунктов в 3 группах: Работа · Управление · Аналитика. Недоступное по правам или редакции скрыто.
|
||||
- Селектор области (подразделения) фильтрует весь экран. Карточки — в боковой панели. Ctrl+K — поиск и команды.
|
||||
- Помощник: при старте только иконка в трее, окно создаётся по клику и уничтожается при закрытии; цели ≤ 40 МБ ОЗУ в покое, ≤ 150 МБ с окном, открытие ≤ 1 с.
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
date: 2026-11-08
|
||||
zone: shared
|
||||
task: "1.2"
|
||||
items: []
|
||||
branch: chore/1.2-ai-docs-protocol
|
||||
pr: —
|
||||
impact: shared
|
||||
status: в работе
|
||||
author: Frontend
|
||||
---
|
||||
|
||||
# [1.2] Система документирования для AI-ассистентов
|
||||
|
||||
## Сделано
|
||||
- Протокол работы AI: `docs/ai/PROTOCOL.md` — источники истины, зоны frontend/backend/shared, чек-листы начала и конца сессии.
|
||||
- Сверка с дорожной картой: `docs/ai/roadmap.md` и скрипт `tools/roadmap-context/roadmap-context.mjs` (Node 18+, без зависимостей, только чтение).
|
||||
- Шаблоны: `docs/ai/templates/` — запись журнала, ADR, описание модуля.
|
||||
- Снимки состояния: `docs/status/shared.md`, `frontend.md`, `backend.md`.
|
||||
- Индексы зон: `docs/frontend/README.md`, `docs/backend/README.md`; карта документации `docs/README.md`.
|
||||
- `AGENTS.md`: раздел 9 «Документирование и контекст».
|
||||
|
||||
## Решения
|
||||
- Дорожная карта остаётся единственным трекером; AI её только читает и готовит текст для людей.
|
||||
- Память проекта для AI — `docs/status` (снимок) + `docs/journal` (история по PR), документация коммитится в той же ветке, что и код.
|
||||
- Внутренние документы зоны в `docs/frontend` и `docs/backend`; ассистент другой зоны их не читает без необходимости.
|
||||
|
||||
## Для другой стороны
|
||||
- Backend: прочитать `docs/ai/PROTOCOL.md`, добавить личный блок правил с `зона: backend` (раздел 8).
|
||||
|
||||
## Проверка
|
||||
- `node tools/roadmap-context/roadmap-context.mjs` и `... 1.2` против https://locshare.ru/roadmap/ — сводка выводится.
|
||||
|
||||
## Осталось
|
||||
- [ ] Обсудить протокол вдвоём, при необходимости поправить.
|
||||
- [ ] Перенести в репозиторий Gitea вместе с остальными файлами (#1.2.3).
|
||||
- [ ] Включить пароль на roadmap-server (#1.1.2): сейчас `/api/progress` читается без авторизации.
|
||||
@@ -0,0 +1,8 @@
|
||||
# Журнал работы
|
||||
|
||||
Одна запись на ветку/PR. Шаблон — `docs/ai/templates/journal-entry.md`, правила — `docs/ai/PROTOCOL.md`.
|
||||
|
||||
- Имя: `YYYY-MM-DD-<зона>-<ID>-<кратко>.md`, дата — день создания ветки.
|
||||
- `zone` — чья работа; `impact: shared` — запись обязательна к прочтению другой стороной.
|
||||
- Запись правит только её автор. Смерженную запись не переписывают; исправление — новой записью.
|
||||
- Ассистент в начале сессии читает последние 5 записей своей зоны и все `impact: shared` новее своей последней записи.
|
||||
@@ -0,0 +1,24 @@
|
||||
# Состояние: Backend
|
||||
|
||||
Обновлено: 2026-11-08 · Владелец: Backend-разработчик
|
||||
|
||||
Снимок, а не история. Внутренние правила зоны — `docs/backend/`.
|
||||
|
||||
## Сейчас
|
||||
- Кода нет. Впереди в шаге 1: Gitea и правила Git (#1.2), решения 1.4–1.7, тестовый стенд (#1.12).
|
||||
|
||||
## Сделано в текущем шаге
|
||||
- —
|
||||
|
||||
## В работе
|
||||
<!-- - #ID · ветка · что осталось -->
|
||||
- —
|
||||
|
||||
## Ждём от Frontend
|
||||
- —
|
||||
|
||||
## Ближайшее
|
||||
- —
|
||||
|
||||
## Известные проблемы и долги
|
||||
- —
|
||||
@@ -0,0 +1,24 @@
|
||||
# Состояние: Frontend
|
||||
|
||||
Обновлено: 2026-11-08 · Владелец: Frontend-разработчик
|
||||
|
||||
Снимок, а не история. Внутренние правила зоны — `docs/frontend/`.
|
||||
|
||||
## Сейчас
|
||||
- Кода нет. Впереди в шаге 1: макеты и информационная архитектура (#1.11), окно Помощника (#1.9.7), PoC трея Tauri (#1.8.1–1.8.2).
|
||||
|
||||
## Сделано в текущем шаге
|
||||
- —
|
||||
|
||||
## В работе
|
||||
<!-- - #ID · ветка · что осталось -->
|
||||
- —
|
||||
|
||||
## Ждём от Backend
|
||||
- —
|
||||
|
||||
## Ближайшее
|
||||
- —
|
||||
|
||||
## Известные проблемы и долги
|
||||
- —
|
||||
@@ -0,0 +1,32 @@
|
||||
# Состояние: общее (shared)
|
||||
|
||||
Обновлено: 2026-11-08 · Шаг 1 «Решения и подготовка» · Версия —
|
||||
|
||||
Снимок, а не история. Правила — `docs/ai/PROTOCOL.md`, разделы 2 и 6.
|
||||
|
||||
## Сейчас
|
||||
- Продуктового кода нет. Идёт шаг 1: решения, Gitea, окружение, макеты.
|
||||
- Дорожная карта на сервере работает (#1.1 выполнено).
|
||||
- Введена система документирования для AI: `docs/ai/`, `docs/status/`, `docs/journal/`, `tools/roadmap-context/`.
|
||||
|
||||
## Контракты
|
||||
| Контракт | Состояние | Последнее изменение |
|
||||
|---|---|---|
|
||||
| `api/openapi.yaml` | нет, шаг 2 (#2.5) | — |
|
||||
| `proto/agent/v1`, `proto/helper/v1` | нет, шаг 2 (#2.6) | — |
|
||||
| `migrations/` | нет, шаг 2 (#2.11) | — |
|
||||
| Каталог функций `docs/features.md` | нет, шаг 2 (#2.3) | — |
|
||||
|
||||
## Принятые решения (кратко, со ссылкой)
|
||||
- —
|
||||
|
||||
## Готово для другой стороны
|
||||
<!-- Формат: - YYYY-MM-DD · зона → зона · что готово · где (путь, эндпоинт, ADR) -->
|
||||
- —
|
||||
|
||||
## Запросы между зонами
|
||||
<!-- Формат: - [ ] YYYY-MM-DD · от зоны → к зоне · что нужно · зачем · #ID -->
|
||||
- —
|
||||
|
||||
## Блокеры
|
||||
- —
|
||||
@@ -0,0 +1,171 @@
|
||||
#!/usr/bin/env node
|
||||
// Сводка дорожной карты «Штиль» для AI-ассистентов и людей. Только чтение, без зависимостей, Node 18+.
|
||||
//
|
||||
// node tools/roadmap-context/roadmap-context.mjs текущий шаг + последние изменения
|
||||
// node tools/roadmap-context/roadmap-context.mjs 2 обзор шага 2
|
||||
// node tools/roadmap-context/roadmap-context.mjs 2.11 задача 2.11 полностью
|
||||
// node tools/roadmap-context/roadmap-context.mjs --all все шаги подробно (как «Сводка для AI»)
|
||||
// --remote-data брать план (data.js) с сервера, даже если есть локальный roadmap/data.js
|
||||
//
|
||||
// Переменные окружения: ROADMAP_URL, ROADMAP_AUTH («логин:пароль» для Basic Auth), ROADMAP_DATA.
|
||||
|
||||
import { readFile } from 'node:fs/promises';
|
||||
import { existsSync } from 'node:fs';
|
||||
import vm from 'node:vm';
|
||||
|
||||
const BASE = (process.env.ROADMAP_URL || 'https://locshare.ru/roadmap').replace(/\/+$/, '');
|
||||
const AUTH = process.env.ROADMAP_AUTH;
|
||||
const LOCAL = process.env.ROADMAP_DATA || 'roadmap/data.js';
|
||||
const args = process.argv.slice(2);
|
||||
const flag = n => args.includes(n);
|
||||
const target = args.find(a => !a.startsWith('--'));
|
||||
|
||||
const STATUS = { todo: 'Не начато', doing: 'В работе', review: 'На проверке', done: 'Выполнено', blocked: 'Заблокировано' };
|
||||
const KINDS = { comment: 'Комментарий', question: 'Вопрос', proposal: 'Предложение', blocker: 'Блокер', decision: 'Решение' };
|
||||
const DEC = { open: 'Не обсуждали', discuss: 'Обсуждаем', accepted: 'Принято', postponed: 'Отложено' };
|
||||
const PRIO = { normal: 'Обычный', high: 'Высокий', critical: 'Критичный' };
|
||||
|
||||
async function get(path, kind) {
|
||||
const headers = AUTH ? { Authorization: 'Basic ' + Buffer.from(AUTH).toString('base64') } : {};
|
||||
const r = await fetch(BASE + path, { headers, cache: 'no-store', signal: AbortSignal.timeout(15000) });
|
||||
if (!r.ok) throw new Error(`${path}: HTTP ${r.status}`);
|
||||
return kind === 'json' ? r.json() : r.text();
|
||||
}
|
||||
|
||||
function evalPlan(src) {
|
||||
const sandbox = { window: {} };
|
||||
vm.runInNewContext(src, sandbox, { timeout: 1000 });
|
||||
if (!sandbox.window.SHTIL_ROADMAP) throw new Error('data.js не содержит window.SHTIL_ROADMAP');
|
||||
return sandbox.window.SHTIL_ROADMAP;
|
||||
}
|
||||
|
||||
async function loadPlan(warn) {
|
||||
const hasLocal = existsSync(LOCAL) && !flag('--remote-data');
|
||||
const remote = await get('/roadmap/data.js', 'text').catch(e => (hasLocal ? null : Promise.reject(e)));
|
||||
if (!hasLocal) return { plan: evalPlan(remote), source: BASE + '/roadmap/data.js' };
|
||||
const local = await readFile(LOCAL, 'utf8');
|
||||
if (remote !== null && remote.replace(/\r\n/g, '\n') !== local.replace(/\r\n/g, '\n'))
|
||||
warn.push(`Локальный ${LOCAL} отличается от data.js на сервере: подтяните main или обновите сервер.`);
|
||||
return { plan: evalPlan(local), source: LOCAL };
|
||||
}
|
||||
|
||||
const strip = s => String(s ?? '')
|
||||
.replace(/<\/(p|div|tr|pre|ul|ol|table)>/gi, '\n').replace(/<br\s*\/?>/gi, '\n')
|
||||
.replace(/<li>/gi, '\n- ').replace(/<t[dh][^>]*>/gi, ' | ').replace(/<[^>]+>/g, '')
|
||||
.replace(/</g, '<').replace(/>/g, '>').replace(/"/g, '"').replace(/\/g, '\\').replace(/&/g, '&')
|
||||
.replace(/[ \t]+\n/g, '\n').replace(/\n{3,}/g, '\n\n').trim();
|
||||
const oneLine = s => strip(s).replace(/\s*\n\s*/g, ' ');
|
||||
const day = iso => (iso ? String(iso).slice(0, 10) : '—');
|
||||
const indent = s => String(s).replace(/\n/g, '\n ');
|
||||
|
||||
function build(plan, P) {
|
||||
const nameOf = id => P.members?.[id]?.name || id || '—';
|
||||
const steps = plan.phases.flatMap(ph => (ph.steps || []).map(st => ({ ...st, phase: ph })));
|
||||
const tasks = Object.fromEntries(steps.flatMap(st => (st.tasks || []).map(t => [t.id, { t, step: st }])));
|
||||
const tstate = id => ({ status: 'todo', assignees: [], priority: 'normal', ...(P.tasks?.[id] || {}) });
|
||||
const live = (sec, id) => Object.entries(P[sec] || {}).map(([k, v]) => ({ id: k, ...v })).filter(x => x.task === id && !x.deleted);
|
||||
const items = id => [
|
||||
...(tasks[id].t.subtasks || []).map(([sid, text]) => ({ id: sid, text })),
|
||||
...live('custom', id).map(c => ({ id: c.id, text: c.text, own: nameOf(c.by) })),
|
||||
];
|
||||
const done = iid => !!P.items?.[iid]?.done;
|
||||
const stats = id => { const it = items(id); return { done: it.filter(i => done(i.id)).length, total: it.length }; };
|
||||
const comments = id => live('comments', id).sort((a, b) => String(a.created_at).localeCompare(String(b.created_at)));
|
||||
const answer = (id, i) => P.answers?.[`${id}~${i}`];
|
||||
|
||||
function taskLine(id) {
|
||||
const { t } = tasks[id], st = tstate(id), s = stats(id), cs = comments(id);
|
||||
const q = (t.discuss || []).length, qa = (t.discuss || []).filter((_, i) => answer(id, i + 1)?.text).length;
|
||||
const parts = [`${s.done}/${s.total}`];
|
||||
if (st.assignees.length) parts.push(st.assignees.map(nameOf).join(', '));
|
||||
if (st.priority !== 'normal') parts.push('приоритет: ' + PRIO[st.priority]);
|
||||
if (st.due) parts.push('срок ' + st.due);
|
||||
if (t.decision) parts.push('решение: ' + DEC[P.decisions?.[id]?.status || 'open']);
|
||||
if (q) parts.push(`ответов на вопросы ${qa}/${q}`);
|
||||
const blk = cs.filter(c => c.kind === 'blocker' && !c.resolved).length;
|
||||
const oq = cs.filter(c => c.kind === 'question' && !c.resolved).length;
|
||||
if (blk) parts.push(`БЛОКЕРЫ: ${blk}`);
|
||||
if (oq) parts.push(`открытые вопросы в обсуждении: ${oq}`);
|
||||
return `- [${STATUS[st.status] || st.status}] ${id} ${t.title} · ${parts.join(' · ')}`;
|
||||
}
|
||||
|
||||
function stepBlock(st, detailed) {
|
||||
const all = (st.tasks || []).map(t => stats(t.id)).reduce((a, s) => ({ d: a.d + s.done, n: a.n + s.total }), { d: 0, n: 0 });
|
||||
const cur = plan.meta.current?.step === st.id ? ' ← ТЕКУЩИЙ' : '';
|
||||
const L = [`## Шаг ${st.id} · ${st.title} (${st.period}, версия ${st.version})${cur} — пунктов ${all.d}/${all.n}`, oneLine(st.goal)];
|
||||
if (!st.tasks) { if (st.preview) L.push('Планируется: ' + st.preview.join('; ')); return L; }
|
||||
if (st.outcome) L.push('Результат шага: ' + st.outcome.join('; '));
|
||||
L.push('');
|
||||
(st.tasks || []).forEach(t => (detailed ? L.push(...taskDetail(t.id), '') : L.push(taskLine(t.id))));
|
||||
return L;
|
||||
}
|
||||
|
||||
function taskDetail(id) {
|
||||
const { t, step } = tasks[id], st = tstate(id), s = stats(id);
|
||||
const L = [`### [${id}] ${t.title}`,
|
||||
`Шаг ${step.id} · области: ${(t.area || []).map(a => plan.areas[a] || a).join(', ')} · тип: ${plan.types[t.type] || t.type}${t.adr ? ' · ADR-' + t.adr : ''}`,
|
||||
`Статус: ${STATUS[st.status]} · пункты ${s.done}/${s.total}` + (st.assignees.length ? ' · исполнители: ' + st.assignees.map(nameOf).join(', ') : '') + (st.due ? ' · срок ' + st.due : '') + (st.priority !== 'normal' ? ' · приоритет: ' + PRIO[st.priority] : '')];
|
||||
if (t.why) L.push('', '**Зачем:** ' + oneLine(t.why));
|
||||
if (t.body) L.push('', '**Описание:**', strip(t.body));
|
||||
if (t.recommend) L.push('', '**Рекомендация:**', strip(t.recommend));
|
||||
if (t.discuss?.length) {
|
||||
L.push('', '**Вопросы:**');
|
||||
t.discuss.forEach((q, i) => { const a = answer(id, i + 1); L.push(`- В${i + 1}: ${oneLine(q)}`, a?.text ? ` Ответ (${nameOf(a.by)}, ${day(a.at)}): ${indent(a.text)}` : ' Ответа нет'); });
|
||||
}
|
||||
if (t.decision) { const d = P.decisions?.[id] || {}; L.push('', `**Решение [${DEC[d.status || 'open']}]:** ${d.text ? indent(d.text) : '—'}`); }
|
||||
L.push('', '**Выполнение:**', ...items(id).map(i => `- [${done(i.id) ? 'x' : ' '}] ${i.own ? `«${i.text}» (свой пункт, ${i.own}, ${i.id})` : `${i.id} ${oneLine(i.text)}`}`));
|
||||
if (t.done) L.push('', '**Готово, когда:** ' + oneLine(t.done));
|
||||
if (t.artifacts?.length) L.push('**Артефакты:** ' + t.artifacts.join(', '));
|
||||
const n = P.notes?.[id];
|
||||
if (n?.text?.trim()) L.push('', `**Заметка (${nameOf(n.by)}):**`, n.text.trim());
|
||||
const cs = comments(id);
|
||||
if (cs.length) { L.push('', '**Обсуждение:**'); cs.forEach(c => L.push(`- ${day(c.created_at)} ${nameOf(c.author)} [${KINDS[c.kind || 'comment']}${c.resolved ? ', решено' : ''}]: ${indent(c.text)}`)); }
|
||||
const ls = live('links', id);
|
||||
if (ls.length) L.push('', '**Ссылки:** ' + ls.map(l => (l.title ? l.title + ' — ' : '') + l.url).join('; '));
|
||||
return L;
|
||||
}
|
||||
|
||||
function recent(limit) {
|
||||
const ev = [];
|
||||
for (const [k, v] of Object.entries(P.items || {})) if (v?.done) ev.push([v.at, v.by, `отметил(а) пункт ${k}`]);
|
||||
for (const [k, v] of Object.entries(P.tasks || {})) ev.push([v.at, v.by, `задача ${k}: ${STATUS[v.status] || v.status}`]);
|
||||
for (const [k, v] of Object.entries(P.decisions || {})) ev.push([v.at, v.by, `решение ${k}: ${DEC[v.status || 'open']}${v.text ? ' — ' + oneLine(v.text).slice(0, 120) : ''}`]);
|
||||
for (const [k, v] of Object.entries(P.answers || {})) if (v?.text) ev.push([v.at, v.by, `ответ на ${k.replace('~', ' В')}: ${oneLine(v.text).slice(0, 120)}`]);
|
||||
for (const c of Object.values(P.comments || {})) if (!c.deleted) ev.push([c.created_at, c.author, `${KINDS[c.kind || 'comment']} в ${c.task}: ${oneLine(c.text).slice(0, 120)}`]);
|
||||
return ev.filter(e => e[0]).sort((a, b) => String(b[0]).localeCompare(String(a[0]))).slice(0, limit)
|
||||
.map(([at, by, text]) => `- ${String(at).slice(0, 16).replace('T', ' ')} ${nameOf(by)}: ${text}`);
|
||||
}
|
||||
|
||||
return { steps, tasks, stepBlock, taskDetail, recent, nameOf };
|
||||
}
|
||||
|
||||
async function main() {
|
||||
const warn = [];
|
||||
const [{ plan, source }, P] = await Promise.all([
|
||||
loadPlan(warn),
|
||||
get('/api/progress', 'json').catch(e => { throw new Error(`прогресс недоступен (${e.message}). Попросите пользователя вставить «Настройки → Сводка для AI».`); }),
|
||||
]);
|
||||
const R = build(plan, P);
|
||||
const cur = plan.meta.current || {};
|
||||
const out = [`# Дорожная карта «Штиль» · ревизия ${P.revision ?? '—'} · прогресс от ${day(P.updated_at)} · план от ${plan.meta.updated} (${source})`,
|
||||
`Текущая фаза ${cur.phase}, шаг ${cur.step}. Команда: ${Object.values(P.members || {}).filter(m => !m.archived).map(m => m.name + (m.role ? ` (${m.role})` : '')).join(', ') || '—'}`];
|
||||
if (warn.length) out.push(...warn.map(w => '> ВНИМАНИЕ: ' + w));
|
||||
out.push('');
|
||||
|
||||
if (target && /^\d+\.\d+$/.test(target)) {
|
||||
if (!R.tasks[target]) throw new Error(`задачи ${target} нет в плане`);
|
||||
out.push(...R.taskDetail(target));
|
||||
} else if (flag('--all')) {
|
||||
R.steps.forEach(st => out.push(...R.stepBlock(st, !!st.tasks), ''));
|
||||
} else {
|
||||
const id = target || cur.step;
|
||||
const st = R.steps.find(s => s.id === id);
|
||||
if (!st) throw new Error(`шага ${id} нет в плане`);
|
||||
out.push(...R.stepBlock(st, false), '', '## Последние изменения', ...R.recent(15));
|
||||
const next = R.steps.filter(s => Number(s.id) > Number(id)).slice(0, 2).map(s => `${s.id} · ${s.title}`);
|
||||
if (next.length) out.push('', 'Дальше: ' + next.join('; '));
|
||||
}
|
||||
process.stdout.write(out.join('\n') + '\n');
|
||||
}
|
||||
|
||||
main().catch(e => { console.error('roadmap-context: ' + e.message); process.exit(1); });
|
||||
Reference in new issue
Block a user