Передача партий между юр.лицами

Обновлено: 17.05.2026 Статус: wave K-O4 закрыт codex-ревью 13.05, доступен на dev-стенде. Раздел показывает архитектурный flow; реальные передачи на свежем Кочарин-стенде пока не запускались — список пустой до первого live use case. Адресат: диспетчер отправляющего юр.лица, диспетчер принимающего, интегратор настройки кооперационных маршрутов.

Описывает реализацию K-O4 — передача партий между юр.лицами внутри Кочарина (ВСП → ИКС термообработка, ИП-1 → Арлиз Курган сборка и т.д.) через накопители участка с time-based будильниками.

1. Зачем это нужно

Кочарин — 5 юр.лиц + 2 ИП-кооператора. Изделие проходит несколько предприятий: например, заготовку делает ВСП, термообработку — ИКС, шлифовку — ИП-1. Каждое предприятие — отдельный tenant в AntRoute с изоляцией данных.

Inter-org handover решает три задачи:

1. Отправка — диспетчер отправляющего юр.лица переводит партию из своего пространства в shared «накопитель участка» с заранее настроенным receiver org.
2. Приёмка — диспетчер принимающего видит handover в своём списке, нажимает Receive — партия появляется в его пространстве со связанной историей передачи.
3. Time-based alarms — если приёмка не произошла в SLA-окно (по умолчанию 4-12 часов в зависимости от типа кооперации), система создаёт Notification критичности critical диспетчеру и high отправителю.

2. Архитектура (упрощённо)

• TechnologicalObjectShare — модель «один объект (например, чертёж изделия) доступен другому юр.лицу read-only». Создаётся вручную интегратором или автоматически через cooperation_routes импорта.
• InterOrgHandover — модель отдельной передачи: from_org + to_org + batch_id + status (sent/received/cancelled) + sent_at + received_at + sla_due_at + alarm_triggered_at.
• Notification — генерируется service'ом alarms; каждый Notification связан с конкретным Handover через payload.handover_id.
• /api/v1/organizations/cooperators/ — endpoint показывает какие orgs можно выбрать как to_org (это список из cooperation_routes + всех org'ов, у которых есть active share с этим юр.лицом).

3. UI flow

3.1. Endpoint Cooperators

При открытии диалога «Передать партию» frontend вызывает GET /api/v1/organizations/cooperators/. Backend возвращает orgs, для которых:

• есть запись в cooperation_routes текущей organization, OR
• есть active TechnologicalObjectShare(to_org=...) от текущей organization.

Под kocharin-integrator (superuser bypass) возвращаются все 7 Кочарин orgs.

3.2. Список Handover'ов

Раздел /planning/inter-org-handovers под диспетчером (ВСП-admin / ИКС-admin / итд.). Показывает Handover'ы, где текущая org — либо from_org, либо to_org. По умолчанию sort by created_at DESC.

Empty state — это нормально для свежего пилотного стенда

На скриншоте список пустой потому что на свежем dev-стенде Кочарин-импорт прошёл, но live-передач партий между юр.лицами через UI ещё не запускали. Архитектура и endpoint'ы готовы; первая передача появится здесь как только диспетчер ВСП отправит первую партию в ИКС.

Что в каждой строке (когда будут данные):

• handover_id (UUID, кликабельный → detail);
• from_org → to_org с org-кодами (KOC-{numCode});
• batch — артикул изделия + количество;
• status: sent (отправлено, ждёт receive) / received / cancelled;
• sent_at + sla_due_at — когда отправлено, когда истекает SLA;
• alarm — иконка если будильник сработал.

3.3. Detail Handover'а

Открывается по клику на строку. Содержит:

• header с org-кодами + batch info;
• timeline: sent → received (или sent → alarm_triggered → received);
• кнопка Receive — видна только диспетчеру to_org и только в status='sent';
• кнопка Cancel — видна только диспетчеру from_org и только в status='sent' (после receive отмена невозможна);
• linked Notifications (если будильник сработал).

Detail не снят, потому что список пустой

Когда появится первая передача, скриншот detail добавится в следующее обновление этой страницы. Архитектура endpoint'а — см. evidence ниже.

4. Time-based alarms

Management command python manage.py check_handover_alarms (запускается cron каждые 5 мин) ищет:

• Handover.status='sent';
• sla_due_at < now;
• alarm_triggered_at IS NULL.

Для каждого такого — создаёт два Notification:

• severity='critical', recipient=диспетчер to_org, payload={handover_id, batch_artikul, hours_overdue};
• severity='high', recipient=диспетчер from_org, payload={handover_id, batch_artikul, hours_overdue}.

Затем alarm_triggered_at ставится в now() — это idempotency lock против повторных алармов.

SLA по типам кооперации (из K-O4 methodology §3.4):

• Термообработка: 12 часов от sent до due;
• Шлифовка: 8 часов;
• Сборка: 24 часа;
• По умолчанию: 4 часа.

(Конкретные SLA настраиваются через DSL-конфиг — в kocharin.yaml#cooperation_routes#sla_hours.)

5. Маршрут просмотра (когда будут данные)

После того как первая партия будет отправлена через UI:

1. Под koc-4505016987-admin (диспетчер ВСП) — открыть Batch detail, нажать кнопку «Передать в кооперацию», выбрать ИКС, заполнить comment, отправить.
2. Открыть /planning/inter-org-handovers — увидеть строку в status='sent'.
3. Logout, login под koc-7203456955-admin (ИКС).
4. Открыть /planning/inter-org-handovers — увидеть ту же строку (видна в обеих orgs).
5. Открыть handover detail, нажать Receive → status переходит в 'received', batch появляется в ИКС-пространстве.
6. Если SLA истёк до receive — увидеть в обеих сессиях Notification severity=critical/high.

6. Что отложено

• UI создания handover из карточки Batch. Метод frontend есть (InterOrgTransferDialog), но в этой статье не снят — нужен живой Batch.
• Bulk receive. Сейчас только по одной handover приёмка; bulk «receive все sent для моей org» — отдельная задача.
• Email уведомления при будильнике — пока только in-app Notifications.
• Mobile push. Mobile приложение не входит в этот wave.
• History глубина. Сейчас все Handover'ы хранятся бессрочно; cleanup старше 1 года — после пилота.

7. Что искать в обратной связи

1. Достаточно ли информации в списке Handover'ов, или нужны дополнительные столбцы (например, ожидаемая дата возврата для возвратных кооперационных передач)?
2. Кнопка Receive — нужны ли дополнительные confirmation'ы (например, ввод comment'а перед receive), или одного клика достаточно?
3. Timeline detail'а — какие events важно видеть кроме sent/received/alarm/cancelled?
4. SLA-значения по умолчанию (12/8/24/4 часа) — корректны или нужно подкрутить?

Приложение. Evidence в репозитории

• docs/sprint_2026_may/closed/2026-05/K-O4-inter-org-batch-transfer.md — закрытая methodology с Block 1A/1B/2/3/4.
• docs/sprint_2026_may/closed/2026-05/K-O4-inter-org-batch-transfer.md §6 — live API walkthrough на dev: h_api=d231542a-…7e88 received, h_alarm=272c63a3-…edb5 7 critical Notifications.
• antroute_backend/operational/models/inter_org_handover.py — модель.
• antroute_backend/operational/services/handover_alarms.py — alarm logic.
• antroute_backend/operational/management/commands/check_handover_alarms.py — cron entry.
• frontend/src/features/planning/InterOrgHandoversPage.tsx — list page.
• frontend/src/features/planning/InterOrgHandoverDetailPage.tsx — detail page.
• frontend/src/features/planning/InterOrgTransferDialog.tsx — modal из Batch detail.
• frontend/src/api/cooperators.ts + frontend/src/api/interOrgHandover.ts — клиенты.
• 48 backend pytest (operational.tests) + frontend vitest для UI компонентов.