# Эндпоинты, с которыми взаимодействует prescriptions-frontend

Документ описывает все HTTP-эндпоинты внешних сервисов, к которым обращается модуль (микрофронтенд `prescriptions-frontend`, Module Federation `srx_prescriptions`, экспонирует `./PrescriptionsPage`).

## Как устроено взаимодействие

Запросы выполняются через единый `httpService` (`module/api/http-service.ts`), созданный фабрикой `createHttpService` из [`@sarex-team/sdk-js`](https://www.npmjs.com/) поверх `axios`. Каждый вызов задаётся объектом с полями:

- `service` — логическое имя сервиса (см. таблицу хостов ниже);
- `url` — путь запроса (дописывается к базовому хосту сервиса);
- `data` — тело запроса (для `POST`/`PUT`/`PATCH`);
- `queryKey`, `axiosConfig` (в т.ч. `responseType: "blob"` для файлов), `params` — опции кеширования/повторов и параметры запроса.

Метод HTTP определяется вызываемой функцией `httpService`: `getRequest`/`postRequest`/`putRequest`/`patchRequest`/`deleteRequest`.

Базовый хост подставляется SDK по паре (`BUILD_ENV`, `service`) из реестра `module/api/hosts.ts`. Значение `BUILD_ENV` задаётся на этапе сборки (`webpack.config.js` → `DefinePlugin`, глобальная константа `BUILD_ENV`), по умолчанию — `prod` (`http-service.ts`: `BUILD_ENV ?? "prod"`). В окружении `local` тип сервиса переключается на `original` (`setTypeOfHttpService("original")`).

Итоговый URL = `<базовый хост сервиса>` + `url`.

Определения вызовов сосредоточены в `module/api/*` (`index.ts`, `contractsApi.ts`, `resourcesApi.ts`, `templatesApi.ts`, `marks.ts`) и частично в сторах (`module/store/stores/resources.ts`, `module/store/stores/users.ts`).

## Базовые хосты по сервисам и окружениям

Значения из `module/api/hosts.ts`. Помимо `stage`/`prod` определены окружения `local`, `preprod` и `contour` (в `contour` — относительные пути для изолированного контура).

| Сервис (`service`) | Назначение | `stage` | `prod` |
| --- | --- | --- | --- |
| `prescriptions` | Предписания (поверх issues) | `https://stage-api.sarex.io/issues/api/prescriptions` | `https://api.sarex.io/issues/api/prescriptions` |
| `issues` | Сервис замечаний/issues | `https://stage-api.sarex.io/issues/api` | `https://api.sarex.io/issues/api` |
| `documentations` | Сервис документации (документы, бандлы, диски) | `https://stage-api.sarex.io/documentations/api/v1` | `https://api.sarex.io/documentations/api/v1` |
| `gateway_api_v1` | Gateway API v1 (ресурсы, документы, шаблоны) | `https://stage-api.sarex.io/gateway/api/v1` | `https://api.sarex.io/gateway/api/v1` |
| `gateway_api_v2` | Gateway API v2 (пользователи, ресурсы) | `https://stage-api.sarex.io/gateway/api/v2` | `https://api.sarex.io/gateway/api/v2` |
| `sarex` | Основной backend (core/client) | `https://stage.sarex.io` | `https://lk.sarex.io` |
| `sarexApi` | API Sarex (contracts) | `https://stage-api.sarex.io` | `https://api.sarex.io` |
| `eav_api_v0` | Сервис атрибутов (EAV) | `https://stage-api.sarex.io/eav/api/v0` | `https://api.sarex.io/eav/api/v0` |
| `orchestrator` | Оркестратор процессов (маркировка, подпись) | `https://stage-api.sarex.io/orchestrator` | `https://api.sarex.io/orchestrator/api` |
| `files` | Сервис файлов (скачивание) | `https://stage-api.sarex.io/files/api/v1` | `https://api.sarex.io/files/api/v1` |
| `lambdas` | Лямбды (экспорт reviews) | `https://stage-api.sarex.io/lambdas` | `https://api.sarex.io/lambdas` |
| `checklists` | Сервис чек-листов | `https://stage-api.sarex.io/checklists/api/v1` | `https://api.sarex.io/checklists/api/v1` |
| `zitadel` | IdP (аутентификация) | `https://idp.dev.stage.sarex.io` | `https://login.sarex.io` |

> Подключаемый удалённый модуль (Module Federation) описан отдельно в `module/api/module-hosts.ts`: `documentations` → `remoteEntry.js` (stage: `https://stage-modules.sarex.io/documentations/static/module/remoteEntry.js`, prod: `https://modules.sarex.io/documentations/static/module/remoteEntry.js`). Хост выбирается функцией `getModuleHost(moduleName)` по `BUILD_ENV`.

## Эндпоинты по сервисам

### `prescriptions` — Предписания

| Функция | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `getPrescriptions` | GET | `/?{query}` | Список предписаний (фильтры/поиск, сериализация в `serializePrescriptionParams`) |
| `createPrescription` | POST | `/prescription/` | Создать предписание ⚠ вызывается с `service: "prescription"` (см. замечания) |
| `getPrescriptionById` | GET | `/{id}/` | Предписание по id |
| `editPrescription` | PATCH | `/{id}/` | Редактировать предписание |
| `deletePrescription` | DELETE | `/{id}/` | Удалить предписание |
| `exportPrescriptionById` | GET | `/{id}/export/?file_format={docx\|pdf}` | Экспорт предписания в docx/pdf |
| `getStatusCount` | GET | `/status-count/?{query}` | Счётчики по статусам |
| `getHistoryByCompanyId` | GET | `/history/?company_id={id}` | История предписаний компании |
| `getHistoryByPrescriptionId` | GET | `/{id}/history/` | История конкретного предписания |

### `issues` — Замечания / статусы

| Функция | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `getStatusModels` | GET | `/prescription-status-models/?company_id={id}` | Модели статусов предписаний |
| `getCompanyStatuses` | GET | `/prescription-statuses/?company_id={id}` | Статусы предписаний компании |
| `getIssues` | GET | `/issues/?{params}` | Список замечаний |
| `getCustomStatuses` | GET | `/companies/{companyId}/status-model/v2/` | Кастомная модель статусов компании |

### `documentations` — Сервис документации

| Функция | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `getDocument` | GET | `/documents/{id}` | Документ по id |
| `getDisks` | GET | `/disks` | Список дисков (используется в `DocumentAPI` и `TemplatesApi`) |
| `mark` | PUT | `/bundles/{bundleId}/marks` | Добавить штампы/QR/подписи в бандл |
| `sign` | POST | `/bundles/{bundleId}/sign` | Подписать бандл |
| `downloadFile` | GET | `/bundles/{bundleId}/{key}/download` | Скачать файл бандла (`responseType: blob`) |

### `gateway_api_v1` — Gateway API v1

| Функция | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `getResources` (store) | GET | `/resources/?company_id={id}` | Список ресурсов компании |
| `fetchParentDocumentByResourceId` | GET | `/resources-rpc/parent-document-by-resource-id/{resourceId}/` | Родительский документ по resource id |
| `fetchDocumentsBundleVersions` | POST | `/documents/bundle_versions` | Версии бандлов документов |
| `getDocumentAncestors` | POST | `/documents/ancestors` | Предки документов |
| `getTemplates` | GET | `/disks/{diskId}/flat_documents/?type={type}` | Шаблоны диска (плоский список) |

### `gateway_api_v2` — Gateway API v2

| Функция | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `getUsersByResourceId` | GET | `/users/?{query}` | Пользователи по фильтру ресурса |
| `getResourceFullInfo` | GET | `/resources/{resourceId}/` | Полная информация о ресурсе |

### `sarex` — Основной backend (core/client)

| Функция | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `getUsersByCompanyId` | GET | `/api/core/users/?company={id}&{query}` | Пользователи компании |
| `getDepartments` | GET | `/api/core/admin/departments/?company={id}` | Отделы компании |
| `getDepartmentsV2` | GET | `/api/core/admin/departments/?company={id}&{query}` | Отделы компании (с доп. query) |
| `getPositions` | GET | `/api/core/admin/positions/?company={id}` | Должности компании |
| `getPositionsV2` | GET | `/api/core/admin/positions/?company={id}&{query}` | Должности компании (с доп. query) |
| `getSettings` (store) | GET | `/api/client/settings/` | Клиентские настройки |

### `sarexApi` — API Sarex (contracts)

| Функция | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `getContracts` | GET | `/contracts/api/v0/contracts/?tenant_id={companyId}` | Договоры компании |
| `getContractsByContractorId` | GET | `/contracts/api/v0/contracts/?tenant_id={companyId}&contractor_id={id}` | Договоры по контрагенту |

### `eav_api_v0` — Сервис атрибутов (EAV)

| Функция | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `getAttributes` | GET | `/attribute/?company_id={id}` | Атрибуты компании |

### `orchestrator` — Оркестратор процессов

| Функция | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `createMarkFlow` | POST | `/process` | Запустить процесс маркировки |
| `getMarkFlow` | GET | `/process/{id}` | Процесс по id |
| `startSign` | POST | `/sign` | Запустить подписание |

### `files` — Сервис файлов

| Функция | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `downloadDocuments` | POST | `/documents/` | Скачать документы по `bundle_ids` (`responseType: blob`) |

### `lambdas` — Лямбды (экспорт)

| Функция | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `fetchExportReviewsByResourceIDs` | GET | `/export-reviews/{params}` | Экспорт reviews (xlsx) |
| `fetchExportReview` | GET | `/export-reviews/{reviewId}/report/` | Отчёт по review (pdf) |

### `flows` — Процессы (⚠ сервис не задан в hosts.ts)

| Функция | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `changeCopyPaths` | PATCH | `/documents/change-copy-paths/` | Изменить пути копий документов |

## Обработка ошибок

Отдельного модуля-маппера ошибок (`errors.ts`) в проекте нет — обработка распределена:

- часть обёрток (`ContractsApi`, `ResourcesApi`, `TemplatesApi`) при ошибке пробрасывают `throw new Error(error)`;
- часть функций (`fetchParentDocumentByResourceId`, `fetchExportReview*`) гасят ошибку через `console.error` и не пробрасывают её;
- тип ответа об ошибке — `ErrorResponse` (`module/api/types.ts`): читается `response.data.detail`;
- статусы запроса в сторах: `RequestStatus` — `init`/`loading`/`success`/`fetching`/`error`/`permissionError`.

## Права доступа (`module/api/permissions.ts`)

Модуль оперирует правами `core.*`: `can_view_prescription`, `can_add_prescription`, `can_edit_prescription`, `can_delete_prescription`, `can_view_all_prescriptions`, `can_admin_prescription`. Группы (`FG_PERMISSIONS`): `ADMIN` (все права), `AUTHOR` (просмотр + создание), `RESPONSIBLE` и `VIEW_ALL` (просмотр).

## Замечания и потенциальные проблемы

- **`prescription` (единственное число)** — `createPrescription` вызывается с `service: "prescription"`, но такого ключа в `module/api/hosts.ts` нет (есть только `prescriptions`). Базовый хост не резолвится корректно — вероятно опечатка, следует использовать `prescriptions`.
- **`flows`** — `changeCopyPaths` использует `service: "flows"`, который также не задан в `hosts.ts`. Ключ нужно добавить в реестр либо исправить.
- **`contour`** — в окружении `contour` не определён сервис `sarexApi`, поэтому `getContracts`/`getContractsByContractorId` в этом контуре работать не будут.
- **`orchestrator`** — в `prod` базовый URL с суффиксом `/api` (`.../orchestrator/api`), а в `stage`/`local`/`preprod` — без него. Пути эндпоинтов (`/process`, `/sign`) следует проверять с учётом этого различия.
- **`checklists` и `zitadel`** заданы в `hosts.ts`, но напрямую через `httpService` в модуле не вызываются (`zitadel` — IdP, используется SDK для авторизации; `checklists` в текущем коде модуля не используется).