Модуль «Облік зерна» (ККУ) — інструкція менеджера-впроваджувача¶

Серія: інструкції для менеджера-продавця та впроваджувача модулів DOP. Документ 1 з ланцюга. Далі: 02 — Авто-транспорт · 03 — Логістика та консолідація. Навігація по серії — README.

Кому: менеджеру, що продає та впроваджує DOP. Не операторська інструкція й не технічна документація — це «що це, кому, як показати, як налаштувати». Усі приклади спираються на демо-дані ТОВ «Зерноплюс» (анонімізований НІБУЛОН) на демо-тенанті; інженерний blueprint засіювання — zernoplyus-grain-export-seed-blueprint.

Backend-код: shipcore_grain (vertical-плагін). Розділ в UI: «Облік зерна».

1. Що це за модуль і навіщо¶

Облік зерна (ККУ — комплекс кількісно-якісного обліку) — вертикальний модуль DOP для елеваторів, хлібоприймальних підприємств (ХПП), агрохолдингів, зернотрейдерів і портових зернотерміналів. Він веде зерно від моменту, коли машина стала на ваги, до експортного відвантаження й розрахунку за якість.

Ключова відмінність зернового обліку від звичайного складського: зерно обліковується одночасно за кількістю і за якістю (Q/Q — quantity & quality). Тонна пшениці 2 класу з вологістю 13% і тонна тієї ж пшениці з вологістю 16% — це різні товари за ціною й придатністю. Плюс зерно зберігається на давальницьких умовах (зерно на елеваторі належить різним поклажодавцям), має природну усушку, потребує складських свідоцтв (товаророзпорядчі документи під заставу), сертифікатів якості та експортного пакета (фіто/радіо/походження).

Болі клієнта, які закриває модуль¶

Біль	Як закриває DOP
Кількість і якість обліковуються в різних таблицях Excel, не звіряються	Єдиний ланцюг: приймання → лаб → сертифікат якості = одна операція, що створює партію на складі
Чиє зерно в силосі? (давальницьке зберігання)	Лоти власності (`OwnershipLot`) + лицьові рахунки поклажодавців — завжди видно, кому скільки належить
Усушка/підробка/сушіння списуються «на око»	Акти підробки/сушіння/фумігації + журнал усушки з прив'язкою до причини
Складські свідоцтва й застава — на папері	Документ «Складське свідоцтво» з життєвим циклом видано→застава→індосамент→погашення
Експортний контракт GAFTA + розрахунок за якість вручну	Контракт + шкала знижок + автоматичний розрахунок премії/дисконту за якість
Експортний пакет документів збирається руками	Фіто/радіо/сертифікат походження + перевірка готовності пакета по відвантаженню
Добова звірка бункерів (ЗПП-37)	Документ добової звірки з замороженим знімком і хешем

Орієнтири (з чим порівнювати в розмові з клієнтом)¶

LabWare/STARLIMS (LIMS для лабораторії), GrainBridge / AGRIS / Cultura Grain (зернотрейдинг + GAFTA), «Е-зерно» (держреєстр складських документів). DOP дає це єдиним модулем, зшитим з бухобліком, транспортом і морським експортом — без зоопарку інтеграцій.

2. Ключові поняття (словник для менеджера)¶

Силос (Silo) — окрема ємність зберігання на майданчику-елеваторі. Має місткість, поточне заповнення, клас зерна. Режим «окреме зберігання» (один клас/лот на силос) або «знеособлене» (commingled).
Клас зерна (GrainGrade) — товарний клас за стандартом (ДСТУ / GAFTA / USDA) з набором якісних параметрів (протеїн, клейковина, вологість, число падіння тощо).
Приймання (GrainReception) — документ заїзду партії зерна на елеватор.
Сертифікат якості (GrainQualityCertificate) — поворотна точка: коли лаборант його видає, у системі з'являється партія зерна на складі (Batch), рух запасу, лот власності й запис на лицьовому рахунку поклажодавця.
Партія (Batch) — облікова одиниця запасу на складі (з бухгалтерського блоку DOP).
Лот власності (OwnershipLot) — «чия» частина партії. Інваріант: сума відкритих лотів = кількість у партії.
Лицьовий рахунок поклажодавця (DepositorAccount) — скільки зерна кожного класу належить конкретному поклажодавцю на конкретній організації.
Усушка (ShrinkageJournal) — журнал втрат маси (вологість / сміття / переміщення / природна), завжди з причиною.

3. Що налаштувати перед стартом (довідники)¶

Довідник	UI	Що це	Залежності
Класи зерна	Master Data → Якість → Класи зерна	ДСТУ/GAFTA/USDA класи з параметрами	команда `seed_grain_grades` дає 9 базових
Силоси	Master Data → Зберігання → Силоси	ємності з місткістю + клас	потребує `gatehouse.Site` (майданчик) + `Warehouse` (обліковий склад) — створюються парою
Шкали знижок за якістю	Master Data → Якість → Шкали знижок	банди премії/дисконту за параметром (напр. протеїн ≥13.5% → +120 ₴/т)	валюта

Поза модулем, але обов'язково: номенклатура зерна (Item із класом культури), контрагенти (Client — постачальники-фермери, покупці), організація (Organization).

Підказка впроваджувачу: мінімальний набір для демо вже засівається — див. §6. Для реального клієнта: спочатку класи зерна під його стандарти, потім мапа елеваторів (майданчик → силоси), потім шкали знижок під його контракти.

4. Документообіг (повна схема)¶

 ┌─ ПОЛЕ (модуль agro_field, опційно) ────────────────────────────────────┐
 │ Поле → Сівба → Агрохімія → Жнива ──міст──▶ Приймання                    │
 └─────────────────────────────────────────────────────────────────────────┘
 ┌─ ПРОХІДНА / ВАГОВА (модуль gatehouse) ──────────────────────────────────┐
 │ Черга авто → Заїзд (ANPR) → Ваговий квиток (брутто/тара/нетто) ──міст──▶ │
 └─────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
   ПРИЙМАННЯ ─────▶ ЛАБ. ЗРАЗОК ─────▶ СЕРТИФІКАТ ЯКОСТІ  ◀── ★ створення запасу
   GrainReception   (LabSample,        GrainQualityCertificate     (Batch + рух
   draft→weighed→    Kanban-процес)    draft→issued                  + OwnershipLot
   quality_pending                                                   + лицьовий рахунок
                                                                     + заповнення силосу
                                                                     + усушка)
                                      │
        ┌─────────────┬──────────────┼──────────────┬─────────────────┐
        ▼             ▼              ▼              ▼                 ▼
   ЗБЕРІГАННЯ     ВИРОБНИЧІ АКТИ   CUSTODY        ЗВІРКА            ТОРГІВЛЯ
   Переміщення   Підробка         Складське      Добова звірка     Контракт GAFTA
   GrainTransfer Сушіння          свідоцтво      бункерів          GrainContract
                 Фумігація        WarehouseReceipt DailyBin...        │
                                  Переуступка                         ▼
                                  GrainOwnership...               Розрахунок за якість
                                                                  GrainSettlement ─▶ проводки
                                      │                            (PartyLedger/GL)
                                      ▼
                              ВІДВАНТАЖЕННЯ
                              GrainDispatch ──▶ транспорт (авто-ТТН / ЖД-накладна)
                              draft→loaded→shipped     │
                                      │                ▼
                                      ▼          (модулі fleet / shipcore_rail)
                              ЕКСПОРТНИЙ ПАКЕТ
                              Фіто / Радіо / Сертифікат походження
                                      │
                                      ▼
                              МОРСЬКИЙ ЕКСПОРТ (модуль shipcore_sea)
                              Рейс / Чартер / Коносамент / Акт сталії

Документи за етапами¶

Приймання та якість - Приймання зерна (GrainReception) — заїзд партії. Статуси: чернетка → зважено → очікує якості → проведено. Може створюватись із вагового квитка прохідної (поле «ваговий квиток») або з врожаю (модуль поля). - Сертифікат якості (GrainQualityCertificate) — лабораторний результат. Видача сертифіката = поява зерна на складі (єдина точка, де народжується запас).

Зберігання та операції - Переміщення (GrainTransfer) — силос → силос (консолідація / підготовка до відвантаження), з втратою на переміщення. - Акт підробки (GrainCleaning) — очистка, відходи 1/2/3 категорій + втрата. - Акт сушіння (GrainDrying) — зниження вологості, списання вологи. - Акт фумігації (GrainFumigation) — карантинне блокування силосу на період ізоляції.

Товаророзпорядчі (custody) - Складське свідоцтво (WarehouseReceipt) — простий/подвійний варант. Цикл: видано → застава → індосамент → погашення. - Переуступка власності (GrainOwnershipTransfer) — цесія / продаж на зберіганні / своп / банківське вивільнення. - Добова звірка бункерів (DailyBinReconciliation) — ЗПП-37: заморожений знімок усіх силосів майданчика + хеш.

Торгівля та розрахунок - Контракт (GrainContract) — GAFTA-контракт (купівля/продаж), із класом, кількістю, ціною, базисом (FOB/CIF), шкалою знижок. - Розрахунок за якість (GrainSettlement) — єдиний зерновий документ, що пише бухгалтерські проводки (PartyLedger; GL — за наявності бізнес-операції). Рахує премію/ дисконт за якість відносно базового класу контракту.

Відвантаження та експорт - Відвантаження (GrainDispatch) — списання зі складу, прив'язка транспортного документа (авто/ЖД/море). Блокується активним карантином (фумігація). - Експортний пакет — Фітосанітарний / Радіологічний / Сертифікат походження (Phytosanitary/Radiological/CertificateOfOrigin). Endpoint перевіряє готовність пакета.

Реєстр - Журнал усушки (ShrinkageJournal) — лише читання; накопичує всі події втрат.

Процеси (інтерактивний UI)¶

Карта силосів (Bin Map) — візуальна мапа заповнення силосів по власниках.
Канбан лабораторії (Lab Kanban) — рух зразка: взято → підготовка → аналіз → результати → сертифіковано.

5. Потоки інформації (звідки беруться дані й куди йдуть)¶

На вході модуля: - з прохідної/ваговой (gatehouse): ваговий квиток брутто/тара → приймання; - з поля (agro_field): врожай → приймання (власне зерно агрохолдингу); - з лабораторії: якісні параметри → сертифікат.

Усередині: сертифікат → партія/лот/лицьовий рахунок/заповнення силосу/усушка; усі складські операції коригують ці ж сутності.

На виході модуля: - у бухоблік (essentials): GrainSettlement → PartyLedger/GL; собівартість партій живить P&L; - у транспорт (fleet авто / shipcore_rail ЖД): GrainDispatch → ТТН / ЖД-накладна; - у логістику (logistic): заповнення силосів → оптимізатор консолідації читає власний запас для least-cost плану постачання; - у морський експорт (shipcore_sea): відвантаження → рейс/чартер/коносамент.

Ці стрілки — точки інтеграції з іншими модулями DOP. Деталі по транспорту й логістиці — у наступних документах серії (§8).

6. Наскрізний демо-сценарій (готовий скрипт показу)¶

Демо засівається трьома командами (інженерний опис — у blueprint):

python manage.py seed_grain_export_case   --tenant <demo>   # елеватори, приймання, цикл
python manage.py seed_railway_waybills     --tenant <demo>   # транспорт у порт
python manage.py seed_grain_lot_accumulation  --tenant <demo>   # оптимізатор постачання

Легенда: ТОВ «Зерноплюс» виконує експортний контракт — 100 000 т продовольчої пшениці + 40 000 т фуражного ячменю, Миколаїв → Єгипет, покупець GASC.

Що показати по кроках (усі цифри — з реального сіду):

Мережа елеваторів — 6 майданчиків, 12 силосів у Миколаївській/Дніпро/Полтавській областях з різною відстанню до порту. (Master Data → Силоси.)
Приймання → сертифікат — відкрити приймання, показати, що видача сертифіката якості створила партію в силосі, лот власності й запис на лицьовому рахунку. Власний запас після циклу ≈ 57 тис. т пшениці + 23 тис. т ячменю (частину вже відвантажено).
Складські операції — переміщення між силосами, акт сушіння (16.5%→13.5% вологості), акт фумігації, складське свідоцтво із заставою, переуступка.
Контракт + розрахунок — GAFTA-контракт на 100 000 т пшениці GASC; розрахунок за якість пише проводку в PartyLedger.
Карта силосів / Канбан лабораторії — інтерактивні процеси.
Зв'язок із сусідніми модулями (передзвук для наступних документів серії):
Логістика: план консолідації на 100 000 т → оптимізатор сам обрав джерела — власні 57 250 т + докупівля 42 750 т, середня собівартість доставки 8 784 ₴/т, близькі елеватори авто, далекі вагонами;
Фінал ланцюга: експортний рахунок GASC на $23 млн, собівартість зерна 800 млн ₴, податок на прибуток 18% ≈ 22.6 млн ₴, сплачений державі.

Цей сценарій — наскрізний від поля та черги авто перед прохідною до податкової проводки; зерновий модуль — його ядро.

7. Чек-лист впровадження у клієнта¶

☐ Класи зерна під стандарти клієнта (ДСТУ/GAFTA/USDA).
☐ Мапа елеваторів: майданчики (Site) → силоси з місткістю та класом.
☐ Номенклатура культур (Item) + контрагенти (постачальники, покупці).
☐ Шкали знижок за якістю під типові контракти.
☐ Режим зберігання силосів (окреме vs знеособлене) — узгодити з технологом.
☐ Ролі: ваговик, лаборант, диспетчер терміналу, бухгалтер (рольовий каталог).
☐ Інтеграція прохідної/ваговой (якщо є) → приймання.
☐ Пробний цикл: приймання → сертифікат → відвантаження на тестовому силосі.
☐ Підключення транспорту й логістики — за окремими документами серії (§8).

8. Точки інтеграції та зв'язок із серією¶

Сусідній модуль	Зв'язок із зерном	Документ серії
Авто-транспорт (`fleet`)	Відвантаження → ТТН; вхідні рейси → приймання	02 — Авто-транспорт
Логістика / консолідація (`logistic`)	Заповнення силосів → least-cost план постачання	03 — Логістика та консолідація
Залізниця (`shipcore_rail`)	Відвантаження → ЖД-накладна (hopper-вагони)	у складі документа 02/03
Морський експорт (`shipcore_sea`)	Відвантаження → рейс/чартер/коносамент	окремий документ серії
Бухоблік (`essentials`)	Розрахунок за якість → проводки; собівартість → P&L	базовий модуль (Essentials)
Прохідна (`gatehouse`)	Ваговий квиток → приймання	окремий документ серії
Поле (`agro_field`)	Врожай → приймання	окремий документ серії

9. Інтеграція у F1-довідку (план)¶

Цей документ — джерело для вбудованої довідки (кнопка F1 / Help на формах і довідниках). При інтеграції (skill add-help-article, фреймворк frontend/core/.../Help) матеріал ріжеться на статті по сутностях:

Документи (стаття-довідка + кнопка Help на формі): приймання, сертифікат якості, переміщення, акти підробки/сушіння/фумігації, складське свідоцтво, переуступка, добова звірка, контракт, розрахунок, відвантаження, експортні сертифікати.
Довідники: класи зерна, силоси, шкали знижок.
Процеси: карта силосів, канбан лабораторії.
Оглядова стаття модуля = §1–§5 цього документа (призначення + документообіг + потоки).

Кожна стаття — двомовна (*.md + *.ua.md), доменні терміни перекладаються, ідентифікатори коду лишаються в backticks. Ланцюгові посилання (на авто/логістику) у F1 перетворюються на internal-links довідки.

Наступні у серії: 02 — Авто-транспорт → 03 — Логістика та консолідація. Інженерний опис даних: blueprint засіювання Зерноплюс.