299 lines
11 KiB
YAML
299 lines
11 KiB
YAML
openapi: 3.0.3
|
||
|
||
info:
|
||
title: CDE Orchestration API
|
||
version: "0.0.0"
|
||
description: |
|
||
HTTP API оркестратора **cde-orchestration-demo**
|
||
(`gitlab.com/sarex-team/cde-orchestration-demo`) — управление процессами
|
||
согласования/подписи документов в Camunda (Zeebe/Operate).
|
||
|
||
Сервис написан на Go (**Fiber v3**), точка входа — `cmd/http/main.go`,
|
||
сборка приложения — `internal/app/http/server.go`. Все ручки объявлены в
|
||
`internal/controller/http/v0` и смонтированы под префиксом `/api`.
|
||
|
||
### Аутентификация
|
||
Все эндпоинты проходят через middleware `pkg/http/middleware/auth.go`.
|
||
Токен передаётся заголовком `Authorization: Bearer <jwt>`. Поддерживаются
|
||
два режима:
|
||
|
||
1. **Sarex** (по умолчанию) — подпись JWT проверяется RSA public key из
|
||
переменной `PUBLIC_KEY`.
|
||
2. **Zitadel** — если передан дополнительный заголовок
|
||
`Identity: Bearer <jwt>`, полезная нагрузка берётся из метаданных
|
||
этого токена (`urn:zitadel:iam:user:metadata`); подпись основным
|
||
сервисом не проверяется.
|
||
|
||
При отсутствии/некорректности заголовков middleware возвращает `401`.
|
||
|
||
### Замечания
|
||
- Ручка `GET /api/process/{instance_key}` может вернуть `425 Too Early`,
|
||
если процесс есть в кеше, но ещё не создан в Camunda (идёт обработка).
|
||
- Тело ответов на запись (`process`, `sign`, `operate`) обычно пустое —
|
||
значим только HTTP-статус.
|
||
|
||
contact:
|
||
name: cde-orchestration-demo
|
||
url: https://gitlab.com/sarex-team/cde-orchestration-demo
|
||
|
||
servers:
|
||
- url: http://localhost:8080/api
|
||
description: Локальный запуск (Fiber, ADDRESS по умолчанию :8080)
|
||
- url: http://cde-svc.cde.svc.cluster.local/api
|
||
description: Внутрикластерный адрес (ClusterIP)
|
||
|
||
tags:
|
||
- name: infra
|
||
description: Служебные эндпоинты
|
||
- name: process
|
||
description: Процессы согласования/подписи
|
||
- name: sign
|
||
description: Отправка подписей в процесс
|
||
- name: operate
|
||
description: Управление определениями процессов (BPMN)
|
||
|
||
security:
|
||
- bearerAuth: []
|
||
|
||
paths:
|
||
/:
|
||
get:
|
||
tags: [infra]
|
||
summary: Проверка доступности
|
||
description: Возвращает 200 OK. Требует валидной авторизации (middleware).
|
||
operationId: root
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
"401":
|
||
description: Не авторизован
|
||
|
||
/process/:
|
||
post:
|
||
tags: [process]
|
||
summary: Запустить процесс
|
||
description: |
|
||
Создаёт инстанс процесса согласования/подписи в Camunda по документам
|
||
из `payload`. Если для `flow_id` уже есть активный инстанс — вернётся
|
||
`400`.
|
||
operationId: createProcess
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ProcessCreateRequest"
|
||
responses:
|
||
"202":
|
||
description: Процесс принят к обработке
|
||
"400":
|
||
description: Ошибка валидации или активный инстанс уже существует
|
||
"401":
|
||
description: Не авторизован
|
||
"500":
|
||
description: Внутренняя ошибка (ошибка создания инстанса в Camunda)
|
||
|
||
/process/{instance_key}:
|
||
get:
|
||
tags: [process]
|
||
summary: Получить состояние процесса
|
||
description: |
|
||
Возвращает текущее состояние процесса по `flow_id` (в пути — числовой
|
||
ключ). Логика: если запись есть в кеше, но нет активного инстанса в
|
||
Camunda — процесс ещё обрабатывается (`425`).
|
||
operationId: getProcess
|
||
parameters:
|
||
- name: instance_key
|
||
in: path
|
||
required: true
|
||
description: Числовой идентификатор (`flow_id`)
|
||
schema:
|
||
type: integer
|
||
format: uint64
|
||
responses:
|
||
"200":
|
||
description: Состояние процесса
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/GetProcessInstanceResponse"
|
||
"401":
|
||
description: Не авторизован
|
||
"404":
|
||
description: Процесс не найден
|
||
"425":
|
||
description: Too Early — процесс ещё обрабатывается
|
||
"500":
|
||
description: Внутренняя ошибка
|
||
|
||
/sign/:
|
||
post:
|
||
tags: [sign]
|
||
summary: Отправить подписи в процесс
|
||
description: |
|
||
Публикует сообщение `signRequest` в процесс Camunda с подписями из
|
||
`payload`. Для элементов с `mrpa_id` предварительно проверяется доступ
|
||
через sarex-backend.
|
||
operationId: sign
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/SignRequest"
|
||
responses:
|
||
"200":
|
||
description: Подписи приняты, сообщение отправлено в процесс
|
||
"401":
|
||
description: Отсутствует токен авторизации
|
||
"403":
|
||
description: Нет прав на MRPA
|
||
"422":
|
||
description: MRPA не найдена
|
||
"500":
|
||
description: Внутренняя ошибка
|
||
|
||
/operate/processes:
|
||
post:
|
||
tags: [operate]
|
||
summary: Загрузить определение процесса (BPMN)
|
||
description: |
|
||
Принимает BPMN-файл (multipart, поле `definition`) и деплоит его в
|
||
Zeebe.
|
||
operationId: deployProcessDefinition
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
multipart/form-data:
|
||
schema:
|
||
type: object
|
||
required: [definition]
|
||
properties:
|
||
definition:
|
||
type: string
|
||
format: binary
|
||
description: BPMN-файл определения процесса
|
||
responses:
|
||
"200":
|
||
description: Определение загружено
|
||
"400":
|
||
description: Файл не передан/некорректен
|
||
"401":
|
||
description: Не авторизован
|
||
"500":
|
||
description: Внутренняя ошибка деплоя
|
||
|
||
components:
|
||
securitySchemes:
|
||
bearerAuth:
|
||
type: http
|
||
scheme: bearer
|
||
bearerFormat: JWT
|
||
description: |
|
||
JWT Sarex (проверяется по `PUBLIC_KEY`). Для режима Zitadel
|
||
дополнительно передаётся заголовок `Identity: Bearer <jwt>`.
|
||
|
||
schemas:
|
||
ProcessCreateRequest:
|
||
type: object
|
||
required: [flow_id, author_id]
|
||
description: Запрос на старт процесса (`internal/dto/http.go`).
|
||
properties:
|
||
flow_id:
|
||
type: integer
|
||
format: uint64
|
||
description: Внешний ID процесса (обязателен, != 0)
|
||
author_id:
|
||
type: integer
|
||
format: uint64
|
||
description: ID автора запроса (обязателен, != 0)
|
||
company_id:
|
||
type: integer
|
||
format: uint64
|
||
step_id:
|
||
type: integer
|
||
format: uint64
|
||
metadata:
|
||
type: object
|
||
additionalProperties: true
|
||
payload:
|
||
type: array
|
||
description: Документы для обработки (произвольные объекты)
|
||
items:
|
||
type: object
|
||
additionalProperties: true
|
||
overwrite_marks:
|
||
type: boolean
|
||
mode:
|
||
type: string
|
||
description: Режим работы ("original", "copy", "both")
|
||
use_signature:
|
||
type: boolean
|
||
create_copy_on_finish:
|
||
type: boolean
|
||
comment:
|
||
type: string
|
||
is_last_signer:
|
||
type: boolean
|
||
|
||
GetProcessInstanceResponse:
|
||
type: object
|
||
description: Состояние инстанса процесса (`internal/dto/http.go`).
|
||
properties:
|
||
status:
|
||
type: string
|
||
use_signature:
|
||
type: boolean
|
||
is_finished:
|
||
type: boolean
|
||
is_ready_for_sign:
|
||
type: boolean
|
||
is_last_signer:
|
||
type: boolean
|
||
create_copy_on_finish:
|
||
type: boolean
|
||
comment:
|
||
type: string
|
||
payload:
|
||
description: Полезная нагрузка процесса (структура зависит от процесса)
|
||
nullable: true
|
||
instance_key:
|
||
type: integer
|
||
format: uint64
|
||
|
||
SignRequest:
|
||
type: object
|
||
required: [flow_id, payload]
|
||
description: Запрос на подпись документов в процессе (`internal/dto/http.go`).
|
||
properties:
|
||
flow_id:
|
||
type: integer
|
||
format: uint64
|
||
metadata:
|
||
type: object
|
||
additionalProperties: true
|
||
payload:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/SignRequestPayloadElem"
|
||
|
||
SignRequestPayloadElem:
|
||
type: object
|
||
properties:
|
||
bundle_id:
|
||
type: string
|
||
format: uuid
|
||
author_id:
|
||
type: integer
|
||
format: uint64
|
||
signature:
|
||
type: string
|
||
description: Сгенерированная подпись (помещается в p7s)
|
||
algorithm:
|
||
type: string
|
||
mrpa_id:
|
||
type: string
|
||
format: uuid
|
||
nullable: true
|
||
description: Если задан — проверяется доступ через sarex-backend
|