116 lines
10 KiB
Markdown
116 lines
10 KiB
Markdown
# Эндпоинты, с которыми взаимодействует inspections-frontend
|
||
|
||
Документ описывает все HTTP-эндпоинты внешних сервисов, к которым обращается модуль (микрофронтенд `inspections-frontend`).
|
||
|
||
## Как устроено взаимодействие
|
||
|
||
Запросы выполняются через общий `httpService` (`module/api/http-service.ts`), созданный фабрикой `createHttpService` из `@sarex-team/sdk-js` (поверх `axios`). У сервиса есть методы `getRequest`, `postRequest`, `patchRequest`, `deleteRequest`, каждый из которых принимает объект с полями:
|
||
|
||
- `service` — логическое имя сервиса (см. таблицу хостов ниже);
|
||
- `url` — путь запроса (дописывается к базовому хосту сервиса);
|
||
- `data` — тело запроса (для POST/PATCH);
|
||
- `axiosConfig` — доп. настройки axios (`params`, `paramsSerializer` и т.п.);
|
||
- `showErrorNotification` — показывать ли уведомление об ошибке.
|
||
|
||
Базовый хост подставляется по паре «`service` + окружение». Окружение определяется глобальной переменной сборки `BUILD_ENV` (`local`/`stage`/`preprod`/`prod`/`contour`); при её отсутствии используется `prod` (`const buildEnv = BUILD_ENV ?? "prod"`). В режиме `local` для http-сервиса выставляется `type: "original"`. `BUILD_ENV` задаётся при сборке (напр. `BUILD_ENV=stage npm start`) и прокидывается через webpack DefinePlugin.
|
||
|
||
Определения запросов сгруппированы по файлам в `module/api/` (`inspections.ts`, `assets.ts`, `Issues.ts`, `premises-api.ts`) и по стор-файлам в `module/Inspections/store/` (`inspections.ts`, `filters.ts`, `resource.ts`, `calendar.ts`, `issuesStore.ts`).
|
||
|
||
## Базовые хосты по сервисам и окружениям
|
||
|
||
Значения из `module/api/hosts.ts`. Итоговый URL = `<базовый хост сервиса>` + `url` запроса.
|
||
|
||
| Сервис (`service`) | Назначение | `stage` | `prod` |
|
||
| --- | --- | --- | --- |
|
||
| `inspections` | Сервис событий/инспекций (этот бэкенд) | `https://stage-api.sarex.io/inspections/api/v1` | `https://api.sarex.io/inspections/api/v1` |
|
||
| `sarexApi` | Gateway/API Sarex (`/gateway`) | `https://stage-api.sarex.io` | `https://api.sarex.io` |
|
||
| `sarex` | Локальный сервис данных (`/api/core`, `/api/client`) | `""` (относительные пути) | `""` |
|
||
| `eavV0` | Сервис атрибутов EAV, API v0 | `https://stage-api.sarex.io/eav/api/v0` | `https://api.sarex.io/eav/api/v0` |
|
||
| `eavV4` | Сервис атрибутов EAV, API v4 (ассеты) | `https://stage-api.sarex.io/eav/api/v4` | `https://api.sarex.io/eav/api/v4` |
|
||
| `issues` | Сервис замечаний | `https://stage-api.sarex.io/issues/api` | `https://api.sarex.io/issues/api` |
|
||
| `premises` | Сервис помещений | `https://stage-api.sarex.io/premises/api/v1` | `https://api.sarex.io/premises/api/v1` |
|
||
| `zitadel` | IdP (аутентификация) | `https://idp.dev.stage.sarex.io` | `https://login.sarex.io` |
|
||
|
||
> Также определены окружения `local`, `preprod` и `contour`. В `local` сервис `sarex` проксируется на `/sarex-backend`, а `inspections`/`eav`/`issues`/`premises` указывают на стейдж. В `contour` все хосты пустые (относительные пути для изолированного контура). Сервис `zitadel` в hosts объявлен, но прямых запросов из модуля к нему нет — аутентификация обрабатывается на уровне SDK/платформы.
|
||
|
||
## Эндпоинты по сервисам
|
||
|
||
### `inspections` — Сервис событий/инспекций
|
||
|
||
Базовый хост уже включает `/api/v1`, поэтому в путях ниже он не повторяется.
|
||
|
||
| Метод | Путь | Где вызывается | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| GET | `/inspections/` | `store/resource.ts` | Создание/список событий |
|
||
| POST | `/inspections/` | `store/resource.ts` | Создать событие |
|
||
| POST | `/inspections/filter/` | `store/resource.ts`, `store/calendar.ts` | Список событий с фильтрами и пагинацией в теле |
|
||
| GET | `/inspections/{id}/` | `api/inspections.ts`, `store/resource.ts` | Событие по id |
|
||
| PATCH | `/inspections/{id}/` | `api/inspections.ts` | Частичное обновление события |
|
||
| GET | `/inspections/types/` | `api/inspections.ts` | Типы событий компании (query `company_id`) |
|
||
| POST | `/inspections/status-count/` | `store/inspections.ts` | Счётчики по статусам (фильтры в теле) |
|
||
| POST | `/inspections/filter-options/` | `store/filters.ts` | Доступные значения фильтров |
|
||
| GET | `/inspections/aggregate/created_at/minmax/` | `store/filters.ts` | Мин/макс по дате создания |
|
||
| GET | `/inspections/aggregate/inspection_dt/minmax/` | `store/filters.ts` | Мин/макс по дате проведения |
|
||
| GET | `/inspections/change-history/` | `api/inspections.ts` | История изменений (пагинация, фильтры в query) |
|
||
| GET | `/inspections/export/` | `store/inspections.ts` | Экспорт событий (xlsx) |
|
||
| POST | `/inspections/unavailable-dates/` | `api/inspections.ts` | Недоступные даты для исполнителей |
|
||
| POST | `/inspections/unavailable-users/` | `api/inspections.ts` | Недоступные исполнители на интервал |
|
||
|
||
### `sarexApi` — Gateway/API Sarex
|
||
|
||
| Метод | Путь | Где вызывается | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| GET | `/gateway/api/v1/resources/?company_id={companyId}` | `store/inspections.ts` | Ресурсы (проекты) компании |
|
||
| GET | `/gateway/api/v2/users/` | `store/issuesStore.ts`, `store/resource.ts` | Пользователи (с пагинацией/фильтрами) |
|
||
| GET | `/gateway/api/v1/attachments/?company_id={companyId}&instance_id={id}&model_name=inspection` | `store/resource.ts` | Вложения события |
|
||
| POST | `/gateway/api/v1/attachments/` | `store/resource.ts` | Создать вложение |
|
||
| DELETE | `/gateway/api/v1/attachments/{id}` | `store/resource.ts` | Удалить вложение |
|
||
|
||
### `sarex` — Локальный сервис данных
|
||
|
||
| Метод | Путь | Где вызывается | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| GET | `/api/client/settings/` | `store/inspections.ts` | Клиентские настройки |
|
||
| GET | `/api/core/users/` | `store/inspections.ts` | Пользователи |
|
||
| GET | `/api/core/admin/departments/?company={companyId}` | `store/inspections.ts` | Отделы компании |
|
||
| GET | `/api/core/admin/positions/?company={companyId}` | `store/inspections.ts` | Должности компании |
|
||
|
||
### `eavV4` — Сервис атрибутов EAV (ассеты)
|
||
|
||
| Метод | Путь | Где вызывается | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| POST | `/assets/search/` | `api/assets.ts` | Поиск ассетов по списку id |
|
||
| GET | `/assets/` | `api/assets.ts` | Список ассетов (фильтры/пагинация/теги в query) |
|
||
|
||
> Теги ассетов (`EnumAssetTags`): `location`, `project_structure`, `events.can_be_selected`, `remarks.can_be_selected`.
|
||
|
||
### `eavV0` — Сервис атрибутов EAV (атрибуты)
|
||
|
||
| Метод | Путь | Где вызывается | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| GET | `/attribute/?company_id={companyId}` | `store/inspections.ts` | Атрибуты компании |
|
||
|
||
### `issues` — Сервис замечаний
|
||
|
||
| Метод | Путь | Где вызывается | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| POST | `/issues/` | `api/Issues.ts` | Создать замечание |
|
||
| GET | `/issues/` | `api/Issues.ts` | Список замечаний (фильтры по компании/ресурсу/событию/типам) |
|
||
| POST | `/attachments/` | `api/Issues.ts`, `store/issuesStore.ts` | Прикрепить медиа к замечанию |
|
||
| GET | `/companies/{companyId}/status-model/` | `api/Issues.ts` | Статусная модель замечаний компании |
|
||
| GET | `/issue-types/` | `api/Issues.ts` | Типы замечаний компании |
|
||
|
||
### `premises` — Сервис помещений
|
||
|
||
Базовый хост уже включает `/api/v1`.
|
||
|
||
| Метод | Путь | Где вызывается | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| GET | `/premises/{id}/` | `api/premises-api.ts` | Помещение по id |
|
||
| POST | `/premises/filter/` | `api/premises-api.ts` | Помещения по фильтру (пагинация в query) |
|
||
| POST | `/premise_types/filter/` | `api/premises-api.ts` | Типы помещений по фильтру (пагинация в query) |
|
||
|
||
## Обработка ошибок
|
||
|
||
Показ уведомлений об ошибках управляется флагом `showErrorNotification` в параметрах запроса (включается точечно для части запросов). Для сериализации query-параметров-массивов местами используется `query-string` с `arrayFormat: "comma"` (напр. в `api/Issues.ts`). Часть запросов в `api/assets.ts` оборачивает ошибку в `throw new Error(...)`.
|