index

@mineflow/client-react

---

@mineflow/client-react / HR

HR

HR (персонал, вахты, смены, табель, УЗ, закрепления техники) — рукописные хуки. Тривиальные read'ы (usePersonnel/useWatches/…) генерятся в ./hr.generated и ре-экспортируются ниже; здесь — нетривиальные read'ы (полный курсорный обход, singleton me, top-level asset-assignments, вахтовый ростер) и write-хуки жизненного цикла 5 агрегатов.

Все write HR синхронные (НЕ саги — ни один endpoint не отдаёт { sagaId }), поэтому каждый построен на useDomainMutation и на успехе инвалидирует свой раздел. Формы тел выводятся из @mineflow/api-client (codegen из OpenAPI) → не дрейфуют. IDEMPOTENT — плейсхолдер под required header-param Idempotency-Key; реальный ключ проставит fetch-слой (makeAuthenticatedFetch).

Interfaces

Interface	Description
PersonnelOrderDocumentFile	Скачанный файл документа приказа: тело + имя файла + MIME.
TimesheetExport	Результат выгрузки табеля: CSV как Blob + имя файла из Content-Disposition.
WatchArrivalOrderDocumentParams	Параметры печати приказа «О заезде на вахту» (BL-72).

Type Aliases

Type Alias	Description
AdjustTimesheetBody	Тело корректировки строки табеля (часы, причина, …).
AssignOrgNodeBody	Тело назначения/снятия штатной позиции (orgNodeId=null — снять с должности).
CancelSurveyBody	Тело отмены опроса (reason).
CancelWatchAssignmentBody	Тело отмены назначения на вахту (reason, …).
ChangeUserLoginBody	Тело переименования логина УЗ (новый login + обязательная причина).
CreateAssetAssignmentBody	Тело закрепления техники за сотрудником (assetId, personnelId, роль, …).
CreateOrgNodeBody	Тело создания узла оргструктуры (parentId/positionId/title/subdivision/plannedHeadcount).
CreatePersonnelOrderBody	Тело создания черновика приказа (operationType + payload по схеме операции).
CreateShiftBody	Тело создания смены (объект, дата, тип смены, вахта, …).
CreateSubstitutionBody	Тело подмены в смене (кого кем, reason, …).
CreateSurveyBody	Тело создания опроса (title, окно приёма, аудитория).
CreateUserAccountBody	Тело создания учётной записи (логин, ФИО, роли, объект-скоуп, …).
CreateWatchAssignmentBody	Тело назначения сотрудника на вахту (personnelId, план прибытия/убытия, опц. assetId станка).
CreateWatchBody	Тело создания вахты (объект, диапазон дат вахтового цикла, …).
DeactivateUserAccountBody	Тело деактивации УЗ (reason, …).
DeleteAssetAssignmentBody	Тело снятия закрепления техники (reason, …).
DepartWatchAssignmentBody	Тело фиксации убытия с вахты (фактическая дата, …).
HirePersonBody	Тело найма сотрудника (ФИО, должность, объект, табельный номер, …).
IssuePersonnelOrderBody	Тело выпуска приказа (draft → issued).
LockUserAccountBody	Тело блокировки УЗ (reason, …).
MovePersonnelBody	Тело операции «Переместить» (ТЗ «Админ-панель» § 4): вахтовая группа и/или статус.
PersonnelOrderDocumentFormat	Формат выгрузки документа приказа (зеркалит бэковый DocumentFormat).
RevokePersonnelOrderBody	Тело сторнирования приказа (issued → revoked; причина).
SetShiftForemanBody	Тело назначения бригадира смены (foremanId).
SetSurveyQuestionsBody	Тело задания вопросов опроса (замена целиком, в draft).
SetWatchStaffingBody	Тело планового состава вахты по должностям (ADR-0082).
StartVacationBody	Тело начала отпуска сотрудника (даты).
StartWatchBody	Тело начала вахты сотрудника (даты вахтового цикла).
SubmitSurveyResponseBody	Тело отправки заполнения (answers).
SupersedePersonnelOrderBody	Тело замены приказа (issued → superseded; ссылка на заменяющий).
TerminatePersonBody	Тело увольнения сотрудника (reason, дата, …).
TimesheetExportQuery	Фильтры выгрузки табеля (dateFrom/dateTo обязательны на бэке, objectId опц.).
TransferPersonBody	Тело перевода сотрудника на другой объект (toObjectId, …).
UpdateOrgNodeBody	Тело обновления узла (переименование/перенос/штат — частичное).
UpdatePersonBody	Тело редактирования карточки сотрудника.
UpdatePersonnelOrderDraftBody	Тело редактирования черновика приказа (частичное; только status=draft).
UpdateShiftBody	Тело правки смены (shiftDate/shiftType/watchId).
UpdateSurveyBody	Тело правки опроса (в draft).
UpdateUserRolesBody	Тело смены ролей УЗ (массив системных ролей).
UpdateWatchBody	Тело правки дат вахты до старта (startDate/endDate).
WatchArrivalOrderDocumentFormat	Формат печатного приказа «О заезде на вахту» (html не поддержан — только файл).

Functions

Function	Description
filenameFromContentDisposition	Достаёт filename из Content-Disposition (attachment; filename="..."; filename*=UTF-8''...). RFC 5987 filename* имеет приоритет (несёт UTF-8 имя). Экспортирована как чистая функция — покрыта unit-тестом без рендера хука.

Действия

Function	Description
useTimesheetExport	Выгрузка табеля в CSV (GET /hr/timesheet/export). Это on-demand ЭКШЕН, не реактивный query: useApiMutation (без авто-запуска/кэша), тело тянется как Blob (parseAs: 'blob'), т.к. эндпоинт стримит файл без typed-ответа в спеке. Само скачивание — на стороне платформы (web: createObjectURL + <a download>; RN: запись в FS), как и у documents (ADR-0051).

Запись

Function	Description
useAdjustTimesheet	Корректировка строки табеля. Инвалидирует раздел табеля.
useArchiveOrgNode	Архивирование узла (active → archived; узел должен быть пуст). Только Admin/CEO. Тело не требуется. Инвалидирует раздел оргструктуры.
useArchiveSurvey	Архивировать опрос (closed → archived).
useArriveWatchAssignment	Фиксация прибытия по назначению на вахту. Тело не требуется. Инвалидирует раздел вахт.
useAssignPersonnelOrgNode	Назначение сотрудника на узел штатного расписания (ADR-0063). orgNodeId=null снимает с должности. Инвалидирует список персонала.
useCancelSurvey	Отменить опрос (draft
useCancelWatchAssignment	Отмена назначения на вахту. Инвалидирует раздел вахт.
useChangeUserLogin	Переименование логина УЗ (PATCH; только локальные учётки — федеративным бэкенд отвечает 422). Инвалидирует раздел УЗ.
useCloseSurvey	Закрыть приём ответов (published → closed).
useCreateAssetAssignment	Закрепление техники за сотрудником. Инвалидирует список закреплений.
useCreateOrgNode	Создание узла штатного расписания (позиция или подразделение). Только Admin/CEO. Инвалидирует дерево и детали оргструктуры.
useCreatePersonnelOrder	Создание черновика кадрового приказа (draft; без номера и эффекта). Admin only. Инвалидирует раздел приказов.
useCreateShift	Создание смены. Инвалидирует список смен.
useCreateSubstitution	Подмена в смене. Инвалидирует раздел смен.
useCreateSurvey	Создать опрос (черновик). Инвалидирует список опросов.
useCreateUserAccount	Создание учётной записи. Инвалидирует список УЗ.
useCreateWatch	Создание вахты. Инвалидирует список вахт.
useCreateWatchAssignment	Назначение сотрудника на вахту. Инвалидирует раздел вахт.
useDeactivateUserAccount	Деактивация УЗ. Инвалидирует раздел УЗ.
useDeleteAssetAssignment	Снятие закрепления техники. Инвалидирует список закреплений.
useDepartWatchAssignment	Фиксация убытия по назначению на вахту. Инвалидирует раздел вахт.
useDiscardPersonnelOrder	Удаление (DISCARD) черновика приказа — физическое удаление. Не-draft удалить нельзя (бэк отдаст 409). Admin only. Тела нет; БЕЗ Idempotency-Key (DELETE идемпотентен по HTTP-семантике, бэк не помечен @Idempotent). Инвалидирует раздел приказов.
useEndVacation	Завершение отпуска сотрудника. Тело не требуется.
useEndWatch	Завершение вахты сотрудника (FSM on_watch → rest). Тело не требуется.
useGenerateWatchShifts	Генерация смен day/night на дни вахты (ADR-0082, B1). Тело не требуется. Идемпотентно. Инвалидирует разделы вахт и смен: роут вахтовый, но создаёт записи hr/shifts, а экран вахты держит оба запроса рядом (таблица смен и график заездов) — без второго ключа они висели на старых данных до перезагрузки.
useHirePerson	Найм (создание) сотрудника. На успехе инвалидирует список персонала.
useIssuePersonnelOrder	Выпуск приказа (draft → issued): выделяет номер, фиксирует payload, диспатчит эффект на сотрудника. Admin only. Инвалидирует раздел приказов.
useLockUserAccount	Блокировка УЗ. Инвалидирует раздел УЗ.
useMovePersonnel	«Переместить» сотрудника (ТЗ «Админ-панель» § 4): смена вахты (A/B) и/или статуса одним PATCH; по каждому изменившемуся полю пишется запись в журнал «Перемещения». Синхронный write → useDomainMutation; инвалидирует раздел персонала (префикс personnel.all накрывает и списки, и журнал перемещений сотрудника).
usePublishSurvey	Опубликовать опрос (draft → published).
useResetUserPassword	Сброс пароля УЗ. Тело не требуется. Инвалидирует раздел УЗ.
useRestoreOrgNode	Восстановление узла из архива (archived → active). Только Admin/CEO. Тело не требуется. Инвалидирует раздел оргструктуры.
useRetryIamProvisioning	Повтор IAM provisioning для pending/failed local УЗ. Инвалидирует раздел УЗ.
useRevokePersonnelOrder	Сторнирование приказа (issued → revoked): причина + async-компенсация эффекта в hr/personnel. Admin only. Инвалидирует раздел приказов.
useSetShiftForeman	Назначение/смена бригадира смены (PUT). Инвалидирует раздел смен.
useSetSurveyQuestions	Задать вопросы опроса (замена, в draft; после публикации заморожены).
useSetWatchStaffing	Плановый состав вахты по должностям (ADR-0082, replace). Возвращает пересчитанное заполнение. Инвалидирует раздел вахт.
useStartVacation	Начало отпуска сотрудника. Инвалидирует список персонала.
useStartWatch	Начало вахты сотрудника (FSM rest → on_watch). Инвалидирует список персонала.
useSubmitSurveyResponse	Отправить заполнение опроса (сторона респондента, offline-outbox).
useSupersedePersonnelOrder	Замена приказа новым (issued → superseded): помечает приказ заменённым новым issued-приказом. Admin only. Инвалидирует раздел приказов.
useTerminatePerson	Увольнение сотрудника (terminal). Инвалидирует список персонала.
useTransferPerson	Перевод сотрудника на другой объект. Инвалидирует список персонала.
useUnlockUserAccount	Разблокировка УЗ. Тело не требуется. Инвалидирует раздел УЗ.
useUpdateOrgNode	Обновление узла (переименование, смена подразделения/штата ИЛИ перенос ветки — отличающийся parentId запускает проверку ацикличности на бэке). Только Admin/CEO. Инвалидирует раздел оргструктуры.
useUpdatePerson	Редактирование карточки сотрудника (PATCH). Инвалидирует список персонала.
useUpdatePersonnelOrderDraft	Редактирование черновика приказа (PATCH; только status=draft — выпущенный иммутабелен, бэк отдаст 409). Admin only. Инвалидирует раздел приказов.
useUpdateShift	Правка даты/типа/привязки смены (PATCH). Инвалидирует раздел смен.
useUpdateSurvey	Изменить опрос (в draft). Инвалидирует раздел опросов.
useUpdateUserRoles	Смена ролей УЗ (PATCH; без двойного согласования). Инвалидирует раздел УЗ.
useUpdateWatch	Правка дат вахты до старта (PATCH). Инвалидирует раздел вахт.

Чтение

Function	Description
useAssetAssignment	Одно закрепление техники по id.
useAssetAssignments	Список закреплений техники за персоналом (cursor-пагинация, фильтры objectId/assetId/personnelId/role/active). Путь top-level /asset-assignments (контроллер смонтирован без hr/-префикса), поэтому хук рукописный, не из генератора (тот ключует по area из пути).
useMe	Текущая учётная запись (GET /hr/user-accounts/me) — кто залогинен: профиль, роли, объект-скоуп. Без параметров; ключ в разделе userAccounts (инвалидация userAccounts.all накроет и me).
useMyAuditLog	Собственный security-журнал (GET /hr/user-accounts/me/audit-log, self-service HR 1.6). Учётка резолвится по JWT так же, как в useMe — видны ТОЛЬКО свои записи, поэтому доступно любой аутентифицированной роли (в отличие от useUserAccountAuditLog, который admin-only по id). Newest-first, первая страница.
useMySurveys	«Мои опросы» — активные опросы, адресованные текущему сотруднику.
useOperationDefs	Реестр операций КДП (GET /hr/personnel-orders/operations) — каталог OperationDef (метаданные форм, 19 типов) для динамического рендера/валидации формы создания приказа на FE (ADR-0042). Рукописный: bare-array read под отдельным долгоживущим ключом personnelOrders.operations (а не list()), чтобы мутации журнала приказов не инвалидировали реестр. Тривиальный list-генератор сюда не подходит (ключует под list()).
useOrgNode	Один узел оргструктуры по id + занятые сотрудники.
useOrgStructure	Дерево оргструктуры (штатное расписание, ADR-0063) с счётчиками вакансий/подчинённых.
usePerson	Один сотрудник HR по id.
usePersonnel	Список персонала HR (cursor-пагинация).
usePersonnelAll	Полный список персонала: стягивает ВСЕ страницы курсора (в отличие от usePersonnel — одна страница ≤200, молча обрезающая крупный участок). Курсор/ лимит хук гонит сам; caller передаёт только фильтры (objectId). Отдельный ключ (…list({…, all: true})), чтобы не пересекаться с кэшем usePersonnel.
usePersonnelMovements	Журнал «Перемещения» сотрудника (ТЗ «Админ-панель» § 3.6): кадровые движения (вахтовая группа / статус), newest-first, первая страница. Рукописный: nested read под {id} генератор не распознаёт. Не запускается при пустом id. (Фильтры changeType/cursor пока вне контракта — на контроллере не проставлен @ApiQuery.)
usePersonnelOrder	Карточка одного кадрового приказа КДП по id.
usePersonnelOrderDocument	Inline-HTML документа выпущенного приказа (GET /hr/personnel-orders/{id}/document). Рукописный: ответ text/html, а не JSON — генератор list/detail сюда не годится (его unwrap(c.GET(...)) подразумевает JSON-тело). Здесь явный parseAs: 'text', чтобы openapi-fetch читал тело как строку (иначе .json() упал бы на HTML). Только status=issued (иначе бэк отдаёт 409 → unwrap бросит MineflowApiError). Не запускается при пустом id.
usePersonnelOrderDocumentDownload	Императивная загрузка документа выпущенного приказа бинарём (pdf/docx) или html. Возвращает стабильный колбэк (id, format) => Promise<{blob, filename, contentType}>. Тянет файл аутентифицированным authFetch (Bearer) напрямую — минуя типизированный openapi-fetch, т.к. тело бинарное (не JSON) и форма ответа зависит от формата. Имя файла берётся из Content-Disposition (RFC 5987 → кириллица в номере приказа сохраняется). DOM-доставку (createObjectURL + a.download) делает платформа (web); RN сохраняет Blob иначе. Только status=issued (иначе 409 → колбэк бросает Error с сообщением бэка).
usePersonnelOrders	Журнал кадровых приказов КДП (cursor-пагинация, фильтры personnelId/objectId/category/operationType/status).
useShift	Одна смена HR по id.
useShifts	Список смен HR (cursor-пагинация, фильтры objectId/shiftDate/shiftType/watchId).
useSurvey	Один опрос HR по id (с вопросами).
useSurveyResponses	Индивидуальные (именные) ответы опроса (Admin).
useSurveyResults	Агрегированные результаты опроса (дашборд).
useSurveys	Список опросов HR (авторская сторона, cursor-пагинация).
useTimesheet	Табель HR за период (query.dateFrom/dateTo обязательны на бэке).
useTimesheetEntry	Одна строка табеля HR по id.
useTimesheetSummary	Итог табеля за период: сумма отработанных часов + простоев и число записей по всей выборке (не по странице). dateFrom/dateTo обязательны на бэке.
useUserAccount	Одна учётная запись HR по id.
useUserAccountAuditLog	Security-журнал учётки (HR 1.6, read-model SecurityAuditLog; admin). Newest-first, первая страница.
useUserAccounts	Список учётных записей HR (cursor-пагинация, фильтры status/systemRoleCode/objectId/search).
useWatch	Одна вахта HR по id.
useWatchArrivalOrderDocumentDownload	Императивная загрузка печатного приказа «О заезде на вахту» (GET /hr/watches/{id}/arrival-order/document). Документ собирается на лету из не-отменённых назначений вахты; номер и дата приходят из диалога печати — реестр приказов ведёт канцелярия. Тот же механизм, что у usePersonnelOrderDocumentDownload: аутентифицированный authFetch → Blob + имя файла из Content-Disposition (RFC 5987, кириллица целая).
useWatchAssignments	Назначения (заезды) вахты — read-model для FSM-переходов arrive/depart/cancel.
useWatches	Список вахт HR (без personnelId-фильтра — query опционален).
useWatchFill	Заполнение вахты по должностям (план/факт/% — ADR-0082).
useWatchRoster	Bulk-ростер вахтовых назначений участка (GET /hr/watches/roster?objectId, ADR-0081, ADR-0119) — плоский список не-отменённых назначений: ФИО + должность одним запросом, кто сейчас на вахте участка. Станка здесь нет: посменную привязку «человек ↔ станок» отдаёт useCrewRoster (наряд). Замена brigade-ростера; убирает N+1 по /watches/{id}/assignments. Рукописный: codegen не распознаёт query-read без {id}. Гейтится на наличие objectId.