139 lines
11 KiB
Markdown
139 lines
11 KiB
Markdown
# Эндпоинты, с которыми взаимодействует issues-frontend
|
||
|
||
Документ описывает все HTTP-эндпоинты внешних сервисов, к которым обращается модуль (микрофронтенд `issues-frontend`).
|
||
|
||
## Как устроено взаимодействие
|
||
|
||
Запросы сгруппированы по доменным API-объектам в каталоге `module/api/` (`IssuesApi`, `CoreApi`, `PrescriptionsApi`, `InspectionsApi`, `AttributesApi`, `AssetsApi`, `ContractsApi`, `ResourcesApi`, `TemplatesApi`, `PremisesApi`, `DocumentationApi`). Каждый метод вызывает единый `httpService` (`module/api/http-service.ts`).
|
||
|
||
`httpService` создаётся фабрикой `createHttpService` из `@sarex-team/sdk-js` и принимает карту хостов `hosts` (`module/api/hosts.ts`) и текущее окружение `BUILD_ENV`. Вызов задаётся объектом:
|
||
|
||
- `service` — логическое имя сервиса (ключ из `hosts`, см. таблицу ниже);
|
||
- метод — `getRequest`/`postRequest`/`putRequest`/`patchRequest`/`deleteRequest`;
|
||
- `url` — путь запроса (дописывается к базовому хосту сервиса);
|
||
- `axiosConfig` — доп. настройки axios (`params`, `paramsSerializer`, `responseType` и т.п.);
|
||
- `data` — тело запроса;
|
||
- `showErrorNotification`, `queryKey`, `cache` — опции показа ошибок, ключа кеша и кеширования.
|
||
|
||
Итоговый URL = `<базовый хост сервиса для BUILD_ENV>` + `url`. Базовый хост выбирается по `BUILD_ENV` (`local`/`stage`/`prod`/`preprod`/`contour`).
|
||
|
||
## Базовые хосты по сервисам и окружениям
|
||
|
||
Значения из `module/api/hosts.ts`. Приведены `stage` и `prod`; в `contour` используются относительные пути, в `preprod` — домен `api.preprod.sarex.io`, в `local` — как в `stage`, но `sarex` проксируется на `/sarex-backend`.
|
||
|
||
| Сервис (`service`) | Назначение | `stage` | `prod` |
|
||
| --- | --- | --- | --- |
|
||
| `issues` | Сервис замечаний (issues-backend, собственный API) | `https://stage-api.sarex.io/issues/api` | `https://api.sarex.io/issues/api` |
|
||
| `prescriptions` | Предписания (issues-backend) | `https://stage-api.sarex.io/issues/api/prescriptions` | `https://api.sarex.io/issues/api/prescriptions` |
|
||
| `sarexApi` | Gateway/API Sarex (`/gateway`, `/issues`, `/inspections`, `/contracts`) | `https://stage-api.sarex.io` | `https://api.sarex.io` |
|
||
| `sarex` | Локальный сервис данных (`/api/core`, `/api/client`) | `""` (относительные пути) | `""` |
|
||
| `gateway` | Gateway Sarex | `https://stage-api.sarex.io/gateway` | `https://api.sarex.io/gateway` |
|
||
| `documentations` | Сервис документации | `https://stage-api.sarex.io/documentations/api/v1` | `https://api.sarex.io/documentations/api/v1` |
|
||
| `eav` | Сервис атрибутов/ассетов (EAV) | `https://stage-api.sarex.io/eav/api` | `https://api.sarex.io/eav/api` |
|
||
| `files` | Сервис файлов | `https://stage-api.sarex.io/files/api/v1` | `https://api.sarex.io/files/api/v1` |
|
||
| `premises` | Сервис помещений | `https://stage-api.sarex.io/premises/api/v1` | `https://api.sarex.io/premises/api/v1` |
|
||
| `workspaces` | Сервис рабочих областей | `https://stage-api.sarex.io/workspaces` | `https://api.sarex.io/workspaces` |
|
||
| `workflows` | Сервис обработки документов | `https://stage-api.sarex.io/workflows` | `https://api.sarex.io/workflows` |
|
||
| `comparisons` | Сервис сравнений | `https://stage-api.sarex.io/comparisons` | `https://api.sarex.io/comparisons` |
|
||
| `remarks` | Сервис замечаний (remarks) | `https://stage-api.sarex.io/remarks` | `https://api.sarex.io/remarks` |
|
||
| `bim` / `bimv2` | BIM-API | `https://stage-api.sarex.io/bim` (`/bimv2`) | `https://api.sarex.io/bim` (`/bimv2`) |
|
||
| `google` | Временное хранилище (GCS) | `https://storage.googleapis.com/srx-tmp` | `https://storage.googleapis.com/srx-tmp` |
|
||
| `zitadel` | IdP (аутентификация) | `https://idp.dev.stage.sarex.io` | `https://login.sarex.io` |
|
||
|
||
> Часть сервисов объявлена в карте хостов, но напрямую в `module/api/*` не вызывается (`workspaces`, `workflows`, `comparisons`, `remarks`, `bim`, `bimv2`, `google`, `zitadel`) — они используются инфраструктурой SDK / другими слоями. Сервис `prescriptions` объявлен в хостах, но методы предписаний фактически ходят через `sarexApi` по пути `/issues/api/prescriptions`.
|
||
|
||
Подключаемый удалённый модуль `documentations` описан отдельно в `module/api/module-hosts.ts` (`remoteEntry.js` микрофронтенда documentations).
|
||
|
||
## Эндпоинты по сервисам
|
||
|
||
### `issues` — Сервис замечаний (собственный API)
|
||
|
||
Файл `module/api/issuesApi.ts`.
|
||
|
||
| Метод API | HTTP | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `IssuesApi.getStatusModels` | GET | `/companies/{companyId}/status-model/` | Модель статусов компании (по `resource_id`, `issue_type_id`) |
|
||
| `IssuesApi.getTypes` | GET | `/issue-types/` | Типы замечаний компании (`company_id`) |
|
||
| `IssuesApi.getIssue` | GET | `/issues/{public_id}/` | Замечание по публичному id |
|
||
| `IssuesApi.editIssue` | PATCH | `/issues/{publicId}/` | Редактировать замечание |
|
||
| `IssuesApi.getChanges` | GET | `/issue-changes/` | История изменений замечания (`issue_id`) |
|
||
|
||
### `sarexApi` — Gateway/API Sarex
|
||
|
||
Файлы `issuesApi.ts`, `prescriptionsApi.ts`, `inspections.ts`, `contractsApi.ts`, `attributes.ts`.
|
||
|
||
| Метод API | HTTP | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `IssuesApi.postComment` | POST | `/issues/api/comments/` | Добавить комментарии |
|
||
| `IssuesApi.deleteComment` | DELETE | `/issues/api/comments/{id}/` | Удалить комментарий |
|
||
| `IssuesApi.postAttachment` | POST | `/issues/api/attachments/` | Загрузить вложение (multipart) |
|
||
| `IssuesApi.deleteAttachment` | DELETE | `/issues/api/attachments/{id}/` | Удалить вложение (`issue_public_id`) |
|
||
| `PrescriptionsApi.postPrescription` | POST | `/issues/api/prescriptions/` | Создать предписание |
|
||
| `PrescriptionsApi.getPrescriptions` | GET | `/issues/api/prescriptions/` | Список предписаний (сериализованные фильтры в query) |
|
||
| `InspectionsApi.getInspections` | GET | `/inspections/api/v1/inspections/light/` | Список инспекций (`company_id`, `limit`, `offset`) |
|
||
| `InspectionsApi.getInspectionTypes` | GET | `/inspections/api/v1/inspections/types/` | Типы инспекций (`company_id`) |
|
||
| `ContractsApi.getContracts` | GET | `/contracts/api/v0/contracts/` | Договоры (`tenant_id`, `contractor_id`, `resource_id`) |
|
||
| `AttributesApi.getDocumentAttributes` | GET | `/gateway/api/v1/documents/{documentId}/attributes/` | Атрибуты документа |
|
||
|
||
### `sarex` — Локальный сервис данных
|
||
|
||
Файл `module/api/coreApi.ts`.
|
||
|
||
| Метод API | HTTP | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `CoreApi.getUserSettings` | GET | `/api/client/settings/` | Клиентские настройки |
|
||
| `CoreApi.getUsers` | GET | `/api/core/users/` | Пользователи компании (`company`, `limit`, `offset`, `show_inactive`) |
|
||
| `CoreApi.getDepartments` | GET | `/api/core/admin/departments/` | Отделы компании |
|
||
| `CoreApi.getPositions` | GET | `/api/core/admin/positions/` | Должности компании |
|
||
|
||
### `gateway` — Gateway Sarex
|
||
|
||
Файлы `coreApi.ts`, `resources.ts`, `templatesApi.ts`.
|
||
|
||
| Метод API | HTTP | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `CoreApi.getGatewayUsers` | GET | `/api/v2/users/` | Пользователи по ресурсу/правам (`resource_id`, `permissions`, `limit`, `offset`) |
|
||
| `ResourcesApi.getResourceFullInfo` | GET | `/api/v2/resources/{resourceId}/` | Полная информация о ресурсе |
|
||
| `TemplatesApi.getTemplates` | GET | `/api/v1/disks/{diskId}/flat_documents/` | Плоский список документов диска (`type`) |
|
||
|
||
### `documentations` — Сервис документации
|
||
|
||
Файлы `documentation.ts`, `templatesApi.ts`.
|
||
|
||
| Метод API | HTTP | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `DocumentationApi.getDocumentById` | GET | `/documents/{docId}` | Документ по id (опц. `extend`) |
|
||
| `TemplatesApi.getDisks` | GET | `/disks` | Список дисков |
|
||
|
||
### `eav` — Атрибуты и ассеты (EAV)
|
||
|
||
Файлы `assets.ts`, `attributes.ts`.
|
||
|
||
| Метод API | HTTP | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `AssetsApi.getAssetsPost` | POST | `/v4/assets/search/` | Поиск ассетов |
|
||
| `AssetsApi.getAssetsGet` | GET | `/v4/assets/` | Список ассетов |
|
||
| `AttributesApi.getAttributes` | GET | `/v0/attribute/` | Атрибуты компании (`company_id`) |
|
||
|
||
### `files` — Сервис файлов
|
||
|
||
Файл `documentation.ts`.
|
||
|
||
| Метод API | HTTP | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `DocumentationApi.getPage` | GET | `/pages/{sourceId}/{pageId}` | Страница файла (ответ `blob`) |
|
||
|
||
### `premises` — Сервис помещений
|
||
|
||
Файл `premises-api.ts`.
|
||
|
||
| Метод API | HTTP | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `PremisesApi.getPremise` | GET | `/premises/{id}/` | Помещение по id |
|
||
| `PremisesApi.getPremisesFilter` | POST | `/premises/filter/` | Фильтрация помещений (`limit`, `offset` в query) |
|
||
| `PremisesApi.getPremiseTypesFilter` | POST | `/premise_types/filter/` | Фильтрация типов помещений (`limit`, `offset` в query) |
|
||
|
||
## Обработка ошибок
|
||
|
||
Глобальная обработка выполняется в `module/api/http-service.ts`: `httpService` обёрнут в `Proxy`, который для методов запросов (`getRequest`/`postRequest`/`putRequest`/`patchRequest`/`deleteRequest`) перехватывает ошибку и при статусе `403` показывает toast-уведомление (`react-toastify`) с текстом `detail` из ответа либо сообщением «У вас недостаточно прав для выполнения данного действия», после чего пробрасывает ошибку дальше. Для отдельных запросов показ уведомлений включается флагом `showErrorNotification: true`. В окружении `local` SDK переключается в режим `original` (`setSharedHttpServiceConfig({ type: "original" })`).
|