iac/apps/cde/ENDPOINTS.md

Эндпоинты внешних сервисов, с которыми взаимодействует 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 = <базовый адрес> + путь.