67 lines
4.5 KiB
Markdown
67 lines
4.5 KiB
Markdown
# Эндпоинты, с которыми взаимодействует document-link-frontend
|
||
|
||
Документ описывает HTTP-эндпоинты внешних сервисов, к которым обращается фронтенд публичных ссылок (`document-link-frontend`).
|
||
|
||
## Как устроено взаимодействие
|
||
|
||
Фронтенд загружает карточку документа по `uuid` из URL (`/<uuid>`). Запрос выполняется хуком `useSWR` в `src/app/[uuid]/components/modal.tsx` через нативный `fetch`. Базовый хост API выбирается в рантайме по `window.location.hostname`, итоговый URL = `https://<apiBaseUrl>` + путь эндпоинта. Скачивание файлов выполняется переходом браузера по ссылкам, которые возвращает сам API (`download_link`, `download_mrpas_link`).
|
||
|
||
Авторизация: заголовок `Authorization: Bearer <jwt>` (сейчас — зашитая константа `fixedToken`; целевое — `NEXT_PUBLIC_API_TOKEN` из секрета `documentations-publiclink-jwt-secret`). Запрос идёт с `credentials: "include"`.
|
||
|
||
## Базовые хосты по окружениям
|
||
|
||
Значения из `switch` по `window.location.hostname` в `modal.tsx`:
|
||
|
||
| Hostname фронтенда | `apiBaseUrl` (базовый хост API) |
|
||
| --- | --- |
|
||
| `localhost` | `https://stage-api.sarex.io` |
|
||
| `document-link.stage.sarex.io` | `https://stage-api.sarex.io` |
|
||
| `document-link.sarex.io` | `https://api.sarex.io` |
|
||
| прочее | не определён (fallback `https://stage-api.sarex.io`) |
|
||
|
||
## Эндпоинты по сервисам
|
||
|
||
### `documentations` — Сервис документации
|
||
|
||
| Ключ | Метод | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| Публичная ссылка | GET | `/documentations/api/v1/public/documents/public_link/{uuid}` | Метаданные документа по публичной ссылке (`uuid`) |
|
||
|
||
Пример итогового URL: `https://stage-api.sarex.io/documentations/api/v1/public/documents/public_link/e602b98d-58a1-4ba3-8a89-84e5617b5aac`.
|
||
|
||
Ожидаемые поля ответа (используются во фронтенде):
|
||
|
||
| Поле ответа | Тип | Использование |
|
||
| --- | --- | --- |
|
||
| `name` | string | Название документа |
|
||
| `document_type` | string | Тип (иконка): `bim`/`bimv2`/`cloud`/`surface`/`workspace`/`pdf`/`deviation`/`c2s`/`c2c`/`abap`/`ksg`/`docx`/`xlsx`/`dxf`/`dwg`/… |
|
||
| `author` | string | Автор |
|
||
| `version` | string | Версия документа (скрывается для `workspace`/`folder`/`project`) |
|
||
| `size` | number | Размер в байтах (форматируется библиотекой `bytes`) |
|
||
| `download_token` | string | Токен скачивания |
|
||
| `download_link` | string (URL) | Прямая ссылка на скачивание файла |
|
||
| `download_mrpas_link` | string (URL) \| null | Ссылка на скачивание МЧД (опционально) |
|
||
| `expires_at` | string (datetime) \| null | Срок действия ссылки; `null` → «Неограничено» |
|
||
| `is_connector` | bool | Признак «файл > 5 Гб, требуется Sarex-коннектор» |
|
||
|
||
### Скачивание файлов (динамические ссылки)
|
||
|
||
Не отдельные эндпоинты реестра, а переход браузера по URL из ответа:
|
||
|
||
| Действие | Источник URL |
|
||
| --- | --- |
|
||
| Скачать файл/папку | `download_link` из ответа `public_link` |
|
||
| Скачать МЧД | `download_mrpas_link` из ответа `public_link` (если не `null`) |
|
||
|
||
При `is_connector = true` вместо прямого скачивания показывается предупреждение со ссылкой на [Sarex-коннектор](https://support.sarex.io/knowledge_base/item/347946).
|
||
|
||
## Обработка ошибок
|
||
|
||
Статус ответа маппится в человекочитаемое сообщение (`modal.tsx`):
|
||
|
||
| Статус | Сообщение |
|
||
| --- | --- |
|
||
| `400`, `404` | «Ссылка не найдена» |
|
||
| `410` | «Время действия вашей ссылки истекло» |
|
||
| `500`, `503` | «Что-то пошло не так» |
|