# Развёртывание Deconflictor в компании

Deconflictor принимает изменения через веб-интерфейс, API и нормализованные вебхуки,
сопоставляет их окна с графом зависимостей и сохраняет решение с проверяемыми основаниями.
Это прототип: одна компания, одна БД и один процесс приложения на установку. Для начала
используйте режим рекомендаций `advisory`; решение о выпуске принимает ваша интеграция.

[Английская версия](company-deployment.en.md). Контракт API: [OpenAPI](../../openapi.json).
В вашей установке интерактивный справочник Swagger находится на `/docs`, схема — на
`/openapi.json`. Публичная копия справочника не отправляет запросы в установки компаний.

## Подготовка

Нужны Docker Engine с Compose v2, доступ к выданному исходному коду или согласованному образу,
HTTPS-прокси и доступ к выбранной модели. Команды ниже выполняются в корне репозитория.
Образ собирается для Linux; базовые образы и зависимости закреплены в исходном коде.
Подберите ресурсы по своему объёму заявок и нагрузке: универсальной гарантии пропускной
способности нет. Приложение оценивает заявки последовательно и сохраняет заявки и решения в PostgreSQL.
Очередь worker находится в памяти; незавершённые оценки восстанавливаются из БД.

Подготовьте каталог `deployment/` с двумя файлами: `catalog-info.yaml` и `policy.yaml`.
В каталоге Backstage используйте устойчивые имена `Component` и `Resource`;
ребро `frontend → database` означает «frontend зависит от database».
Начните с [примера каталога](../../topologies/otel-demo-3.1.0/catalog-info.yaml), заменив
его сервисами компании. Внешние `Location` рекурсивно не загружаются; доставку свежего
файла из вашей CMDB или Backstage настраивает администратор.

Возьмите [пример политики](../../policy.example.yaml) и замените поверхности и окна.
Без ограничений файл содержит:

```yaml
blackouts: []
maintenance_windows: []
```

Повтор неизменённого импорта не меняет граф. Приложение отказывается работать с пустым
каталогом. Текущий предел Intake — 300 поверхностей; до подключения более крупной области
проверьте полноту графа и ограничения прототипа. Разделение установок не должно скрывать
межсервисные зависимости.

## Установка с ключом API

Это обычный вариант автоматизации. Используйте отдельный ключ провайдера с контролем расходов.

```sh
cp production.env.example .env.production
openssl rand -hex 32
openssl rand -hex 32
chmod 600 .env.production
```

Два случайных значения задайте в `.env.production` как `POSTGRES_PASSWORD` и
`DECONFLICTOR_API_TOKEN`. Они должны различаться. Не сохраняйте их в истории команд,
репозитории, заявках или снимках экрана. Заполните:

```dotenv
DECONFLICTOR_LLM_ADAPTER=api
DECONFLICTOR_AGENT_MODEL=openai:MODEL_ID
DECONFLICTOR_AGENT_EFFORT=medium
DECONFLICTOR_EXPLAIN_LANGUAGE=ru
DECONFLICTOR_MODE=advisory
OPENAI_API_KEY=
```

Вместо `MODEL_ID` укажите доступную вашему API-аккаунту модель со структурированными ответами,
а в `OPENAI_API_KEY` — ключ. Название модели API не обязано совпадать с названием в подписке.
Для совместимого шлюза задайте `DECONFLICTOR_API_OPENAI_BASE_URL`; сначала проверьте поддержку
JSON-схем и выбранного effort. Другие модели по ролям задаются через
`DECONFLICTOR_INTAKE_MODEL`, `DECONFLICTOR_JUDGE_MODEL`, `DECONFLICTOR_CHALLENGER_MODEL`,
`DECONFLICTOR_CHAIR_MODEL` и соответствующие переменные `*_EFFORT`.

```sh
docker compose --env-file .env.production -f compose.production.yaml up --build -d --wait
```

Сервис `setup` применяет миграции и импортирует каталог, затем запускается `app`.
PostgreSQL хранится в томе `pgdata` и не публикует порт. Приложение доступно с хоста по
`http://127.0.0.1:8000`; `DECONFLICTOR_PORT` меняет этот порт.

## Установка с подпиской Codex

Этот вариант использует выделенную организацией учётную запись подписки. Её квота общая
с другими сеансами аккаунта; доступность модели и условия подписки проверяет администратор.
Ключ API не требуется. В `.env.production` задайте:

```dotenv
DECONFLICTOR_LLM_ADAPTER=codex_cli
DECONFLICTOR_AGENT_MODEL=gpt-6-astra
DECONFLICTOR_AGENT_EFFORT=medium
OPENAI_API_KEY=
```

Названия моделей Codex пишутся без префикса `openai:`. Во всех командах этого варианта
добавляйте `-f compose.codex.yaml` после `-f compose.production.yaml`:

```sh
docker compose --env-file .env.production -f compose.production.yaml -f compose.codex.yaml build app codex-auth
docker compose --env-file .env.production -f compose.production.yaml -f compose.codex.yaml run --rm --no-deps codex-auth
docker compose --env-file .env.production -f compose.production.yaml -f compose.codex.yaml up --build -d --wait
```

Команда входа показывает адрес и одноразовый код: подтвердите вход в браузере разрешённой
учётной записью. Вход по коду устройства должен быть разрешён в настройках аккаунта.
Не передавайте код в журналы общего доступа. Состояние входа хранится в отдельном томе
`codex-home`, доступном процессу UID 10001 для обновления сессии. Это секрет, не обычный кэш.
Приложение запускает закреплённую версию CLI внутри своего контейнера, без Docker socket,
с отключёнными инструментами и пользовательской конфигурацией. Переключения на API при
ошибке входа нет.

```sh
docker compose --env-file .env.production -f compose.production.yaml -f compose.codex.yaml run --rm --no-deps codex-auth python -m deconflictor.api.codex status
```

Для повторного входа остановите только `app`, выполните команду входа и снова запустите
`up -d --wait`. Для выхода после остановки приложения замените `status` на `logout`.
Статус входа проверяется локально; истёкшая серверная сессия может обнаружиться только
при запросе модели. [Документация OpenAI по авторизации](https://developers.openai.com/codex/auth).

Подробный [контракт настройки моделей](company-models.md) описывает версии CLI, окружение
процесса и хранение входа.

## HTTPS, доступ и первая проверка

Перед приложением нужен корпоративный обратный прокси с HTTPS. Веб-интерфейс и `/api`
обслуживаются с одного адреса. Для событий SSE отключите буферизацию и разрешите долгие
соединения. Запускайте один экземпляр приложения: очередь и уведомления координируются
внутри процесса. `DECONFLICTOR_FORWARDED_ALLOW_IPS` должен перечислять только доверенные
адреса прокси; по умолчанию эти заголовки игнорируются.

В браузере откройте адрес установки и введите API-токен. В Swagger нажмите `Authorize` и
введите только токен, без слова `Bearer`. Справочник загружает все ресурсы локально,
не использует внешнюю проверку схем и не сохраняет этот токен после обновления страницы.
Прототип использует один общий токен: персональных ролей, SSO и изоляции арендаторов внутри
установки нет. Корпоративные ограничения доступа настройте на прокси.

Проверьте `GET /api/info`: `llm.answers` должно быть `live`, `llm.adapter` — `api` или
`codex_cli`, а `graph_version` — ненулевым. Затем отправьте одну безопасную заявку команды
и дождитесь решения с обоснованием. Это реальный расход API или квоты подписки.
Успешный запуск проверяет настройки и БД, но не баланс и доступность провайдера.

## Интеграция CI/CD и тикетов

Для повторяемой доставки используйте `POST /api/integrations/changes` с заголовками
`Authorization: Bearer <token>` и `Content-Type: application/json`. Это нормализованный
входящий вебхук: ваша автоматизация переводит поля исходного CI или тикета в эту схему.
Сырые события конкретного вендора и его подпись этим маршрутом не интерпретируются.

```json
{
  "source": "ci-checkout",
  "external_id": "checkout/deploy/8142",
  "change": {
    "title": "Обновление checkout",
    "body": "Поэтапно обновляем checkout; запись остаётся доступной.",
    "kind": "deploy",
    "author": "team-checkout",
    "environment": "prod",
    "window": {"start": "2026-10-14T08:00:00Z", "end": "2026-10-14T08:30:00Z"},
    "declared_surfaces": ["component:default/checkout"],
    "links": ["https://issues.example.org/releases/8142"]
  }
}
```

Замените дату и имя сервиса. Все даты требуют часового пояса; окно включает начало и
не включает конец. `source` — постоянное имя интеграции, `external_id` — неизменная
ревизия выпуска или тикета, а не номер попытки доставки. Повтор того же содержимого
с той же парой ключей возвращает `200` и тот же UUID; первый приём — `202`. Другое
содержимое с тем же ключом даёт `409 external_identity_conflict`. Для нового плана нужна
новая ревизия, старую отмените. После таймаута повторите то же тело либо найдите заявку
через `GET /api/integrations/changes?source=ci-checkout&external_id=checkout/deploy/8142`.

Ответ подтверждает сохранение. Для автоматического разрешения выпуска интеграция должна
заново прочитать карточку по `card` и проверить все условия:

- `status=active` и `evaluation.state=done`.
- `record` и `outcome` существуют; `record.id=outcome.record_id` и `record.content_version=content_version`.
- `record.final_verdict=outcome.final_verdict=approve`.
- `record.chair.status` — `ok` или `carried`. `not_asked` и `skipped_standard` допустимы только по явной политике компании.
- Нет действующего `override`: ручное несогласие требует отдельного процесса согласования компании и не меняет вердикт сервиса.

При `pending` дождитесь объяснения и прочитайте карточку повторно: председатель может
ужесточить разрешение до эскалации. `failed`, неизвестный статус Chair, `reject`, `escalate`,
ошибка оценки, таймаут и неполный ответ не разрешают автоматический выпуск. Ограничьте время
ожидания; ошибки передавайте человеку. Повтор webhook восстанавливает только отсутствующую
первоначальную оценку, а не повторяет ожидающий или неудачный Chair.

Повторно прочитайте карточку непосредственно перед выпуском: другие заявки или действия
могут изменить решение. Чтение API не блокирует календарь и не выдаёт атомарного разрешения
на внешний запуск; сервис сам не развёртывает изменения. Полные правила доставки и
[примеры интеграций](incoming-webhooks.md) хранятся вместе с кодом.

Обычный `POST /api/changes` также доступен: UUID можно передать самим, но повтор UUID
возвращает конфликт. Изменения принимаются через веб-форму, без внешней интеграции.
После отмены или исполнения отправьте `PATCH /api/changes/{id}/status` со значением
`withdrawn` или `executed`; связанные решения пересчитаются. Deconflictor не выполняет
само развёртывание. Человеческое переопределение с причиной хранит несогласие в истории,
но не меняет решение кода. Перенос окна принимает только предложение из актуальной карточки.

События доступны по `events` и `/api/events`. Для продолжения передайте `Last-Event-ID`
с последним полученным `seq`. Браузерный `EventSource` допускает параметр `access_token`;
уберите этот параметр из журналов прокси. Для других клиентов используйте заголовок.
Исходящие уведомления отдельно настраиваются через `DECONFLICTOR_NOTIFY_WEBHOOK_URL`;
это не адрес приёма входящих заявок.

## Безопасность и хранение

Тексты заявок, сведения о сервисах и цитаты передаются выбранной модели. Согласуйте
разрешённые данные, условия провайдера и сроки хранения до подключения внутренних проектов.
Запросы и обоснования остаются в PostgreSQL; автоматической политики удаления сейчас нет.
Не передавайте в описаниях пароли, ключи и персональные данные без необходимости.

Ограничьте сеть БД, доступ к хосту, исходящие адреса модели и право чтения `.env.production`.
Шифруйте диски и резервные копии средствами инфраструктуры. Приложение работает без root,
с кодом только для чтения. Проверьте журналы прокси на токены в URL. При утечке общего
API-токена замените его в конфигурации, пересоздайте `app` и обновите доверенные клиенты.
Для Codex отдельно отзовите вход и войдите снова; не копируйте `codex-home` в обычные архивы.

## Резервные копии и восстановление

Сохраняйте дамп БД, точную версию приложения, каталог и политику. Секреты храните отдельно.
Для Codex добавляйте второй Compose-файл во все команды, как выше.

```sh
docker compose --env-file .env.production -f compose.production.yaml exec -T db pg_dump -U deconflictor -d deconflictor -Fc > backup.dump
```

Проверяйте восстановление в отдельной установке той же версии с новым пустым томом БД:
поднимите только `db`, дождитесь его готовности, затем импортируйте дамп. Не запускайте
`setup` до восстановления, иначе новая БД уже будет содержать таблицы. В отдельной копии
исходников задайте `DECONFLICTOR_PORT=8001` и `DECONFLICTOR_API_RESUME=0` в своём
`.env.production`, чтобы не занять рабочий порт и не оценивать восстановленные заявки
автоматически. Отдельное имя проекта Compose ниже изолирует тома. Для Codex выполните
новый вход в этом проекте до запуска приложения.

```sh
docker compose -p deconflictor-restore --env-file .env.production -f compose.production.yaml up -d --wait db
docker compose -p deconflictor-restore --env-file .env.production -f compose.production.yaml exec -T db pg_restore --exit-on-error --no-owner -U deconflictor -d deconflictor < backup.dump
docker compose -p deconflictor-restore --env-file .env.production -f compose.production.yaml up -d --wait
```

Сверьте граф, количество заявок, историю и одну карточку. Для подписки выполните новый вход
в отдельной установке. Не используйте `down -v` для штатной остановки: это удаляет данные.

## Обновление и изменение каталога

Сначала сохраните резервную копию и версии конфигурации. Остановите `app`, получите
проверенную версию исходников/образа и пересоздайте `setup` для миграций перед запуском:

```sh
docker compose --env-file .env.production -f compose.production.yaml stop app
docker compose --env-file .env.production -f compose.production.yaml build
docker compose --env-file .env.production -f compose.production.yaml up --force-recreate --no-deps --exit-code-from setup setup
docker compose --env-file .env.production -f compose.production.yaml up -d --wait
```

При ошибке миграции не запускайте новую версию приложения. Откат кода не откатывает схему:
восстанавливайте проверенный дамп в отдельную БД вместе с прежней версией приложения.
После успешного обновления проверьте `/api/info`, журнал `setup` и тестовую заявку.

Для обновления каталога замените файл и выполните импорт без вызова модели:

```sh
docker compose --env-file .env.production -f compose.production.yaml run --rm --no-deps setup deconflictor graph import /config/catalog-info.yaml
```

После изменения политики пересоздайте `app`. Старые Decision Record сохраняют прежнюю
версию графа, политики и сведения о моделях; история не переписывается.

## Поиск неисправностей

```sh
docker compose --env-file .env.production -f compose.production.yaml ps
docker compose --env-file .env.production -f compose.production.yaml logs --tail=100 app setup
```

- `401`: проверьте токен приложения и клиента; в Swagger вводится только значение токена.
- `403`: приложение запущено без токена и запрещает внешние запросы; не обходите эту проверку заголовками.
- `409`: прочитайте код ошибки; повтор вебхука с другим телом требует новой ревизии, устаревшая карточка — повторного чтения.
- `422`: ответ содержит все нарушения с полями; проверьте часовой пояс, окно и канонические имена поверхностей.
- `503`: проверьте готовность БД, миграции и конфигурацию сервиса.
- Оценка `failed`: найдите причину в карточке и журнале; исправьте ключ, вход или лимит модели. Перезапуск по умолчанию восстанавливает незавершённые оценки.
- Нет событий: проверьте буферизацию и таймаут прокси, токен, последний `seq`; повторное подключение продолжает поток.
- Неизвестный сервис: проверьте `/api/surfaces` и импорт каталога; имя в заявке должно совпадать с каноническим ref или его алиасом.

Для поддержки подготовьте версию приложения, время ошибки с часовым поясом, UUID заявки,
код ошибки и очищенный фрагмент журнала. Не прикладывайте `.env.production`, содержимое
тома входа, дамп с внутренними заявками или токены.
