167 lines
14 KiB
Markdown
167 lines
14 KiB
Markdown
# Эндпоинты, с которыми взаимодействует 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` в текущем коде модуля не используется).
|