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