186 lines
17 KiB
Markdown
186 lines
17 KiB
Markdown
# Эндпоинты, с которыми взаимодействует transmittal-frontend
|
||
|
||
Документ описывает все HTTP-эндпоинты внешних сервисов, к которым обращается модуль (микрофронтенд `transmittal-frontend`).
|
||
|
||
## Как устроено взаимодействие
|
||
|
||
Все запросы описаны декларативно в реестре `module/api/endpoints.ts` (объект `endpoints`). Каждый эндпоинт задаётся структурой `Endpoint`:
|
||
|
||
- `service` — логическое имя сервиса (см. таблицу хостов ниже);
|
||
- `method` — HTTP-метод (`GET`/`POST`/`PUT`/`PATCH`/`DELETE`);
|
||
- `path(args)` — функция, возвращающая путь запроса (с подстановкой параметров/query);
|
||
- `body(args)` — опционально, формирование тела запроса;
|
||
- `cache`, `queryOptions`, `responseType`, `axiosConfig` — опции кеширования, повторов и типа ответа.
|
||
|
||
Запрос выполняется единой функцией `fetch(endpoint, params, controller)`, которая через `httpService` (`module/api/http-service.ts`, поверх `@sarex-team/sdk-js` + `axios`) отправляет запрос на базовый хост сервиса. Базовый хост подставляется `resolveHost(service)` из `module/api/hosts.ts` в зависимости от `BUILD_ENV`. Ошибки маппируются в человекочитаемые сообщения в `module/api/errors.ts`.
|
||
|
||
## Базовые хосты по сервисам и окружениям
|
||
|
||
Значения из `module/api/hosts.ts`. Итоговый URL = `<базовый хост сервиса>` + `path` эндпоинта.
|
||
|
||
| Сервис (`service`) | Назначение | `stage` | `prod` |
|
||
| --- | --- | --- | --- |
|
||
| `transmittals` | Сервис передачи документации (трансмитталы, шаблоны) | `https://stage-api.sarex.io/transmittals` | `https://api.sarex.io/transmittals` |
|
||
| `documentations` | Сервис документации (документы, бандлы, файлы) | `https://stage-api.sarex.io/documentations` | `https://api.sarex.io/documentations` |
|
||
| `sarexApi` | Gateway/API Sarex (`/gateway`, `/eav`, `/cde`) | `https://stage-api.sarex.io` | `https://api.sarex.io` |
|
||
| `sarex` | Локальный сервис данных (`/api/core`, `/api/client`) | `""` (относительные пути) | `""` |
|
||
| `processes` | Сервис рабочих процессов (flows, reviews) | `https://stage-api.sarex.io/flows` | `https://api.sarex.io/flows` |
|
||
| `workflows` | Сервис обработки документов | `https://stage-api.sarex.io/workflows` | `https://api.sarex.io/workflows` |
|
||
| `workspaces` | Сервис рабочих областей | `https://stage-api.sarex.io/workspaces` | `https://api.sarex.io/workspaces` |
|
||
| `remarks` | Сервис замечаний | `https://stage-api.sarex.io/remarks` | `https://api.sarex.io/remarks` |
|
||
| `files` | Сервис файлов | `https://stage-api.sarex.io/files` | `https://api.sarex.io/files` |
|
||
| `google` | Временное хранилище (GCS) | `https://storage.googleapis.com/srx-tmp` | `https://storage.googleapis.com/srx-tmp` |
|
||
| `bim` | BIM-API | `https://stage-bim-api.sarex.io` | `https://bim-api.sarex.io` |
|
||
| `zitadel` | IdP (аутентификация) | `https://idp.dev.stage.sarex.io` | `https://login.sarex.io` |
|
||
|
||
> Также определены окружения `local`, `preprod` и `contour` (относительные пути для изолированного контура). В `local` сервис `sarex` проксируется на `/sarex-backend`. Подключаемый удалённый модуль documentations описан отдельно в `module/api/module-hosts.ts`.
|
||
|
||
## Эндпоинты по сервисам
|
||
|
||
### `transmittals` — Сервис передачи документации
|
||
|
||
| Ключ | Метод | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `getTransmittals` | POST | `api/v1/transmittals` | Список трансмитталов (пагинация по `bookmark`, фильтр по `resource_id`) |
|
||
| `getTransmittalStatuses` | POST | `api/v1/transmittals/global_statuses` | Глобальные статусы по набору `resource_ids` |
|
||
| `getTransmittalById` | GET | `api/v1/transmittals/{transmittalId}` | Трансмиттал по id |
|
||
| `getAct` | GET | `api/v1/transmittals/{transmittalId}/act_available` | Доступность акта для трансмиттала |
|
||
| `downloadAct` | GET | `api/v1/transmittals/{transmittalId}/download_act` | Скачивание акта |
|
||
| `createTransmittal` | POST | `api/v1/transmittals/create` | Создание трансмиттала |
|
||
| `approveTransmittal` | PUT | `api/v1/transmittals/{transmittalId}/approve` | Принять трансмиттал (с комментарием) |
|
||
| `declineTransmittal` | PUT | `api/v1/transmittals/{transmittalId}/decline` | Отклонить трансмиттал (с комментарием) |
|
||
| `deleteTransmittal` | DELETE | `api/v1/transmittals/{transmittalId}` | Удалить трансмиттал |
|
||
| `linkReviewToTransmittal` | POST | `api/v1/transmittals/{transmittalId}/link_review` | Привязать review к трансмитталу |
|
||
| `getStatusTypes` | GET | `api/v1/transmittals/status` | Справочник типов статусов |
|
||
| `getSearchProject` | POST | `api/v1/transmittals/search` | Поиск/фильтрация трансмитталов в проекте |
|
||
| `getSearchProjects` | POST | `api/v1/transmittals/search/resources` | Поиск/фильтрация по нескольким ресурсам |
|
||
| `getSteps` | GET | `api/v1/steps` | Список шагов |
|
||
| `getStep` | GET | `api/v1/steps/{id}` | Шаг по id |
|
||
| `getSearchTemplates` | POST | `/api/v1/transmittal_templates` | Поиск шаблонов трансмитталов |
|
||
| `createTemplate` | POST | `/api/v1/transmittal_templates/create` | Создать шаблон |
|
||
| `updateTemplate` | PATCH | `/api/v1/transmittal_templates/{templateId}` | Обновить шаблон |
|
||
| `deleteTemplate` | DELETE | `/api/v1/transmittal_templates/{templateId}` | Удалить шаблон |
|
||
| `getTemplateListForSelect` | GET | `/api/v1/transmittal_templates/select?resource={resourceId}` | Список шаблонов для выбора |
|
||
| `getSingleTemplate` | GET | `/api/v1/transmittal_templates/{templateId}?resource={resourceId}` | Шаблон по id |
|
||
|
||
### `documentations` — Сервис документации
|
||
|
||
| Ключ | Метод | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `getDisks` | GET | `api/v1/disks` | Список дисков |
|
||
| `getAllPermmission` | GET | `api/v1/permissions` | Все права доступа |
|
||
| `getDocPermission` | GET | `api/v1/documents/{id}/permissions` | Права доступа документа |
|
||
| `postPermission` | POST | `api/v1/documents/{id}/permissions` | Выдать права сервисному аккаунту |
|
||
| `postBundle` | POST | `api/v1/bundles` | Создать бандл |
|
||
| `postFile` | POST | `api/v1/bundles/{bundleId}/{fileKey}?single_upload=1` | Загрузить файл (single upload) |
|
||
| `uploadFolderStart` | POST | `api/v1/bundles/{bundleId}/{key}/upload_multipart?upload_path={folderPath}` | Начать multipart-загрузку |
|
||
| `uploadPart` | PUT | `api/v1/bundles/{bundleId}/{bundleKey}?part_number={partNumber}` | Загрузить часть файла |
|
||
| `bundleComplite` | POST | `api/v1/bundles/{bundleId}/upload_finish` | Завершить загрузку бандла |
|
||
| `getFile` | GET | `api/v1/bundles/{bundleId}/{bundleKey}` | Получить файл бандла |
|
||
| `getBundles` | GET | `api/v1/documents/{id}/bundles` | Бандлы документа |
|
||
| `addBundle` | POST | `api/v1/documents/{documentId}/add_bundle` | Привязать бандл к документу |
|
||
| `moveBundles` | PATCH | `api/v1/documents/{documentId}/move_bundles` | Переместить бандлы |
|
||
| `removeBundle` | DELETE | `api/v1/bundles/{id}` | Удалить бандл |
|
||
| `postWorkspace` | POST | `api/v1/workspaces` | Создать рабочую область |
|
||
| `getDocumentById` | GET | `api/v1/documents/{id}` | Документ по id |
|
||
| `getDocumentWithBundles` | GET | `api/v1/documents/{id}?extend=bundles` | Документ с бандлами |
|
||
| `fetchBatchDocuments` | POST | `/api/v1/documents/batch` | Пакетное получение документов |
|
||
| `changeDocument` | PATCH | `api/v1/documents/{id}` | Переименовать документ |
|
||
| `updatePath` | PATCH | `api/v1/documents/{id}/update-path` | Сменить родителя документа |
|
||
| `updateDocumentsPaths` | PATCH | `api/v1/documents/update-path` | Массовая смена родителя |
|
||
| `deleteDocument` | DELETE | `api/v1/documents/{id}` | Удалить документ |
|
||
| `deleteDocuments` | DELETE | `api/v1/documents?document_ids={ids}` | Удалить несколько документов |
|
||
| `downloadFile` | GET | `api/v1/bundles/{lastBundleId}/{key}/download` | Скачать файл |
|
||
| `downloadAllFiles` | GET | `api/v1/bundles/{lastBundleId}/download` | Скачать все файлы бандла |
|
||
| `downloadFolder` | GET | `api/v1/documents/{docId}/download?depth={depth}` | Скачать папку |
|
||
| `getFolderChildrenWithActiveProcesses` | POST | `/api/v1/documents/flows` | Дети папки с активными процессами |
|
||
| `conversionFile` | POST | `api/v1/conversion` | Конвертация документа (в IFC) |
|
||
| `addMarks` | PUT | `api/v1/bundles/{bundleId}/marks` | Добавить штампы/QR/подписи |
|
||
| `sign` | POST | `api/v1/bundles/{bundleId}/sign` | Подписать бандл |
|
||
| `cancelQrCode` | PATCH | `api/v1/bundles/{bundleId}/cancel_qr` | Отменить QR-код |
|
||
| `restartWorkflow` | POST | `api/v1/bundles/{bundleId}/restart` | Перезапустить workflow бандла |
|
||
| `getPublicLink` | GET | `api/v1/public/documents/public_link/{public_link_id}` | Получить публичную ссылку |
|
||
| `deletePublicLink` | DELETE | `api/v1/documents/public_link/{public_link_id}` | Удалить публичную ссылку |
|
||
| `removeDoc` | DELETE | `api/v1/documents/bin?parent_id={id}` | Переместить в корзину |
|
||
| `recoveryDocument` | PATCH | `api/v1/documents/bin/restore?parent_id={id}` | Восстановить из корзины |
|
||
| `copyFolderStructure` | POST | `api/v1/documents/copy_structure` | Копировать структуру папок |
|
||
|
||
### `sarexApi` — Gateway/API Sarex
|
||
|
||
| Ключ | Метод | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `getUsersWithTransmittalProjectPermissions` | GET | `/gateway/api/v2/users/?...&resource_id={projectId}&permissions=...` | Пользователи с правами в проекте |
|
||
| `getDocuments` | GET | `/gateway/api/v1/disks/{id}/documents?...` | Документы диска (с фильтрами/поиском) |
|
||
| `filterByAttributes` | GET | `/gateway/api/v1/disks/{diskId}/documents?parent_id={rootDocumentId}&{params}` | Фильтрация документов по атрибутам |
|
||
| `getResources` | GET | `/gateway/api/v1/resources` | Список ресурсов |
|
||
| `createDocument` | POST | `/gateway/api/v1/documents` | Создать документ/папку/проект |
|
||
| `fetchDocumentAncestors` | POST | `/gateway/api/v1/documents/ancestors` | Предки документов |
|
||
| `fetchDocumentsBundleVersions` | POST | `/gateway/api/v1/documents/bundle_versions` | Версии бандлов документов |
|
||
| `getAttributesByDocumet` | GET | `/gateway/api/v1/documents/{id}/attributes` | Атрибуты документа |
|
||
| `updateAttributes` | PUT | `/gateway/api/v1/documents/{id}/attributes` | Обновить атрибуты документа |
|
||
| `addAttributes` | POST | `/gateway/eav/api/v0/entity/` | Создать сущность атрибутов (EAV) |
|
||
| `getDefaultAttributes` | GET | `/eav/api/v0/schema/?model=document&company_id=...&type_identifier=...` | Схема атрибутов по типу |
|
||
| `getAttributes` | GET | `/eav/api/v0/attribute/?company_id={params}` | Атрибуты компании |
|
||
| `getAttributesWithParams` | GET | `/eav/api/v0/schema/?model=document&{params}` | Схема атрибутов с параметрами |
|
||
| `updateSubscription` | POST | `/gateway/api/v1/subscription/` | Создать/обновить подписку |
|
||
| `deleteSubscription` | DELETE | `/gateway/api/v1/documents/{documentId}/subscription/` | Удалить подписку |
|
||
| `getActivityLog` | GET | `/gateway/api/v1/system_log/?...` | Журнал активности документа |
|
||
| `fetchDocumentByResourceId` | GET | `/gateway/api/v1/resources-rpc/parent-document-by-resource-id/{resourceId}/` | Родительский документ по resource id |
|
||
| `getRemovedDocuments` | GET | `/gateway/api/v1/documents/bin?parent_id={id}{params}` | Удалённые документы в папке |
|
||
| `getRemovedFilteredDocuments` | GET | `/gateway/api/v1/documents/bin{params}` | Удалённые документы (фильтр) |
|
||
| `getBindings` | GET | `/cde/app/v1/bundles/{bundleId}/bindings` | Привязки бандла |
|
||
| `completeUpload` | POST | `{uploadUrl}/complete` | Завершение загрузки (по переданному URL) |
|
||
|
||
### `sarex` — Локальный сервис данных
|
||
|
||
| Ключ | Метод | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `getSettings` | GET | `/api/client/settings/` | Клиентские настройки (кешируется) |
|
||
| `getUser` | GET | `/api/core/users/{userId}/` | Пользователь по id |
|
||
| `getUsersByCompanyIds` | GET | `/api/core/users/?company={ids}&limit=&offset=&show_inactive=true` | Пользователи компаний |
|
||
| `getTargets` | GET | `/api/core/targets/` | Список таргетов |
|
||
| `getCompanies` | GET | `/api/core/companies/` | Список компаний |
|
||
| `getDepartmentById` | GET | `/api/core/admin/departments?company={companyId}` | Отделы компании |
|
||
| `getUsersPositionById` | GET | `/api/core/admin/positions/?company={companyId}` | Должности компании |
|
||
| `getByFullUrl` | GET | `{url}` | Запрос по произвольному URL |
|
||
|
||
### `processes` — Сервис рабочих процессов (flows)
|
||
|
||
| Ключ | Метод | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `getProcesses` | GET | `api/v1/flows/?{query}` | Список процессов (flows) |
|
||
| `createReview` | POST | `api/v1/reviews/` | Создать review |
|
||
| `deleteReview` | DELETE | `api/v1/reviews/{id}/` | Удалить review |
|
||
| `activateReview` | PATCH | `api/v1/reviews/{id}/approve/` | Активировать/утвердить review |
|
||
| `createReviewDocuments` | POST | `api/v1/documents/` | Добавить документы в review |
|
||
|
||
### `workflows` — Сервис обработки документов
|
||
|
||
| Ключ | Метод | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `getWorkflow` | GET | `api/v1/workflows/{workflowId}` | Workflow по id |
|
||
| `getWorkflows` | POST | `api/v1/workflows/batch` | Пакетное получение workflow |
|
||
|
||
### `workspaces` — Сервис рабочих областей
|
||
|
||
| Ключ | Метод | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `getWorkspaces` | GET | `api/v1/workspaces/{uuid}` | Рабочая область по uuid |
|
||
|
||
### `remarks` — Сервис замечаний
|
||
|
||
| Ключ | Метод | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `getRemarksTotalCount` | GET | `api/v1/total_count` | Общее число замечаний |
|
||
|
||
### `files` — Сервис файлов
|
||
|
||
| Ключ | Метод | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `downloadFiles` | GET | `/api/v1/documents/{documentIds}` | Скачать документы по id |
|
||
| `downloadFileBundles` | POST | `/api/v1/documents/` | Скачать бандлы (ответ `blob`) |
|
||
|
||
## Обработка ошибок
|
||
|
||
Коды ответов маппируются в сообщения (`module/api/errors.ts`): `400` — некорректный запрос, `404` — ресурс не найден, `500` (и прочие) — ошибка сервера. Для каждого сервиса задано человекочитаемое имя (напр. `transmittals` → «Сервис передачи документации»), которое подставляется в текст ошибки. По умолчанию у запросов включён показ уведомления об ошибке (`showErrorNotification: true`).
|