Restructure technical specification sections

docs/tz/infrastructure-operations.md

@@ -0,0 +1,79 @@
+# 8. Требования к инфраструктуре и эксплуатации
+
+## 8.1 Инфраструктурная схема
+
+Текущая инфраструктурная схема проекта включает прикладные сервисы, сервис секретов, мессенджерные сервисы и вспомогательный worker-контур.
+
+![Инфраструктура, деплой и эксплуатационный контур](/diagrams/infrastructure-topology.svg)
+
+## 8.2 Сервисы и окружение
+
+Сервисы проекта и способ их развёртывания:
+
+| Сервис | Путь в репозитории | Роль | Deploy mode | Сервер |
+| --- | --- | --- | --- | --- |
+| web-frontend | `web-frontend` | клиентский и менеджерский веб-интерфейс | `dokploy_webhook` | `main` |
+| apollo-backend | `apollo-backend` | GraphQL API и бизнес-логика | `dokploy_webhook` | `main` |
+| hatchet-worker | `hatchet-worker` | фоновый worker-контур | `dokploy_webhook` | `main` |
+| tg-bot | `tg-bot` | Telegram-контур | `dokploy_webhook` | `main` |
+| max-bot | `max-bot` | MAX-контур | `dokploy_webhook` | `main` |
+| bonus-bot | `bonus-bot` | бонусный сервис | `dokploy_webhook` | `main` |
+| vault | `vault` | сервис секретов | `dokploy_webhook` | `main` |
+
+## 8.3 Требования к деплою и запуску
+
+Для основных сервисов проекта используется режим `dokploy_webhook`.
+
+Цепочка развёртывания должна быть следующей:
+
+1. изменения фиксируются в Git-репозитории
+2. изменения публикуются в `main`
+3. Dokploy получает webhook-событие
+4. Dokploy выполняет сборку соответствующего сервиса
+5. сервис перезапускается с загрузкой секретов из Vault
+6. после старта выполняются bootstrap-действия, предусмотренные образом и entrypoint-командой
+
+Текущие особенности прикладных сервисов:
+
+- `web-frontend` стартует через загрузку Vault env и запуск `.output/server/index.mjs`
+- `apollo-backend` стартует через загрузку Vault env, `prisma migrate deploy` и запуск `src/server.js`
+- bot-сервисы стартуют через общий паттерн загрузки Vault env и запуск `node src/server.js`
+
+## 8.4 Требования к секретам и конфигурации
+
+Сервисы программного продукта должны получать прикладные секреты из `Vault`.
+
+В конфигурации сервисов допускается хранение только bootstrap-параметров для подключения к Vault. Бизнес-секреты, ключи интеграций и иные чувствительные данные должны загружаться из Vault при старте приложения.
+
+Сервис `vault` развернут как отдельное приложение на базе образа `hashicorp/vault:1.21.3`.
+
+Прикладные сервисы используют общий shell-bootstrap `load-vault-env.sh`, который:
+
+- ожидает доступность Vault по health endpoint
+- загружает shared secrets
+- загружает project secrets
+- экспортирует секреты в runtime environment процесса
+
+## 8.5 Требования к эксплуатации и надежности
+
+Система должна обеспечивать:
+
+- корректную работу в десктопных и мобильных браузерах
+- приемлемое время открытия основных экранов и выполнения действий
+- сохранность пользовательских данных
+- сохранность истории изменений по заявкам, заказам и бонусным операциям
+- фиксацию ошибок интеграционного обмена
+- журналирование значимых системных и пользовательских событий
+- возможность сопровождения и развития клиентского и менеджерского контуров
+
+## 8.6 Требования к передаче результата и эксплуатации
+
+По результатам выполнения работ заказчику должны быть переданы:
+
+- исходный код программного продукта
+- техническое задание в согласованной редакции
+- сведения об используемых компонентах и их версиях
+- описание реализованных интеграций и используемых внешних интерфейсов
+- схемы взаимодействия модулей и движения данных
+- описание пользовательских ролей и прав доступа
+- материалы, необходимые для сопровождения и эксплуатации продукта