70 lines
6.5 KiB
Markdown
70 lines
6.5 KiB
Markdown
# Эндпоинты, с которыми взаимодействует stamp-verification-frontend
|
||
|
||
Документ описывает все внешние HTTP-вызовы, которые выполняет статическая страница проверки штампа (`stamp-verification-frontend`).
|
||
|
||
## Как устроено взаимодействие
|
||
|
||
В отличие от микрофронтендов с декларативным реестром эндпоинтов, здесь весь сетевой код сосредоточен в одном файле — `static/js/index.js`. Страница обычным `fetch` обращается к **одному** публичному эндпоинту backend-сервиса `documentations`, а также подгружает сторонние ресурсы аналитики и статику.
|
||
|
||
Логика вызова:
|
||
|
||
1. из query-строки берутся параметры `id` (идентификатор QR) и `page_number`; запрос выполняется только если оба заданы;
|
||
2. базовый хост API выбирается по `window.location.host`;
|
||
3. выполняется `GET`-запрос с `mode: "cors"`, `credentials: "include"`, `cache: "no-cache"`;
|
||
4. ответ (JSON) маппится на поля страницы.
|
||
|
||
## Базовые хосты по окружениям
|
||
|
||
Значение определяется в `index.js` по хосту страницы. Итоговый URL = `https://<базовый хост>` + путь эндпоинта.
|
||
|
||
| Хост страницы (`window.location.host`) | Базовый хост API | Окружение |
|
||
| --- | --- | --- |
|
||
| `stamp-verification.sarex.io` | `api.sarex.io` | prod |
|
||
| любой другой (напр. `stamp-verification.stage.sarex.io`) | `stage-api.sarex.io` | stage |
|
||
|
||
> Промежуточных окружений (preprod/local) в коде не предусмотрено: всё, что не prod-домен, трактуется как stage.
|
||
|
||
## Эндпоинты по сервисам
|
||
|
||
### `documentations` — Сервис документации
|
||
|
||
| Ключ | Метод | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `getQrDocumentInfo` | GET | `/documentations/api/v1/public/qr/{qrId}/document_info?number_page={pageNumber}` | Публичная информация о документе по QR-коду штампа: название, версия, автор, дата загрузки, актуальность/аннулирование версии, статус согласования, changelog и ссылка на документ в Sarex |
|
||
|
||
Параметры запроса:
|
||
|
||
| Параметр | Расположение | Обязателен | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `qrId` | path (`{qrId}`) | да | Идентификатор QR-кода (из query `?id=`) |
|
||
| `number_page` | query | да | Номер страницы документа (из query `?page_number=`) |
|
||
|
||
Заголовки запроса (как в текущем коде): `Content-Type: application/json` и `Authorization: Bearer <jwt>`. **Токен захардкожен и истёк** — см. раздел «Замечания». Запрос идёт с `credentials: "include"` (куки/учётные данные), `redirect: "follow"`, `referrerPolicy: "no-referrer"`.
|
||
|
||
Используемые поля ответа (по `index.js`): `document_name`, `version_number`, `page_number`, `author`, `upload_date`, `is_actual_version`, `is_canceled`, `does_bundle_have_flows`, `is_actual_version_approved`, `document_review_status`, `document_url`, `is_latest_changelog`, `changelog` (`no`, `description`, `author` и др.). Полная схема — в `openapi.yaml`.
|
||
|
||
Формирование ссылки на документ: при наличии `document_url` ссылка на странице собирается как `${data.document_url}&page_number=${data.page_number}` и открывается в Sarex.
|
||
|
||
## Внешние (сторонние) ресурсы
|
||
|
||
Не относятся к API Sarex, но выполняются страницей:
|
||
|
||
| Ресурс | Метод | URL | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| Яндекс.Метрика (tag.js) | GET | `https://mc.yandex.ru/metrika/tag.js` | Загрузка счётчика аналитики (id `93441026`) |
|
||
| Яндекс.Метрика (noscript) | GET | `https://mc.yandex.ru/watch/93441026` | Пиксель для окружения без JS |
|
||
| Статика приложения | GET | `static/css/*`, `static/js/*`, `static/icons/*`, `static/fonts/*`, `static/img/*` | CSS, `moment-with-locales.min.js`, иконки, шрифты, фон — раздаются самим nginx |
|
||
|
||
Health-check (со стороны инфраструктуры, не самой страницы): `GET /ping` → `200 {"result": "ok"}` (отдаётся nginx).
|
||
|
||
## Обработка ошибок
|
||
|
||
Специализированного маппинга кодов ошибок в человекочитаемые сообщения (как в backend-сервисах) в коде нет. Ошибки обрабатываются минимально: `fetch` обёрнут в `.catch(...)`, ошибки логируются в консоль (`console.error`). При пустом/отсутствующем ответе поля страницы заполняются плейсхолдером `–––` (`PLACEHOLDER_STR`). Пользовательских уведомлений об ошибке нет.
|
||
|
||
## Замечания
|
||
|
||
- **Захардкоженный JWT.** В заголовке `Authorization` в `index.js` вшит истёкший (2023 г.) Bearer-токен. Эндпоинт публичный (`/public/qr/...`) — заголовок с токеном следует удалить; хранить токены в статике недопустимо.
|
||
- **`credentials: "include"`** при кросс-доменном запросе к `*-api.sarex.io` требует корректной CORS-конфигурации на стороне `documentations` (`Access-Control-Allow-Credentials` + конкретный `Access-Control-Allow-Origin`).
|
||
- **Параметр `v`** (версия) читается из query, но пока не используется.
|
||
- **Выбор окружения только по домену** — новый prod-домен потребует правки кода.
|