1. Общие сведения

Документ описывает процессы, обеспечивающие поддержание жизненного цикла программного обеспечения «Интеллектуальный ИИ-ассистент геолога»: разработку, сборку, контроль качества, развёртывание, обновление, резервное копирование, мониторинг и техническую поддержку.

ПО развивается по итеративной модели: изменения вносятся в исходный код, проходят контроль качества и автоматически разворачиваются на целевых серверах.

2. Среда и инструменты разработки

Для локальной разработки используется Docker Compose: база данных запускается в контейнере, сервисы — нативно с автоперезагрузкой либо также в контейнерах.

3. Управление исходным кодом

• Исходный код ведётся в системе контроля версий Git.
• Основная ветка — main; изменения вносятся через отдельные ветки и объединяются в main.
• Структура репозитория — монорепозиторий: общие контракты, сервисы (api, neuro, front), миграции БД (db/migrations), скрипты (scripts), файлы развёртывания.
• Конфиденциальные данные (пароли, секреты) в репозиторий не помещаются и задаются переменными окружения при развёртывании.

4. Сборка программного обеспечения

Каждый сервис собирается в отдельный Docker-образ:

• api — многоступенчатая сборка: компиляция TypeScript → исполняемый образ Node.js (включает миграции БД).
• front — сборка SPA сборщиком Vite → раздача статики через nginx.
• neuro — образ Python с установленными зависимостями (TensorFlow и др.).

Для локальной поставки предусмотрена сборка дистрибутива: образы выгружаются в архивы (docker save) и упаковываются вместе с файлами запуска в zip-архив (скрипт scripts/package-dist.sh).

5. Контроль качества

• Статическая проверка типов — обязательная проверка TypeScript (tsc --noEmit) для веб-интерфейса и сервера приложений; является частью сборки и предотвращает выпуск кода с ошибками типов.
• Ревью изменений — проверка кода перед включением в основную ветку.
• Идемпотентность миграций — миграции пишутся безопасными для повторного применения, что исключает рассогласование схемы БД.
• Проверка развёртывания — корректность сборки и запуска проверяется на тестовом окружении до выпуска.

6. Развёртывание и обновление

Развёртывание автоматизировано. При публикации изменений в ветку main автоматизированный конвейер по защищённому каналу (SSH) выполняет на целевых серверах обновление:

git pull --ff-only && bash scripts/deploy.sh

Скрипт deploy.sh выполняет последовательность:

1. запуск базы данных и ожидание её готовности;
2. применение миграций БД;
3. пересборку и перезапуск сервисов (docker compose up -d --build);
4. очистку устаревших образов.

Данные в базе сохраняются между обновлениями. Для локальной поставки обновление выполняется заменой образов (docker load) и перезапуском (docker compose up -d).

7. Миграции базы данных

• Изменения схемы оформляются нумерованными SQL-файлами в каталоге db/migrations.
• Миграции пишутся идемпотентно (CREATE TABLE IF NOT EXISTS, ADD COLUMN IF NOT EXISTS и т. п.).
• Применение выполняется автоматически при старте сервера приложений, а также скриптом scripts/migrate.sh при развёртывании; повторный прогон безопасен.

8. Резервное копирование и восстановление

Резервное копирование базы данных выполняется штатными средствами PostgreSQL:

docker compose exec -T postgres pg_dump -U neurogeo neurogeo | gzip > backup.sql.gz

Восстановление — из созданной копии в чистую базу. Рекомендуется выполнять резервное копирование по расписанию (cron) и хранить копии вне сервера.

9. Мониторинг и журналирование

• Журналы сервисов доступны средствами Docker (docker compose logs).
• Состояние базы данных контролируется через healthcheck контейнера.
• Ход длительных операций (построение модели, обучение, удаление) отражается в таблице задач и транслируется в интерфейс в реальном времени (SSE), что позволяет отслеживать выполнение и ошибки.

10. Техническая поддержка и устранение неполадок

Техническая поддержка осуществляется правообладателем по электронной почте: support@neurogeo.io.

11. Управление версиями и выпуск

• Версии ПО фиксируются в системе контроля версий (теги/коммиты ветки main).
• Выпуск новой версии сопровождается обновлением образов и (при необходимости) миграциями БД.
• Для распространения формируется версионированный дистрибутив (zip с образами и файлами запуска).
• Откат к предыдущей версии возможен возвратом к соответствующему состоянию репозитория/образов; данные БД при этом сохраняются.