ShipCore — Прийняті рішення Phase 0 Check-in (2026-05-12)¶

Зафіксовано під час check-in діалогу 12 питаннями. Це source-of-truth для архітектурного напрямку. Phase 1 research стартує з цих припущень.

Бізнес-стратегія¶

1. Pricing model — Фіксована підписка per company (Mid/Pro tiers)¶

Не per-user, не per-shipment.
Конкретні tiers (LogiCore Mid / Pro або інші) — формуємо у Phase 4-5 після оцінки cost-to-serve.
Why: проста для клієнта, проста для білінгу, не штрафує за зростання обсягів.

2. Open vs paid модулі — Auto безкоштовний, решта платна¶

Open-source (community): shipcore_auto (= рефакторений Fleet) + thin core shipcore
Paid (subscription): shipcore_forwarder, shipcore_terminal, shipcore_sea, shipcore_rail, shipcore_avia, shipcore_pricing
Why: збереження маніфест-тези «запрошення BAS-розробників» — вони отримують безкоштовний автопарк, переходять на сучасний стек, потім підписуються на vertical плагіни.

3. Go-to-market — Відкладено¶

Прийняти рішення ближче до Phase 4 (коли вже є робочий продукт для демо).
Open question: direct sales / партнери-інтегратори / асоціації (АсМАП).

4. Pilot-клієнт — Власна або пов'язана логістична компанія¶

Перший pilot — внутрішній або close-circle, для максимального контролю + швидких ітерацій.
Implication для Phase 4-5: вибір domain-кейсів для розробки тюнимо саме під неї.

5. Brand — ShipCore (зафіксовано після trademark check)¶

Робоча назва LogiCore відхилена — конфлікт з LogiCore Inc. (Philippines, contract logistics 200-500 employees), LogiCore Corp (Huntsville US defense), Logicor (EU REIT). Усі домени .com/.io/.eu зайняті.
ShipCore: SaaS-конкурентів-однойменців нема. Semantic «ship + core» прозорий, multi-modal positioning OK.
Action item Phase 1: ручний whois для shipcore.com/.io/.app/.eu + EUIPO + Укрпатент перевірка перед public release.

Архітектура¶

6. Refactor strategy — Шлях A: Тонке спільне ядро `backend/shipcore/`¶

Тонке спільне ядро (новий Django app, ЗАВЖДИ встановлений):

backend/shipcore/
├── models/
│   ├── transport_unit.py     ← abstract base для Vehicle/Vessel/Wagon/Aircraft
│   ├── wagon.py              ← перенесено з transport/
│   ├── container.py          ← перенесено з containerhub/
│   ├── vessel.py             ← NEW
│   ├── aircraft.py           ← NEW (stub)
│   ├── route.py              ← перенесено з fleet/
│   ├── location_point.py     ← перенесено з fleet/
│   ├── port.py               ← NEW
│   ├── station.py            ← перенесено з transport.RailwayStation
│   ├── airport.py            ← NEW (stub)
│   ├── carrier.py            ← NEW
│   ├── market_corridor.py    ← NEW (Чорноморський/Дунайський/EU Land/Asia rail)
│   └── shipment_event.py     ← NEW (UNECE event codes)

Окремі Django app-и (вертикалі), кожна залежить від thin core:

backend/shipcore_auto/         ← (з fleet/) — Driver, Waybill, Order, FuelLedger, eTTN, GPS
backend/shipcore_terminal/     ← (з containerhub/) — yard, gate, stacking, demurrage, drone
backend/shipcore_forwarder/    ← (з logistic/) — Inquiry, Quote, Booking, BL, multi-leg
backend/shipcore_sea/          ← NEW — VesselSchedule, Voyage, OceanBooking, BillOfLading, Demurrage
backend/shipcore_rail/         ← NEW — RailwayWaybill, WagonAssignment, RailTariff (з УЗ)
backend/shipcore_avia/         ← stub — AWB, ULD (низький пріоритет)
backend/shipcore_pricing/      ← NEW — TariffPlan, FuelSurcharge, LaneRateHistory, CPM calculator

Why: - Чисто, без owner-залежностей між вертикалями - Wagon/Container/Vessel — об'єктивно транспортні одиниці, не належать конкретно ні Terminal ні Rail - Розблоковує всі майбутні нові вертикалі (Avia, multimodal warehouse, intermodal) - Phase 4 = ~3 тижні (помірно — не «м'який» rename за дні і не «жорсткий» за місяці)

7. Master data ролі — Carrier окремий, Shipper/Consignee/NotifyParty — ролі¶

Carrier — окрема модель shipcore.Carrier з FK на essentials.Client.
Поля: SCAC code, MC/DOT number, FMC OTI Bond, AsMAP/IRU/TIR ID, equipment list, insurance, performance scorecard, credentials для Carrier API (Maersk OAuth tokens).
Shipper / Consignee / NotifyParty — ролі на конкретному Booking:
FK на Client + опціональний прапорець is_shipper / is_consignee для UI-фільтра.
Та сама Acme Corp може бути Shipper для відправки A, Consignee для відправки B — одна картка контрагента.
Why: best practice CargoWise/Magaya — Carrier має занадто багато специфічних полів, які не fits на generic Client. Shipper/Consignee — це ролі, не сутності.

8. Tariff engine — `shipcore_pricing/` як окремий додаток у thin core¶

Моделі: TariffPlan, TariffLine, FuelSurchargeFormula, AccessorialTariff (detention/lumper/tolls), SeasonalAdjustment, LaneRateHistory
CPM calculator — окремий service, входить у pricing module
FK з Contract: essentials.Contract.default_tariff_plan → shipcore_pricing.TariffPlan
Quote pull from pricing — shipcore_forwarder.Quote.tariff_plan cite, можна override per-booking
Why: базується на research planning/truck-freight-pricing-western.md. FSC окремим полем — must-have з західних TMS. LaneRateHistory як внутрішній «DAT» (rate aggregator з виконаних рейсів) — конкурентна перевага для UA-ринку.

Інтеграції¶

9. Перша carrier integration — Maersk Spot у Phase 5¶

Why: найбільш публічний REST API + OAuth2 + sandbox, активна документація, найбільший deep-sea учасник на UA-маршрутах (Constanța feeder + Дунай).
Phase 8 (EU expansion) — Hapag-Lloyd Quick Quotes, CMA CGM API
Phase 9+ — MSC eBusiness, ONE, ZIM, COSCO, Evergreen
Концептуально ShipCore покриває ВСЕ — імплементація поетапна.

10. MarketCorridor — окремий довідник у thin core¶

Чорноморський / Дунайський / EU Land / Asia rail — first-class entities
Поля: name, region_codes (M2M), primary_ports (M2M), primary_routes (M2M), time_zone, customs_specifics (JSON)
FK з: Tariff.applicable_corridors (M2M), Booking.corridor (FK), Shipment.corridor (FK)
Why: дозволяє різні тарифи по коридорах, dashboard «operations by corridor», специфічні документи (Constanța feeder vs Gdańsk deep-sea — інші customs форми).

11. Tracking — Гібрид direct + aggregator¶

Direct CarrierAdapters: Maersk (P0), Hapag-Lloyd (P1), CMA CGM (P1), MSC (P1)
Vizion-passthrough як fallback: для всіх інших carriers (ONE, ZIM, COSCO, Evergreen, Yang Ming, HMM, ...)
Architecture: CarrierAdapter interface з двома implementations: DirectCarrierAdapter та AggregatorCarrierAdapter. Forwarder Booking workflow вибирає направление автоматично за carrier_code.
Why: реалізм SMB-ринку — не маємо ресурсів покрити 30+ carriers direct. Vizion ~$200-500/міс per ~1000 контейнерів — прийнятна маржа для UA-mid-market клієнтів.

12. Sanctions screening — basic feature у v1¶

MVP (Phase 8 EU expansion): перевірка проти EU sanctions list (publicly available XML feed) при створенні Client + перед Invoice issue
v2 upgrade: integration з paid провайдерами (Refinitiv World-Check, Comply Advantage) для повного coverage (OFAC SDN, UK HMT, DPL)
Где: shipcore.compliance sub-module у thin core
Why: EU forwarders зобов'язані робити KYC + sanctions check, інакше штрафи. Безкоштовний EU feed достатній для baseline. Paid provider — upgrade як option.

Зведена архітектура¶

DOP
├── core
│   └── essentials                                   ✅ existing
├── plugins (horizontal до Essentials)
│   ├── accounting-tax / crm / hrm / production
│   ├── client-portal / gatehouse / commerce
│   └── budgeting / consolidation                    ✅ existing
├── modules (vertical track)
│   └── ShipCore                                     📋 NEW umbrella
│       ├── shipcore                  (thin core)    📋 NEW
│       ├── shipcore_pricing                         📋 NEW
│       ├── shipcore_auto             (з fleet)      📋 refactor
│       ├── shipcore_terminal         (з containerhub) 📋 refactor
│       ├── shipcore_forwarder        (з logistic)   📋 refactor + значне розширення
│       ├── shipcore_sea                             📋 NEW
│       ├── shipcore_rail                            📋 NEW
│       └── shipcore_avia (stub)                     💡 deferred
└── integrations (external connectors)
    ├── carrier connectors                           📋 NEW
    │   ├── Maersk Spot           (Phase 5)
    │   ├── Hapag-Lloyd / CMA CGM / MSC (Phase 8)
    │   └── Vizion (aggregator fallback) (Phase 5)
    ├── rail connectors                              📋 NEW
    │   ├── Укрзалізниця Cargo    (Phase 6)
    │   └── DB Cargo / PKP / ÖBB / CFR (Phase 8+)
    ├── document standards                           📋 NEW
    │   ├── eCMR (DigiCMR/TransFollow) (Phase 8)
    │   ├── T1/NCTS Phase 5             (Phase 8)
    │   ├── TIR Carnet (IRU TIR-EPD)    (Phase 8)
    │   └── DCSA eBL                    (Phase 8+)
    ├── compliance                                   📋 NEW
    │   └── EU sanctions list (free)     (Phase 8)
    │       Refinitiv / Comply Advantage (paid, deferred)
    ├── eTTN                          ✅ existing — used by shipcore_auto
    ├── Wialon GPS                    ✅ existing — used by shipcore_auto
    ├── BAF Sync                      ⚠️ partial — bridge до shipcore_pricing
    └── M.E.Doc                       ⏳ partial — bridge до compliance

Decisions deferred (open questions для Phase 1+)¶

З первинного списку 24 open questions README § 6 — 12 закрито, лишилось 12:

Архітектура (deferred)¶

Plugin boundaries — Sea/Rail/Avia як окремі Django apps (✅ вирішено через Шлях A) — closed
Status timeline — UNECE event codes (✅ запланований у shipcore.ShipmentEvent) — closed

Інтеграції (deferred)¶

EDI vs REST — будуємо EDIFACT-парсер чи фокус на REST + EDI як legacy fallback (Phase 2 task)
eTTN coverage — як shipcore_forwarder пише ETTNDocument, поточний bind лише на Auto.TransportInvoice (Phase 4 task)
УЗ Cargo API — direct vs AsMAP-посередник vs scraping fallback (Phase 2 task)

Domain (deferred)¶

Multi-leg execution UI — як представити «rail Kyiv→Lviv → road Lviv→Польща → sea Gdańsk→Toronto» у одній Booking (Phase 5 task)
Дві ваги — gross/tare/net через Gatehouse.WeighingTicket → Forwarder.Booking (Phase 4 task)
Demurrage/Detention timers — інтеграція ContainerHub.DemurrageCalculation у Forwarder Booking lifecycle (Phase 5 task)
Cross-dock workflow — Logistic README згадує deferred; розглянути в Phase 5 (Phase 5 task)

Регуляторика (deferred)¶

eCMR провайдери — DigiCMR vs TransFollow vs власна реалізація UNECE (Phase 2 task)
T1/NCTS — direct connect vs broker через M.E.Doc (Phase 2 task)
Митні декларації — через існуючу M.E.Doc bridge або окремо (Phase 2 task)

Phase 0 check-in закрито 2026-05-12. Phase 1 (deep market research) стартує з цих припущень.

Phase 1 Corrections (закрито 2026-05-12)¶

Корекції до D1-D12 рішень на основі Phase 1 research (phase1-summary.md, efti-compliance-deep-dive.md). Усі підтверджені user'ом 2026-05-12.

C1 — shipcore_terminal scope: bridge для big TOS, own для Дунайських¶

Корекція до D6 refactor strategy.

Big terminals (Гданськ, Constanța, Одеса, Klaipėda): не власний TOS, а bridge через partner API (Navis N4, Octopi). ShipCore читає terminal state через EDI/REST, не керує операціями yard.
Власний TOS лише для Дунайських + сухих портів UA — наша ніша, де нема SaaS.
Phase 5.5 NEW — mini-phase (1-2 тижні) Дунайські TOS adaptation як reaction на Octopi expansion (SLS Bucharest 2024 — Surprise 2).
Що зміниться у modules/terminal.md: scope скорочується — drone CV / advanced stacking optimization лишається для small ports, але big-terminal-features stop investing.

C2 — shipcore_avia: Awery partnership conversation¶

Корекція до module map (avia stub).

shipcore_avia не stub-to-build, а explicit partnership target з Awery (UA-походження, ONE Record lead на IATA WCS 2026 — Surprise 4).
Phase 9+ scope = «Awery API integration + white-label opportunity», не «build AWB module».
Перш ніж Phase 9 — outreach conversation з Awery (Phase 4-5 calendar window).

C3 — Lane RateView: WIN platform research перед build¶

Корекція до D8 tariff engine.

Riege Scope інтегрував WIN platform для EU air+ocean carrier rate aggregation (Surprise 5).
Phase 7 = research WIN API + pricing + buy-vs-build decision (1-2 дні) перед shipcore_pricing.LaneRateHistory build.
Якщо WIN partnership economically viable — Phase 7 скорочується з 2-3 тижнів до 1.

C4 — CargoWise migration playbook як explicit Phase 5 deliverable¶

Нова корекція з Surprise 1 (CargoWise Value Packs grudz 2025 — disruption window).

Per-transaction billing CargoWise (+$5K/міс для mid-size) створює cohort незадоволених — ICP для ShipCore.
Phase 5 додає shipcore_forwarder.migration_from_cargowise deliverable:
Importer for CargoWise XML/CSV exports (Bookings, Quotes, Clients)
Mapping documentation
Migration assistant UI

C5 — DCSA VGM REST замість VERMAS EDIFACT¶

Корекція до integration-matrix Phase 5 SOLAS VGM.

DCSA опублікував VGM API standard (Nov 2025 — Surprise 6) — REST-based replacement для VERMAS EDIFACT.
Phase 5 shipcore_terminal.GateTransaction пише VGM через DCSA REST, не EDI.
Спрощує реалізацію: не потрібен EDI parser.

C6 — eBL interop hubs у Phase 8 (не v2 deferred)¶

Корекція до integration-matrix Phase 8.

9 carriers committed 100% eBL до 2030; перша interoperable transaction 2025-05-15 (HMM/Suzano — Surprise 7).
Phase 8 додає eBL interop через хаби: CargoX, WaveBL, Enigio, TradeGo, IQAX-GSBN.
Це робить ShipCore-Sea конкурентоспроможним з Riege/CargoWise в EU.

C7 — ICS2 timing: v1 = UA-only (calendar decision)¶

Корекція до Phase 8 timing.

ICS2 Release 3 fully operational з 2026-06-01 для PL/RO/SK/HU/HR/LT (Surprise 8).
Кожен UA→EU транзит з цієї дати потребує pre-arrival declaration.
Рішення user 2026-05-12: v1 execution = UA-only до Phase 8 ready. EU expansion = v1.5.
ShipCore-Forwarder cross-border UA→EU транзити у v1.5; у v1 — UA-внутрішнє + UA→Constanța (Black Sea коридор).

C8 — Pilot wave order: UA road carrier first (уточнення до D4)¶

Уточнення до D4.

Wave 1: UA mid-market road carrier архетип (короткий decision cycle, низька IT-зрілість, Auto+Pricing perfect fit). Профіль — див. phase1-ua-customers.md § Profile 2. Конкретний клієнт — TBD (outreach перед Phase 4 trigger).
Wave 2: ZAMMLER forwarder (висока ARPU justifies onboarding для Sea+eBL).
Skip TIS / ЛЕМТРАНС як direct (занадто корпоративні, EU enterprise stack).
Phase 4 pilot — узгодити з менеджментом обраного pilot перед refactor commits.

⚠️ Pilot identity disclaimer. Конкретна компанія-pilot Wave 1 на момент Phase 3 closure (2026-05-12) не визначена. Попередня формулювання «Інком-Сервіс» була research-архетипом, а не реальною домовленістю — виправлено 2026-05-13 після перевірки.

C-eFTI-byDesign — Compliance-by-design з Phase 4¶

Нова критична корекція. Замінює стару D12 рамку.

Точна термінологія (verified efti-compliance-deep-dive.md):¶

EU multimodal e-document framework
│
├── eFTI (Reg 2020/1056) — road / rail / IWT / air (НЕ sea!)
│       ├── road sub-domain → eCMR (UNECE Protocol 2008, UA ratified 2020-07-13)
│       │       └── UA national → eTTN (Мінінфраструктури + Vchasno/M.E.Doc/EDI NETWORK)
│       ├── rail sub-domain → CIM/SMGS digital
│       ├── inland waterway → CESNI
│       └── air → IATA ONE Record (mandatory transition з 2026)
│
└── EMSWe (Reg 2019/1239) — SEA ОКРЕМО від eFTI
        └── DCSA eBL TransportDocument

Важливо: sea — окрема regulatory framework (EMSWe), не частина eFTI. Це я раніше неправильно пояснив.

Архітектурне рішення (Phase 4 deliverable)¶

Створити backend/shipcore/compliance/ як cross-cutting sub-package (НЕ окремий Django app):

backend/shipcore/
├── compliance/
│   ├── exporters/
│   │   ├── efti_road.py     ← road waybill → eFTI Data Set (XML/JSON-LD)
│   │   ├── efti_rail.py     ← rail → eFTI Data Set
│   │   ├── efti_iwt.py      ← inland waterway → eFTI Data Set
│   │   ├── efti_air.py      ← air → eFTI Data Set
│   │   ├── ecmr.py          ← XAdES eCMR generator (signxml library)
│   │   ├── ettn.py          ← Дія КЕП eTTN (вже у shipcore_auto)
│   │   └── emswe.py         ← sea → EMSWe / DCSA eBL (НЕ eFTI!)
│   ├── signing/
│   │   ├── kep_dia.py       ← DSTU 4145 ECC (Дія КЕП)
│   │   ├── xades.py         ← XAdES через signxml
│   │   └── sign_twice.py    ← UA→EU cross-border (КЕП + XAdES)
│   ├── mapping/
│   │   ├── ettn_to_ecmr.py
│   │   ├── ecmr_to_efti.py
│   │   └── canonical_waybill.py  ← одна модель → 3 projections
│   └── audit.py             ← compliance log (хто/що/коли підписав)

Ключові принципи¶

3 projections одного canonical Waybill — не 3 окремі моделі. Waybill.to_efti_road(), Waybill.to_ecmr(), Waybill.to_ettn().
Sign-twice strategy — для cross-border UA→EU: КЕП (DSTU 4145) для UA-частини + XAdES для EU-частини. DSTU 4145 ECC ≠ NIST curves — non-interoperable.
signxml library — Python primary для XAdES.
Open Logistics Foundation eCMR (live з June 2025, Apache-2.0) — серйозний кандидат для self-host (альтернатива TransFollow €2000-6000/міс).
Phase 4 ефект: +30% effort (з 3 тижнів на ~4), але економить тижні refactor у Phase 8.
v1 execution UA-only, але архітектура eFTI-ready з Phase 4. Phase 8 додає лише connectors + UI, не схему даних.

eFTI mandatory dates (verified)¶

2027-07-09 — mandatory для public authorities (acceptance eFTI data).
Economic operators — voluntary з 2026-01, mandatory analytics 2027-2029 (не зафіксовано в primary тексті).
ShipCore Phase 8 (EU expansion v1.5) має бути ready до 2027-07-09 для PUBLIC AUTHORITIES acceptance, не для operator obligation.

Зведена таблиця Phase 1 corrections¶

Code	Корекція	Тип	Phase impact
C1	terminal scope (bridge big, own Дунайські)	scope reduction	4 + новий 5.5
C2	avia → Awery partnership	scope change	9+
C3	Lane RateView → WIN research first	research-before-build	7
C4	CargoWise migration playbook	NEW deliverable	5
C5	DCSA VGM REST	tech simplification	5
C6	eBL interop hubs	scope addition	8
C7	ICS2 timing — UA-only v1	calendar decision	8 → v1.5
C8	Pilot wave: UA road carrier архетип first (конкретний клієнт TBD)	уточнення pilot	4
C-eFTI-byDesign	shipcore.compliance/ як cross-cutting, sea-окремо-EMSWe	architectural foundation	4 (foundation), 8 (full)

Phase 1 corrections закрито 2026-05-12. Phase 2 (integration matrix deep) стартує з оновлених припущень.