| assertSagaSucceeded | Превращает терминально-отказную сагу (failed/compensated) в брошенную SagaFailedError; успешную возвращает как есть. Вынесено отдельной чистой функцией, чтобы поведение покрывалось unit-тестом без рендера хука. |
| availableActions | Доступные действия (event-типы) в данном состоянии FSM — для показа/сокрытия кнопок в UI. Источник истины — та же xstate-машина, что у бэка (ADR-0022), передаётся параметром (curated re-export машин — отдельный L0-пакет). |
| can | Чистая (не-хук) проверка RBAC: есть ли у пользователя хотя бы одна из требуемых ролей (ADR-0009). Пустой required → доступно любому аутентифицированному. |
| createOfflineDomain | Фабрика offline-first домена под любой агрегат (ADR-0049). Из конфига собирает OfflineDomain: ops/mutationKeys/scope для live-хуков (через useDomainMutation) и registerDefaults/useOutbox/useRetryFailed для replay-после-рестарта и UI-индикаторов. Эталон инстанциации — shiftReportDomain для сменных рапортов. |
| MineflowProvider | Корневой провайдер SDK. Строит аутентифицированный fetch ОДИН раз и переиспользует его и для REST-клиента, и для SSE-фидов. TanStack Query + контекст. Работает в web и React Native (react-dom не требуется). |
| RealtimeProvider | - |
| rolesSignature | Контентная сигнатура набора ролей. Стабильна при равном НАБОРЕ ролей независимо от ссылки на массив (caller часто передаёт inline-литерал roles={['Foreman']}) и от порядка. NUL-разделитель не встречается в PascalCase-именах SystemRole, поэтому разные наборы дают разные строки. |
| useAddBlastingEntry | Взрывные работы: тип ВВ + масса. |
| useAddDowntimeEvent | Простой: причина + интервал (endedAt > startedAt). |
| useAddDrillingEntry | Бурение: ссылается на assetUsageId. |
| useAddFuelEntry | Топливо: выдано/израсходовано (consumed ≤ issued), ссылается на assetUsageId. |
| useAddShiftAssetUsage | Использование техники (anchor): возвращает id, на который ссылаются drilling/fuel (assetUsageId) — добавляй asset-usage ДО них. Offline-устойчив; FIFO-replay сохраняет порядок энкью. |
| useAddShiftPersonnel | Персонал смены: отработанные/простойные часы по сотруднику. |
| useAddTmcUsage | Расход ТМЦ: материал + количество + единица. |
| useApiMutation | Дженерик-write без авто-инвалидации кэша — когда кэшем управляешь сам (optimistic-апдейты, ручной setQueryData). Авто-Idempotency-Key всё равно проставит fetch-слой по generateId. Для автоинвалидации раздела бери useDomainMutation. |
| useApiQuery | Типобезопасный дженерик-хук чтения под любой endpoint, которого ещё нет в concrete-наборе. Конкретный запрос вызывает caller через замыкание fn(client) и типизирует его против @mineflow/api-client — SDK даёт лишь механику (кэш TanStack Query + REST-клиент из ко нтекста), не хардкодит формы DTO. |
| useApiQueryAll | Как useApiQuery, но стягивает ВСЕ страницы курсорной пагинации в один массив (collectAllPages). Нужен там, где UI обязан видеть полный набор, а серверный предел страницы (limit ≤ 200, libs/common) молча обрезал бы одностраничный запрос — напр. пикеры персонала/техники на участке с >200 единицами. |
| useApproveShiftReport | Утверждение сменного рапорта (центральная 6-шаговая approve-сага). POST даёт 202 + sagaId; хук поллит /sagas/{id}/status до терминала. Терминальный откат (failed/compensated) бросается как SagaFailedError → срабатывает onError. |
| useAsset | Один актив EAM по id. |
| useAssetClasses | Справочник классов активов EAM (для resolve label'а техники в UI). Долгоживущий lookup, читаемый всеми ролями. |
| useAssets | Список активов EAM (cursor-пагинация, фильтры status/objectId). |
| useAssetsAll | Полный список активов: стягивает ВСЕ страницы к урсора (в отличие от useAssets, который отдаёт одну страницу ≤200 и молча обрезал бы пикер на участке с >200 единицами). Курсор/лимит хук гонит сам — caller передаёт только фильтры (objectId/status). Ключ отдельный (…list({…, all: true})), чтобы не пересекаться с кэшем одностраничного useAssets. |
| useAvailableActions | Хук доступных FSM-действий для текущего статуса сущности (для UI-кнопок). Мемо-обёртка над чистой availableActions: результат пересчитывается только при смене machine/stateValue. Действия отдаются БЕЗ учёта guard'ов — валидацию перехода делает бэк (409). |
| useBrigade | Одна бригада HR по id. |
| useBrigadeMembers | Состав бригады (под-коллекция members). |
| useBrigades | Список бригад HR (cursor-пагинация). |
| useCan | Хук RBAC-гейта: есть ли у текущего пользователя (роли из MineflowProvider) хотя бы одна из требуемых ролей. Обёртка над чистой can. |
| useCompleteMaintenance | Завершение ТО: FSM maintenance → operational (событие COMPLETE_MAINTENANCE). ADR-0045: dedicated PATCH /eam/assets/:id/complete-maintenance; реактивно завершает открытую запись MaintenanceRecord. Тело не требуется. |
| useConserveAsset | Консервация актива: FSM operational → conserved (событие CONSERVE, ADR-0022). ADR-0045 (asset-centric): dedicated PATCH /eam/assets/:id/conserve. reason обязателен (OPS_REQUIRING_REASON). Запись журнала движений создаётся РЕАКТИВНО по событию eam.asset.status-changed. На успехе инвалидируется список активов. |
| useCreateShiftReport | Создание черновика рапорта (parent: участок + дата + смена). 201 → рапорт. Offline-устойчив (общий scope + стабильный Idempotency-Key из vars — клади его при энкью). На успехе инвалидирует список рапортов. |
| useDecommissionAsset | Списание актива (double-approval). Синхронная операция — отдаёт 200, это НЕ сага. На успехе инвалидирует список активов. |
| useDocumentDownloadUrl | Presigned GET URL д окумента (для просмотра, когда локальной копии файла уже нет, напр. на другом устройстве/после очистки кэша). Запрос не запускается при пустом id. |
| useDocumentsByEntity | Документы сущности-владельца (entityType+entityId) — кросс-девайс список (ADR-0051): утверждающий на другом устройстве видит вложения рапорта. Запрос не запускается при пустом entityId. |
| useDomainMutation | Единая доменная write-мутация: вызывает fn(client, vars) и на успехе инвалидирует invalidateKey (префикс списков/деталей раздела). Заменяет раздублированные per-area хелперы (useAssetMutation/useShiftReportMutation): раздел задаётся invalidateKey, offline-механика — опциями. На дженерике построены все concrete write-хуки SDK. |
| useIsOnline | Текущая «онлайновость» (по onlineManager TanStack Query, который приложение связывает с реальной сетью). Реактивно перерисовывает UI при смене связи. |
| useMineflow | Доступ к контексту SDK (MineflowContextValue: REST-клиент, аутентифицированный fetch, baseUrl, роли). |
| useMineflowClient | Удобный доступ только к REST-клиенту из контекста (без остального значения). |
| useNotifications | REST-backlog уведомлений получателя (cursor-пагинация, новые сверху). Источник истины ленты — realtime (useRealtimeNotifications) префиксит сюда новые, дедуп по id. |
| useOnNotification | Подписка на входящие уведомления из Centrifugo (personal + role каналы). Низкоуровневый хук: только колбэк, без записи в кэш — для счётчиков/тостов. Колбэк хранится в ref, поэтому передавать можно inline без ре-подписки. No-op при выключенном Centrifugo. |
| usePerson | Один сотрудник HR по id. |
| usePersonnel | Список персонала HR (cursor-пагинация). |
| usePersonnelAll | Полный список персонала: стягивает ВСЕ страницы курсора (в отличие от usePersonnel — одна страница ≤200, молча обрезающая крупный участок). Курсор/ лимит хук гонит сам; caller передаёт только фильтры (objectId). Отдельный ключ (…list({…, all: true})), чтобы не пересекаться с кэшем usePersonnel. |
| usePositions | Справочник должностей HR (для picker'а персонала смены). Долгоживущий lookup, читаемый всеми ролями. |
| usePresence | Presence-индикатор (ADR-0054): сколько коллег организации сейчас онлайн в realtime. enabled=false → { online: 0, enabled: false }, индикатор прячется. |
| useProductionObjects | Справочник участков (production objects) для picker'ов. Долгоживущий lookup, читаемый всеми ролями. activeOnly входит в ключ кэша (разные кэши). |
| useReactivateAsset | Расконсервация актива: FSM conserved → operational (событие REACTIVATE). ADR-0045: dedicated PATCH /eam/assets/:id/reactivate (тело не требуется). |
| useRealtimeNotifications | Единственный realtime-хук ленты (ADR-0054): входящие из Centrifugo префиксятся в TanStack-кэш useNotifications (дедуп по id) — экран видит один растущий список. No-op при выключенном Centrifugo (живые апдейты тогда не приходят, актуализация — рефетчем backlog). |
| useRegisterAsset | Регистрация (создание) нового актива. Авто-Idempotency-Key; на успехе инвалидирует список активов. |
| useRejectShiftReport | Отклонение поданного рапорта (submitted → rejected). reason ≥5. БЕЗ саги (синхронный FSM-переход). Offline-устойчив; на успехе инвалидирует список. |
| useRejectShiftReportAfterApprove | Сторнирование утверждённого рапорта (approved → rejected). Только CEO. POST даёт 202 + rejectSagaId (компенсирующая сага); хук поллит до терминала. reason ≥10. Терминальный откат бросается как SagaFailedError → onError. |
| useSagaMutation | Хук async-саги: start инициирует операцию (POST 202 → { sagaId }), затем хук поллит /sagas/{id}/status до терминального состояния и резолвится финальным SagaStatus. Терминальный откат (failed/compensated) бросается как SagaFailedError → срабатывает onError, а не onSuccess. |
| useShiftReport | Один сменный рапорт (parent) по id. Возвращает FSM-поля без line-items. |
| useShiftReportEntries | Line-items рапорта: все 7 коллекций одним вызовом GET /:id/entries. |
| useShiftReports | Список сменных рапортов PRD. |
| useSubmitShiftReport | Подача черновика на утверждение (FSM draft → submitted). Тело пустое. Offline-устойчив; на успехе инвалидирует список рапортов. |
| useTimesheet | Табель HR за период (query.dateFrom/dateTo обязательны на бэке). |
| useTransferAsset | Перемещение/передача актива на другой объект (PATCH). На успехе инвалидирует список активов. |
| useWatch | Одна вахта HR по id. |
| useWatches | Список вахт HR (без personnelId-фильтра — query опционален). |