# Эндпоинты внешних сервисов, с которыми взаимодействует cde-orchestration-demo

Документ описывает все HTTP/AMQP/gRPC-эндпоинты внешних сервисов, к которым обращается оркестратор (сервер `cmd/http` и воркеры). Это исходящие вызовы; описание API, который оркестратор **предоставляет**, — в `openapi.yaml`.

## Как устроено взаимодействие

Клиенты внешних сервисов лежат в `internal/adapters/http/*` и `internal/adapters/*`. Базовые URL берутся из переменных окружения (см. `CONFIGURATION.md`). Для HTTP используются два клиента: Fiber `client` (camunda, flows, pdm, workspaces, system_log) и `go-resty` (workflows, sarexbackend). Аутентификация — по-разному в зависимости от сервиса (OAuth client_credentials, Bearer-токен пользователя/админа, Basic).

## Базовые адреса по сервисам

| Сервис | Переменная базового адреса | Клиент | Назначение |
| --- | --- | --- | --- |
| Camunda Operate / REST | `OPERATE_URL` | Fiber | Управление инстансами процессов, переменными, сообщениями |
| Camunda Keycloak | `CAMUNDA_KEYCLOAK_URL` | Fiber | OAuth-токен для Operate |
| Zeebe Gateway | `ZEEBE_GATEWAY` | gRPC (SDK) | Деплой BPMN, обработка job'ов воркерами |
| Auth (токены) | `AUTH_HOST` | Fiber/resty | Токены пользователя/админа для flows и pdm |
| Flows | `FLOWS_URL`, `FLOWS_INTERNAL_URL` | Fiber | Ревью, действия пользователя, обновление бандлов/документов |
| PDM | `PDM_URL` | Fiber | Маркировка бандлов *(клиент не подключён — см. примечание)* |
| Workflows | `WORKFLOWS_HOST` | resty | Создание workflow обработки PDF |
| Workspaces | `WORKSPACES_URL` | Fiber | Создание рабочих областей |
| System log | `SYSTEM_LOG_URL` | Fiber | Отправка системных логов |
| Sarex backend | `SAREX_BACKEND_BASE_URL` | resty | Получение MRPA по id |
| Telegram Bot API | `TELEGRAM_TOKEN` | tgbotapi | Алертинг воркеров |
| RabbitMQ (AMQP) | `AMQP_*` | amqp091 | Маркировка бандлов (RPC), вычисление хеш-сумм |

## Эндпоинты по сервисам

### Camunda Operate / REST (`OPERATE_URL`, `CAMUNDA_KEYCLOAK_URL`)

`internal/adapters/http/camunda/client.go`. Все запросы (кроме получения токена) идут с заголовком `Authorization: Bearer <access_token>`.

| Метод | Путь | Назначение |
| --- | --- | --- |
| POST | `{CAMUNDA_KEYCLOAK_URL}/auth/realms/camunda-platform/protocol/openid-connect/token` | OAuth-токен (`grant_type=client_credentials`) |
| POST | `{OPERATE_URL}/v2/process-instances` | Создать инстанс процесса |
| GET | `{OPERATE_URL}/api/process-instances/{key}` | Получить инстанс процесса |
| POST | `{OPERATE_URL}/v1/variables/search` | Поиск переменных процесса по имени/значению |
| GET | `{OPERATE_URL}/api/process-instances/{key}/variables/{varId}` | Значение конкретной переменной |
| POST | `{OPERATE_URL}/api/process-instances/{key}/variables` | Список переменных инстанса (`scopeId`) |
| POST | `{OPERATE_URL}/v2/messages/publication` | Публикация сообщения процессу (напр. `signRequest`) |

### Zeebe Gateway (`ZEEBE_GATEWAY`)

`internal/adapters/zeebe`. gRPC через официальный SDK `camunda/zeebe/clients/go/v8`. Используется для деплоя определений процессов (`NewProcessDefinition`) и для job-воркеров, которые слушают Service Task типа `ZEEBE_WORKER_JOB_TYPE` и по завершении/ошибке возвращают результат в инстанс процесса.

### Auth — токены (`AUTH_HOST`)

Используется адаптерами flows и pdm для получения Bearer-токенов.

| Метод | Путь | Назначение |
| --- | --- | --- |
| GET | `{AUTH_HOST}/token/user/{userID}/` | Токен от имени пользователя |
| POST | `{AUTH_HOST}/token/` | Токен админа (`username`/`password`) |

### Flows (`FLOWS_URL`, `FLOWS_INTERNAL_URL`)

`internal/adapters/http/flows/adapter.go`. Запросы (кроме `update-documents`) идут с `Authorization: Bearer <token>`; часть операций — с ретраями (экспоненциальный backoff).

| Метод | Путь | Назначение |
| --- | --- | --- |
| POST | `{FLOWS_URL}/user-actions/` | Добавить действие в историю |
| PATCH | `{FLOWS_URL}/reviews/{reviewID}/approve/` | Утвердить review (со статусом/комментарием) |
| PATCH | `{FLOWS_URL}/reviews/{reviewID}/update-bundles/` | Обновить бандлы review |
| PATCH | `{FLOWS_INTERNAL_URL}/reviews/{reviewID}/update-documents/` | Обновить документы review (внутренний URL, без авторизации) |
| GET | `{FLOWS_URL}/reviews/{reviewID}/documents/` | История бандлов документов review |

### PDM (`PDM_URL`, `AUTH_HOST`) — не подключён

`internal/adapters/http/pdm/client.go`. Клиент реализован, но в текущей сборке нигде не инициализируется (см. примечание в конце). Для полноты — какие вызовы он делает:

| Метод | Путь | Назначение |
| --- | --- | --- |
| GET | `{AUTH_HOST}/token/user/{userID}/` | Токен пользователя (Basic auth логин/пароль) |
| PUT | `{PDM_URL}/bundles/{bundleID}/marks` | Проставить маркировки бандлу |

### Workflows (`WORKFLOWS_HOST`, `AUTH_HOST`)

`internal/adapters/http/workflows/adapter.go` (resty). Используется воркером `split_pdf`.

| Метод | Путь | Назначение |
| --- | --- | --- |
| POST | `{WORKFLOWS_HOST}/internal/v1/companies/{companyID}/workflows` | Создать workflow обработки/оптимизации PDF |

> Базовый URL resty-клиента установлен в `AUTH_HOST`, а адрес workflows подставляется полным (`WORKFLOWS_HOST`). В параметрах задач передаётся `django_host = AUTH_HOST`.

### Workspaces (`WORKSPACES_URL`)

`internal/adapters/http/workspaces/client.go`. Используется воркерами `copy`/`copyv2`.

| Метод | Путь | Назначение |
| --- | --- | --- |
| POST | `{WORKSPACES_URL}/internal/v2/workspaces` | Создать рабочую область |

### System log (`SYSTEM_LOG_URL`)

`internal/adapters/http/system_log/client.go`. Используется воркерами `copy`, `copyv2`, `create_versions`, `create_versionsv2`.

| Метод | Путь | Назначение |
| --- | --- | --- |
| POST | `{SYSTEM_LOG_URL}/api/v0/system_log` | Отправить пакет системных логов |

### Sarex backend (`SAREX_BACKEND_BASE_URL`)

`internal/adapters/sarexbackend/client.go` (resty). Используется HTTP-сервером при подписи (проверка MRPA). Токены проксируются из входящего запроса (`Authorization`, опц. `Identity`).

| Метод | Путь | Назначение |
| --- | --- | --- |
| GET | `{SAREX_BACKEND_BASE_URL}/api/core/mrpa/{id}/` | Получить MRPA по id |

### Telegram Bot API (`TELEGRAM_TOKEN`, `TELEGRAM_ALERT_GROUP_ID`)

`internal/adapters/http/telegram/client.go` через `go-telegram-bot-api`. Отправка алертов в заданную группу при ошибках/паниках в задачах воркеров.

### RabbitMQ / AMQP (`AMQP_*`)

Подключение вида `amqp://{USER}:{PASSWORD}@{HOST}:{PORT}/{PATH_API}`.

| Адаптер | Назначение |
| --- | --- |
| `internal/adapters/amqp/markings` | Маркировка бандла и получение его хеш-суммы (RPC поверх временной очереди, `correlation_id`). Используется воркерами `markingsv2`/`copyv2` |
| `internal/adapters/amqp/rpc` | Общий RPC-клиент RabbitMQ (переподключение, вычисление хеш-сумм объектов) |

## Обработка ошибок

Каждый адаптер проверяет `StatusCode()` ответа и оборачивает не-`200 OK` в ошибку с телом ответа (`internal/errors`). Отдельно у sarexbackend маппинг: `404 → ErrNotFound`, `403 → ErrForbidden`, прочие → generic. Адаптеры flows и pdm выполняют ретраи с экспоненциальным backoff (до 5 попыток).

## Примечания

- **PDM-клиент не подключён.** `internal/adapters/http/pdm` реализован, а переменная `PDM_URL` присутствует в Helm-секрете, но `pdm.New(...)` не вызывается ни в одном бинарнике. Раздел оставлен для полноты; при фактическом использовании актуализируйте документ.
- Пути даны относительно базовых URL из окружения; итоговый URL = `<базовый адрес>` + `путь`.