iac/apps/prescriptions/ENDPOINTS.md

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

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

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

Запросы выполняются через единый httpService (module/api/http-service.ts), созданный фабрикой createHttpService из @sarex-team/sdk-js поверх 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 в текущем коде модуля не используется).