index
@mineflow/client-react / PRD
PRD
PRD (сменные рапорты) — рукописные хуки. Тривиальные read'ы
(useShiftReports/useShiftReport/useShiftReportEntries) генерятся в
./prd.generated и ре-экспортируются ниже. Здесь:
- offline-устойчивый write-lifecycle (create→7 add→submit/reject) поверх
shiftReportDomain(общий scope + стабильный mutationKey, ADR-0049); - approve / reject-after-approve саги (поллят статус, online-only).
Write-body и vars-типы (AddShiftPersonnelBody, AddEntryVars, …) живут в
../shift-report-offline (единый источник для live-хуков и offline-replay) и
ре-экспортируются через barrel пакета.
Type Aliases
| Type Alias | Description |
|---|---|
| AdjustDailyNormBody | Тело корректировки сменной нормы (DailyNorm; foreman ±15% / engineer). База НЕ передаётся — её резолвит сервер (см. useDailyNormBase). |
| AmendProductionPlanBody | Тело поправки утверждённого плана (reason + objectPlans). |
| ApproveProductionPlanBody | Тело утверж дения плана (objectPlans с целями по объектам). |
| CancelWorkOrderBody | Тело отмены наряда (reason обязателен). |
| CreateBlockBody | Тело создания блока (объект + код + горизонт + план п/м + число скважин). |
| CreateProductionPlanBody | Тело создания черновика плана (горизонт + год + месяц). |
| CreateWorkOrderBody | Тело создания черновика наряда (объект + дата смены + тип + состав строк). |
| DailyNormBaseQuery | Query серверной базы нормы: objectPlanId + assetId + effectiveFrom. |
| DailyNormBaseResult | Ответ: серверно-резолвленная база + Foreman-диапазон ±15% (source norm/derived/none). |
| EditWorkOrderAssignmentsBody | Тело полной замены состава наряда (только в draft; набор строк целиком). |
| EditWorkOrderShiftBody | Тело смены наряда — участок + дата + тип смены (EDIT_SHIFT, только в draft). Это ключ документа (PRD-WO-INV-01), поэтому передаётся целиком, а не дельтой. |
| MyShiftAnchor | Станок-якорь смены буровика из issued-наряда (operator-aware, ADR-0113/B). |
| MyWorkOrder | Строка наряд-ориентированного экрана буровика: наряд + производный статус рапорта (BL-67). |
| NspGridResult | НСП-сетка плана: цель/распределено по объектам + недельная поблочная разбивка. |
| RejectAfterApproveBody | Тело сторнирования утверждённого рапорта (reason ≥10). |
| RejectProductionPlanVersionBody | Тело отклонения значительной версии CEO (reason ≥5). |
| SendBlockToReworkBody | Тело отправки скважин на перебур (holesToRework + опц. avgPenetrationPerHole). |
| ShiftCoverageResult | Покрытие приёмки сменного отчёта: карточки (принято/готовность/ожидается/парк) + строки наряда с intakeStatus (received/accepted/pending). |
| ShiftDaySummaryRow | Строка свода смены: рапорт участка с показателями (BL-80). |
| SupersedeProductionPlanBody | Тело замещения плана (replacedByPlanId). |
| UpdateShiftReportBody | Тело правки шапки черновика (Q4): объект / дата / тип смены (все опциональны). |
Запись
| Function | Description |
|---|---|
| useAcceptAllAssetUsages | Приёмка всех received-строк отчёта («Принять все»). Уже принятые пропускаются. |
| useAcceptAssetUsage | Приёмка одной строки-станка начальником участка (received → accepted). |
| useAcceptBlock | Маркшейдерская приёмка блока (FSM under_acceptance → accepted, терминальный). Только Surveyor (cross-object, ADR-0094). Тело пустое. Инвалидирует блоки. |
| useAddBlastingEntry | Взрывные работы: тип ВВ + масса. |
| useAddDowntimeEvent | Простой: причина + интервал (endedAt > startedAt). |
| useAddDrillingEntry | Бурение: ссылается на assetUsageId. |
| useAddFuelEntry | Топливо: выдано/израсходовано (consumed ≤ issued), ссылается на assetUsageId. |
| useAddShiftAssetUsage | Использование техники (anchor): возвращает id, на который ссылаются drilling/fuel (assetUsageId) — добавляй asset-usage ДО них. Offline-устойчив; FIFO-replay сохраняет порядок энкью. |
| useAddShiftPersonnel | Персонал смены: отработанные/простойные часы по сотруднику. |
| useAddTmcUsage | Расход ТМЦ: материал + количество + единица. |
| useAdjustDailyNorm | Корректировка сменной нормы (DailyNorm; foreman ±15% по своему объекту, object-scope). |
| useAmendProductionPlan | Поправка утверждённого плана (FSM approved → approved) — версия v(n+1). delta ≤20% или инициатор-CEO → auto-approved; >20% инженером → ждё т одобрения CEO. |
| useApproveProductionPlan | Утверждение плана (FSM draft → approved) — создаёт версию v1. Инвалидирует планы. |
| useApproveProductionPlanVersion | Утверждение значительной (>20%) версии CEO (sub-FSM pending_ceo → approved_version). Тело не требуется. Только CEO. |
| useCancelWorkOrder | Отмена наряда (FSM draft |
| useCloseWorkOrder | Ручное закрытие наряда (FSM issued → closed). Тело пустое. Авто-закрытие по утверждению сменного отчёта идёт через handler. |
| useCreateBlock | Создать буровзрывной блок (FSM [*] → pending). Foreman/Engineer/Admin (PRD-BLOCK-INV-01: один активный блок на (org, productionObjectId, code) — сервер отдаёт 409 на дубль). Синхронный |
| useCreateProductionPlan | Создание черновика плана (горизонт/год/месяц). Инвалидирует список планов. |
| useCreateShiftReport | Создание черновика рапорта (parent: участок + дата + смена). 201 → рапорт. Offline-устойчив (общий scope + стабильный Idempotency-Key из vars — клади его при энкью). На успехе инвалидирует список рапортов. |
| useCreateWorkOrder | Создание черновика наряда ([*] → draft). Инвалидирует список нарядов. |
| useDeleteShiftReport | Удаление черновика (Q4) — заведён по ошибке. Жёстко удаляет рапорт со всеми строками. Разрешено ТОЛЬКО в статусе draft (не-draft → 409; откат утверждённого — сторно, не delete). 204 No Content. Инвалидирует список. |
| useEditWorkOrderAssignments | Полная замена состава наряда (EDIT_ASSIGNMENTS, только в draft). Передаётся весь набор строк целиком. Инвалидирует наряды. |
| useEditWorkOrderShift | Смена наряда — участок / дата / тип смены (EDIT_SHIFT, только в draft). Ключ документа: 409, если на новую смену уже есть живой наряд (PRD-WO-INV-01), и 422 на переносе участка у наряда с набранным составом. Инвалидирует наряды. |
| useFormShiftReport | Формирование отчёта (draft → formed) — закрывает приём от буровиков. Требует полного покрытия наряда (иначе сервер вернёт 409). |
| useIssueWorkOrder | Выдача наряда (FSM draft → issued). Требует ≥1 рабочего назначения. Тело пустое. |
| useRejectProductionPlanVersion | Отклонение значительной версии CEO (sub-FSM pending_ceo → rejected_version). reason ≥5. Только CEO. |
| useRejectShiftReport | Отклонение поданного рапорта (submitted → rejected). reason ≥5. БЕЗ саги (синхронный FSM-переход). Offline-устойчив; на успехе инвалидирует список. |
| useReopenShiftReport | Переоткрытие отчёта (formed → draft) — возобновляет приём от буровиков. |
| useRevokeAssetUsageAcceptance | Отзыв приёмки строки-станка (accepted → received) — вернуть на доработку. |
| useSendBlockToRework | Отправить скважины на перебур (FSM under_acceptance → in_progress). Только Surveyor. Создаёт цикл перебура, растит остаток блока. Инвалидирует блоки. |
| useStartBlock | Запустить блок в работу (FSM pending → in_progress). Foreman/Admin. Идемпотентно (PRD-BLOCK-INV-08): повтор на запущенном блоке — no-op. Тело пустое. Ручной страховочный путь, когда авто-триггер (первое бурение) недоступен. |
| useSubmitBlock | Подать блок на приёмку (FSM in_progress → under_acceptance). Foreman/Admin. Резервный ручной путь (обычно авто из handler accumulate-fact); PRD-BLOCK-INV-02: сервер валидирует «факт ≥ порога» (422). Тело пустое. Инвалидирует блоки. |
| useSubmitShiftReport | Подача черновика на утверждение (FSM draft → submitted). Тело пустое. Offline-устойчив; на успехе инвалидирует список рапортов. |
| useSupersedeProductionPlan | Замещение плана новым на тот же период (FSM approved → superseded). |
| useUpdateShiftAssetUsage | Дозаполнение факта строки-станка (часы/показания счётчика/оператор): якорь создаётся автостартом смены без факта, итог вносится при «Завершить смену». Допускается пока рапорт в draft и строка не принята (accepted → 409). |
| useUpdateShiftReport | Правка шапки черновика (Q4): производственный объект / дата / тип смены — если рапорт завели по ошибке. Разрешено ТОЛЬКО в статусе draft (после формирования сервер вернёт 409). Частично: шли только изменённые поля. Синхронный @Idempotent; инвалидирует список + карточку рапорта. |
Саги
| Function | Description |
|---|---|
| useApproveShiftReport | Утверждение сменного рапорта (центральная 6-шаговая approve-сага). POST даёт 202 + sagaId; хук поллит /sagas/{id}/status до терминала. Терминальный откат (failed/compensated) бросается как SagaFailedError → срабатывает onError. |
| useRejectShiftReportAfterApprove | Сторнирование утверждённого рапорта (approved → rejected). Только CEO. POST даёт 202 + rejectSagaId (компенсирующая сага); хук поллит до терминала. reason ≥10. Терминальный откат бросается как SagaFailedError → onError. |
Чтение
| Function | Description |
|---|---|
| useBlock | Один блок по id (с историей циклов перебура reworkOrders[] и накопительным фактом: factMeters проходка + factVolumeM3 взрывы). |
| useBlocks | Список буровзрывных блоков (cursor-пагинация; фильтры productionObjectId/status/ reworkActive/horizon). Foreman — scoped по своим объектам (fail-closed). |
| useCrewRoster | Ростер экипажей участка за период (ADR-0119): плоский «человек → станок → смена» по выданным и закрытым нарядам. Одна строка на человека и роль — машинист и помощник одной строки наряда приходят двумя записями. |
| useDailyNormBase | Серверно-резолвленная база суточной нормы + Foreman-диапазон ±15% (PRD-PLAN-INV-13). Чтобы Foreman не вводил базу руками: фронт читает её отсюда. Запрос идёт только когда заданы план, objectPlan и дата (иначе хук бездействует). |
| useMyShiftAnchor | Станок-якорь смены буровика из issued-наряда (operator-aware, ADR-0113/B) — источник one-tap «Начать смену». По дате находит н аряд буровика (перебор обоих типов смены на сервере), строку, где машинист = сам оператор, и возвращает станок + участок + ТИП СМЕНЫ из наряда (не с часов устройства). Тот же источник, что own-station-гейт приёмки. anchor=null — нет issued-наряда на дату / оператор в нём не машинист (кокпит покажет «наряд не выпущен»). Object-scope на сервере. |
| useMyWorkOrders | «Мои наряд-задания» (наряд-ориентированный экран буровика, BL-67) — issued-наряды буровика в окне дат (по умолчанию сегодня + следующий день, ≤14 дней) с производным статусом рапорта на каждую строку-станок (`no_report → draft_* → submitted → approved |
| useNspGrid | Поблочно-недельная НСП-сетка плана (BL-51 Этап B): по каждому доступному объекту — цель, «Распределено» (Σ аллокаций) и недели со строками бурения/взрывов. Read-only проекция. Object-scope применяется на сервере. |
| useProductionPlan | Один производственный план по id (включает историю версий versions[]). |
| useProductionPlans | Список производственных планов (cursor-пагинация; фильтры horizon/year/month/status). |
| useReworkDemand | Потребность перебура по объектам (read-проекция, compute-on-read из открытых циклов перебура): доп. ДТ (л) и коронки (шт) на остаток (remainingMeters); ВВ всегда null (ведётся в ANA). Foreman — только свои объекты (fail-closed). Опц. фильтр productionObjectId. |
| useShiftCoverage | Покрытие наряда поданными отчётами буровиков (read-only). Object-scope на сервере. |
| useShiftDaySummary | Свод смены по всем участкам (BL-80) — «единый отчёт со всех начальников участков». По строке на КАЖДЫЙ существующий рапорт даты: статус плюс показатели (строки-станки, принято из них, факт проходки, ДТ). Участка нет в ответе — рапорт на смену не подавали: отсутствие читается только наложением на справочник участков, из реестра его не видно. Отклонённые рапорты не возвращаются (слот смены свободен). Object-scope на сервере. |
| useShiftReport | Один сменный рапорт (parent) по id. Возвращает FSM-поля без line-items. |
| useShiftReportEntries | Line-items рапорта: все 7 коллекций одним вызовом GET /:id/entries. |
| useShiftReports | Список сменных рапортов PRD. |
| useWorkOrder | Один наряд по id (со строками распределения assignments[] и суммой задания totalTargetMeters). Foreman — только наряды своего объекта (fail-closed). |
| useWorkOrderDemand | Потребность ресурсов на смену по наряду (read-проекция): ДТ (л) и машино-смены считаются от Σ задания; коронки/ВВ приходят null — нет нормативов (Q1/Q2). |
| useWorkOrders | Список наряд-заданий (cursor-пагинация; фильтры productionObjectId/shiftDate/ shiftType/status). Foreman — scoped по своим объектам (fail-closed). |