go-lcg/ROADMAP.md

# Дорожная карта развития (функциональность и безопасность)

Документ описывает план развития проекта на ближайшие релизы с фокусом на улучшение функциональности и усиление безопасности.

## Принципы

- Безопасность по умолчанию: новые возможности включают безопасные дефолты, опционально ослабляются.
- Обратная совместимость: не ломать существующие сценарии CLI и API.
- Прозрачность: чёткие Changelog, версии по SemVer, миграции и откаты.
- Качество: тесты, линтеры, аудит зависимостей, автоматизация релизов.

## Вехи и цели

### v2.1.0 — Формализация API и UX улучшения

- REST API
  - Описать `POST /execute` в OpenAPI (swagger.yaml/json) и приложить в репозитории.
  - Валидация входа по схеме: обязательные поля, ограничения длины, лимит размера тела.
  - Явные коды ошибок и структура ответа (коды/сообщения).
- Безопасность API (первый этап)
  - Дополнить защиту: ограничение размера тела (например, 64KB), тайм-ауты на чтение/запись.
  - Rate limit (встроенный простой токен-бакет, по IP). Конфиг через env.
  - Логирование попыток доступа и ошибок API (с редактированием PII).
- Веб-интерфейс
  - Улучшения мобильной версии (доступность, контраст, a11y-метки).
  - Переключатель темы (light/dark), сохранение предпочтений.
- Промпты
  - Экспорт/импорт системных промптов (JSON) из UI/CLI.
  - Превью при редактировании промптов в UI.
- Документация
  - `API_GUIDE.md`: синхронизировать с OpenAPI.
  - `USAGE_GUIDE.md`: добавить раздел «Ограничения API и лимиты».

### v2.2.0 — Усиление безопасности и управление доступом

- Аутентификация/Авторизация для веб-сервера
  - Ввести токен доступа для API: `LCG_SERVER_TOKEN` (Bearer), отключаемо.
  - Сессии UI (опционально): cookie HttpOnly + SameSite=strict, CSRF-защита форм.
  - CORS: явный список разрешённых Origin через `LCG_CORS_ORIGINS`.
- Транспорт и заголовки безопасности
  - Рекомендации по TLS терминации (пример конфигов nginx/caddy) в `serve/README.md`.
  - Security headers: CSP, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, HSTS (при HTTPS).
- Хранилище и история
  - Опциональное шифрование истории на диске (`LCG_HISTORY_ENCRYPTION_KEY_FILE`).
  - Права на файлы истории и результатов: 0600, директории 0700.
  - Настраиваемая ретенция истории (дни/размер). Авто-очистка.
- Наблюдаемость
  - Аудит-лог действий UI/API с маскированием чувствительных данных.
  - Включаемые/отключаемые метрики (prometheus endpoint — опционально, по отдельному порту/токену).

### v2.3.0 — Расширяемость и производительность

- Плагины провайдеров
  - Интерфейс адаптеров (провайдеры LLM), регистрация через конфиг/билд-теги.
  - Образцы адаптеров и гайды по разработке.
- Производительность
  - Пулы HTTP-клиентов, connection reuse, упреждающие таймауты на уровне контекста.
  - Кэширование результатов подробных объяснений (опционально, по ключу запроса).
- Расширения API
  - Пакетная обработка запросов (batch) с квотой.
  - Пагинация и фильтрация для `/history` (если будет публичный REST).
- Дистрибуция
  - Улучшения .goreleaser: публикация SBOM, подписи (cosign), детерминированные сборки.
  - Готовые пакеты: deb/rpm, инструкции для brew/scoop (по возможности).

## Backlog (кандидаты)

- Потоковая генерация (stream) и WebSocket-канал (при наличии поддержки у провайдеров).
- Оффлайн-режим/кэширование моделей для локальных провайдеров.
- Расширенный поиск по результатам/истории, теги и сохранённые фильтры.
- Резервное копирование и восстановление каталога результатов/истории.
- Улучшение доступности (a11y), горячие клавиши, локализация интерфейса.

## Техническое качество

- Обновление стека
  - Обновить Go (минимум 1.20+), пересобрать и протестировать совместимость.
  - Регулярные обновления зависимостей и проверка уязвимостей (`govulncheck`).
- Линтеры и проверка качества
  - Включить `golangci-lint`, `staticcheck`, `gosec` в CI.
  - Форматирование и единый стиль, pre-commit хуки.
- Тесты
  - Unit-тесты на `serve/*` (маршруты, валидация входных данных, заголовки).
  - Интеграционные тесты API `/execute` (позитив/негатив, лимиты, токены).
  - Фаззинг критичных функций парсинга/валидации.
- CI/CD
  - GitHub Actions: сборка, тесты, линты, релизы. Генерация чек-сумм, подписи, SBOM.
  - Автоматическая публикация релизов и проверок артефактов.

## Конфигурация (новые/уточняемые переменные)

- `LCG_SERVER_TOKEN` — токен доступа для API (Bearer). Отключаемый режим.
- `LCG_RATE_LIMIT` — глобальные лимиты (например, `60/m`, `5/s`).
- `LCG_CORS_ORIGINS` — список разрешённых Origin.
- `LCG_HISTORY_ENCRYPTION_KEY_FILE` — путь к ключу для шифрования истории (опц.).
- `LCG_MAX_BODY_BYTES` — максимальный размер тела запроса, байты (по умолчанию 65536).
- `LCG_BROWSER_PATH` — путь к браузеру для `--browser`.

## Политика релизов

- SemVer: MINOR — функционал без ломаний, PATCH — багфиксы/мелкие улучшения.
- Каждый релиз: обновлённый `CHANGELOG.txt`, теги `vX.Y.Z`, двуязычная документация (RU/EN при возможности).
- Security Advisories: отдельный раздел/ISSUE шаблон для отчётов об уязвимостях.

## Критерии приемки (примеры)

- v2.1.0: OpenAPI спецификация доступна, API валидируется по схеме, лимит размера тела и таймауты соблюдаются, добавлены тесты в CI.
- v2.2.0: Доступ к API с токеном включаем/отключаем через env; активированы security-заголовки; есть базовые правила CORS; аудит-лог включается флагом.
- v2.3.0: Пулы клиентов, бенчмарки показывают улучшение p95 латентности, есть механизм подключения новых провайдеров.

## Риски и смягчение

- Ломание совместимости при усилении безопасности → режим совместимости через env/флаги.
- Рост сложности конфигурации → шаблоны конфигов и «рецепты» в README/serve/README.md.
- Производительные регрессии из-за валидации/лимитов → профилирование и кэширование на горячих путях.

---
Последнее обновление: 2025-10-22