ShipCore — Implementation Roadmap¶

Статус документа: Phase 3 detailed roadmap. Замінює outline-level версію після Phase 1. Pre-conditions: Phase 0 (skeleton) + Phase 1 (market+standards research) + Phase 2 (integration matrix deep) закриті 2026-05-12. 25 архітектурних рішень підтверджені (12 з check-in, 9 Phase 1 corrections, 16 Phase 2 corrections). Поточний фокус: Phase 4 entry (refactor + shipcore.compliance/ foundation).

§ 0. TL;DR Calendar Map¶

ASCII timeline — місяць-by-місяць з критичними deadlines (1-2 сесії/тиждень baseline, solo dev + AI-assistant). Дати orientative — не commitment до клієнтів, а realistic-pessimistic план з urlpdate-checkpoints після кожної phase.

2026                                                                    2027                                            2028
─────────────────────────────────────────────────────────────────────  ─────────────────────────────────────────────  ────
 05    06    07    08    09    10    11    12     01    02    03    04    05    06    07    08    09    10    11    12  Q1+
 │     │     │     │     │     │     │     │      │     │     │     │     │     │     │     │     │     │     │     │
 ✅P0
 ✅P1
 ✅P2
 ✅P3◀── 2026-05-12 (Phase 3 final concept + sub-documents — цей файл частина)
       ╔═════════╗                                                                                                       
       ║ Phase 4 ║◀── refactor ShipCore namespace + shipcore.compliance/ foundation (5 weeks)
       ║  5 wk   ║      └── Включає eTTN backends (Vchasno+M.E.Doc) — встигаємо до 2027-01-01 mandatory
       ╚═════════╝
                ╔══════════════╗                                                                                         
                ║ Phase 5      ║◀── Sea + Maersk sandbox + CargoWise migration playbook (5-6 weeks)
                ║   5-6 wk     ║      └── Pilot Wave 1 UA road carrier onboard sandbox demo
                ╚══════════════╝
                       ╔═══╗                                                                                             
                       ║5.5║◀── Дунайські TOS (1-2 weeks, parallel with end of P5)
                       ║1-2║
                       ╚═══╝
                          ╔══════╗                                                                                       
                          ║  P6  ║◀── Rail + УЗ Cargo (ГІОЦ) + Customs UA API bonus (4 weeks)
                          ║ 4 wk ║      └── може стартувати парал. з P5 коли GIOC NDA в роботі
                          ╚══════╝
                                ╔═══╗                                                                                    
                                ║P7 ║◀── Quote builder + LaneRateHistory build (3 weeks)
                                ║3wk║      └── WIN cleared як non-fit (air-cargo тільки)
                                ╚═══╝
       ─────────────────────────────────────────────────────────────  ▲                                                  
                                                                      │ 2027-01-01 eTTN UA MANDATORY ✅ (P4 deliverable)

                                       ╔══════════════════════════════════════════════════╗                              
                                       ║          Phase 8 — EU expansion v1.5             ║◀── 16 weeks revised
                                       ║   eFTI 4 connectors + ICS2 ITSP + eCMR hybrid    ║      (P2-R3 revision)
                                       ║   + NCTS broker + eBL 2 hubs + Sign-twice real   ║
                                       ║   + EU sanctions + 2 EU carriers                 ║
                                       ╚══════════════════════════════════════════════════╝
                                                                            ▲                                            
                                                                            │ 2027-07-09 eFTI MANDATORY public authorities ✅
                                                                            │   (P8 deliverable, tight але встигаємо)

                                                                                                                ╔═══════╗
                                                                                                                ║ P9+   ║
                                                                                                                ║ Awery ║
                                                                                                                ║ avia  ║
                                                                                                                ║ TBD   ║
                                                                                                                ╚═══════╝

КРИТИЧНІ КАЛЕНДАРНІ ТРИГЕРИ (verified standards-matrix.md):
─────────────────────────────────────────────────────────────────────────────────────
 ❌ 2026-06-01  ICS2 R3 mandatory для PL/RO/SK/HR/LV/LT
                → НЕ ВСТИГАЄМО. v1 = UA-only — підтверджено user 2026-05-12.
                  EU cross-border транзити переносяться у v1.5 (Phase 8).
                  Чесна позиція: пілоти не роблять UA→EU транзити через ShipCore
                  у v1, тільки UA-внутрішнє + UA→Constanța (Black Sea коридор).
 ⚠️  2026-12-30  EUDR mandatory (deforestation regulation)
                → не пряма ShipCore feature. У v1.5 додаємо EUDR data fields на
                  Booking якщо є попит. Не блокує Phase 8 entry.
 ✅ 2027-01-01  eTTN UA mandatory (всі road carriers)
                → Phase 4 deliverable. Vchasno + M.E.Doc backends. Phase 4 готова
                  не пізніше 2026-Q3 (5 weeks при 1 session/week = 2.5-5 calendar months
                  with realistic capacity). Маркер контрольний.
 ✅ 2027-07-09  eFTI mandatory для public authorities (acceptance)
                → Phase 8 deliverable. v1.5 EU expansion. Phase 8 заплановано
                  закрити Q1-Q2 2027 — встигаємо за 1-2 квартали до deadline.
                  Якщо Phase 4 пойде на місяць пізніше — переносимо v1 GA, не P8.
 📅 2030       DCSA eBL 100% adoption commitment (9 carriers)
                → довгий горизонт. CargoX+WaveBL hubs у Phase 8 покривають baseline.
                  Решта hubs (Enigio/TradeGo/IQAX) — Phase 9+.
─────────────────────────────────────────────────────────────────────────────────────

Чесна позиція по календарю:

Phase 4-7 (UA-core) = ~14-18 weeks calendar (5+5.5+4+3 weeks at 1-1.5 session/week tempo з realistic slip-room). Тобто Q3 2026 → Q1 2027.
Phase 8 (EU compliance) = ~16 weeks revised (P2-R3). Q1 → Q2/Q3 2027.
eFTI 2027-07-09 deadline — досяжний, але буфер ~1 квартал. Якщо Phase 4 ковзне на 2 місяці — Phase 8 кінчається на межі deadline.
ICS2 R3 2026-06-01 — пропускаємо свідомо (v1 UA-only). EU клієнти платять за PIlot Wave 2 (ZAMMLER) починаючи Q1 2027.
Acceleration triggers (§ 11) можуть стиснути календар у 2× при другому розробнику або у 1.5× при partnership boost.

§ 1. Phases overview (revised after Phase 2)¶

Таблиця revised effort estimates після Phase 2 corrections (особливо P2-R3 для Phase 8 та C-eFTI-byDesign для Phase 4):

Фаза	Назва	Тип	Original (P0)	Revised (P2)	Зміна	Calendar window
Phase 0	Skeleton + outline	Concept	2-3 год	✅ done 2026-05-12	—	—
Phase 1	Deep market research (4 треки) + eFTI deep dive	Research	1 сесія	✅ done 2026-05-12	—	—
Phase 2	Integration matrix deep (~25 інтеграцій)	Research	2-3 сесії	✅ done 2026-05-12	—	—
Phase 3	Final concept + sub-документи + цей roadmap	Concept	1 сесія	✅ done 2026-05-12	—	—
Phase 4	Refactor existing + `shipcore.compliance/` foundation (C-eFTI-byDesign)	Implementation	2-3 weeks	~5 weeks	+30%	2026-Q3 → 2026-Q4
Phase 5	shipcore_sea (Maersk Spot sandbox + DCSA VGM REST + CargoWise migration playbook)	Implementation	4-6 weeks	5-6 weeks	без змін	2026-Q4
Phase 5.5 ⭐ NEW	Дунайські TOS adaptation (Ізмаїл/Рені/Усть-Дунайськ) — reaction на Octopi Romania	Implementation	—	1-2 weeks	NEW	2026-Q4 (паралельно P5/P6)
Phase 6	shipcore_rail (УЗ Cargo через ГІОЦ + Customs UA API bonus)	Implementation	3-4 weeks	3-4 weeks	без змін	2026-Q4 → 2027-Q1 (parallel-capable з P5)
Phase 7	Quote builder + LaneRateHistory build (WIN cleared як не fit — air-only)	Implementation	1-3 weeks	2-3 weeks	+slight	2027-Q1
Phase 8	v1.5 EU expansion (eFTI + ICS2 + eCMR + NCTS + eBL hubs + sanctions + 2 EU carriers)	Implementation	6-10 weeks	~16 weeks	🔴 major	2027-Q1 → 2027-Q3
Phase 9+	Awery partnership (avia) + advanced analytics + Client Portal B2B	Implementation	TBD	TBD	—	2027-Q4+

Сумарно Phase 4-8: ~28-32 weeks ≈ 7-8 months at baseline tempo. Якщо акселератори спрацюють (§ 11) — компресія до 4-5 months.

Key insights з P2 corrections:

Phase 4 +30% — shipcore.compliance/ як cross-cutting sub-package, не окремий app. signxml skeleton + Дія КЕП mock + 3-projections canonical Waybill + audit log + 2 eTTN backends (Vchasno + M.E.Doc).
Phase 5.5 NEW — після Octopi expansion у Bucharest (SLS 2024) ми не можемо ігнорувати Дунайські порти як white space. Mini-phase 1-2 weeks: yard management primitives для Ізмаїл/Рені/Усть-Дунайськ.
Phase 7 WIN cleared — P2-R1 підтвердив що WIN — це air-cargo connectivity hub (e-AWB до 160+ airlines), не universal rate aggregator. LaneRateHistory будуємо tenant-private як планувалось. WIN переноситься у Phase 9+ як partner-кандидат для shipcore_avia (поряд з Awery).
Phase 8 +160% — найбільший shock з Phase 2. Original 6-10 weeks реально треба ~16 weeks: ICS2 R3 через ITSP (Descartes/AEB), NCTS через AEB broker, eCMR hybrid OLF+TransFollow, 2 eBL hubs (CargoX+WaveBL primary, не 5), Sign-twice real Дія SDK + EU QTSP partnership, eFTI 4 schema-agnostic connectors (road/rail/IWT/air).

§ 2. Phase 4 — Refactor + `shipcore.compliance/` foundation¶

Goals¶

Консолідувати existing fleet/containerhub/logistic/transport код під namespace shipcore_*. Створити thin core shipcore/ з cross-cutting compliance/ sub-package (eFTI-by-design). Закрити eTTN UA mandatory deadline 2027-01-01 через 2 backends. Закласти 3-projections canonical Waybill architecture для майбутніх phase 5-8 без refactor pain.

Scope per module¶

shipcore/ (thin core, NEW): moduли з modules/README.md § thin core — TransportUnit base, Container, Wagon (lift з transport), Vessel stub, Aircraft stub, Route (lift з fleet), LocationPoint (lift з fleet), Port, Station, Airport stub, Carrier, MarketCorridor, ShipmentEvent (UNECE codes).
shipcore.compliance/ (NEW cross-cutting, не окремий app): структура з phase2-summary.md § 2. exporters/ (efti_road/rail/iwt/air + ecmr_olf/transfollow + ettn_vchasno/medoc/edi_network + emswe) + signing/ (kep_dia_skeleton + xades + sign_twice) + mapping/ (ettn_to_ecmr + ecmr_to_efti + canonical_waybill + 3 projections) + audit.py.
shipcore_auto/ (refactor з fleet/): Driver, Waybill, Order, FuelLedger, eTTN, GPS — переехали з мінімальною disruption (modules/auto.md).
shipcore_terminal/ (refactor з containerhub/): yard, gate, demurrage primitives. C1 scope reduction — drone CV / advanced stacking dropped, big-terminal-features dropped (тільки bridge через partner API планується у Phase 8) (modules/terminal.md).
shipcore_forwarder/ (refactor з logistic/): Inquiry, Quote (stub до Phase 7), Booking, BL stub, multi-leg primitives (modules/forwarder.md).
shipcore_pricing/ (NEW skeleton): TariffPlan, TariffLine, FuelSurchargeFormula моделі — full implementation у Phase 7.
shipcore_sea/, shipcore_rail/, shipcore_avia/: empty Django apps з migrations (готують ground для Phase 5/6/9+).
Frontend shipcore/ umbrella: frontend/erp/src/config/ShipCore.ts з накладкою на existing fleet/containerhub/logistic sidebar groups + common React components (CarrierResolver, BookingTimeline, DocumentChain).
BAF Sync update: entity-mapping refresh для нових app namespaces (P2-N13 — BAF per-instance, MVP-ready).

Deliverables checklist¶

[ ] backend/shipcore/ Django app — installed (always-on), models migrated
[ ] backend/shipcore/compliance/ sub-package — skeleton + signxml + canonical Waybill
[ ] backend/shipcore_auto/ — fleet renamed/moved, all tests passing
[ ] backend/shipcore_terminal/ — containerhub renamed/moved (з C1 scope reduction)
[ ] backend/shipcore_forwarder/ — logistic renamed/moved
[ ] backend/shipcore_pricing/ — skeleton models (без logic)
[ ] backend/shipcore_sea/, _rail/, _avia/ — empty Django apps + initial migrations
[ ] compliance/exporters/ettn_vchasno.py — production-ready backend
[ ] compliance/exporters/ettn_medoc.py — production-ready backend
[ ] compliance/exporters/ettn_edi_network.py — as-needed backend
[ ] compliance/signing/kep_dia_skeleton.py — mock interface (Phase 8 → real)
[ ] compliance/signing/xades.py — signxml integration
[ ] compliance/mapping/canonical_waybill.py — 3 projections (eFTI/eCMR/eTTN) з одного canonical model
[ ] compliance/audit.py — compliance log (who/what/when signed/sent)
[ ] frontend/erp/src/config/ShipCore.ts — umbrella sidebar config + section consolidation
[ ] frontend/erp/src/components/ShipCore/{CarrierResolver,BookingTimeline,DocumentChain}.tsx — common-shared
[ ] BAF Sync entity-mapping update (dry-run mode validated)
[ ] Pilot Wave 1 UA road carrier stakeholder meeting (конкретний клієнт TBD — outreach перед Phase 4)
[ ] Documentation update: docs/dop/overview.md, docs/DOCS.md, docs/manifesto.md — додати ShipCore як vertical track
[ ] AI bundle update: docs/ai/domains/shipcore/ створено + initial architecture.md + compliance-byDesign.md

Dependencies¶

Previous phases: - Phase 3 final concept closed (✅ 2026-05-12) - Cash & Bank S6-S8 закрито (docs/todo.md) - Sales Order Architecture Phase 1 закрито (docs/todo.md)

External: - Vchasno API access (commercial subscription — pilot tenant pays) - M.E.Doc EDI gateway access (existing integration в DOP — reuse) - signxml Python library — Apache-2.0, no friction - Pilot Wave 1 UA road carrier (TBD client) management buy-in для namespace refactor

Risks + mitigations¶

Risk	Severity	Mitigation
BAF Sync entity-mapping breakage у production tenants	High	Dry-run mode для всіх mappings, staged rollout per tenant, rollback playbook
eTTN mandate 2027-01-01 не встигаємо якщо Phase 4 ковзне >2 months	High	Vchasno + M.E.Doc backends — high priority within phase. Якщо інші deliverables не встигають — режемо їх, не eTTN
3-projections canonical Waybill — over-engineering для UA-only v1	Medium	C-eFTI-byDesign підтверджена через user decision. Phase 8 без foundation = +50% rework. Risk acceptable
signxml + DSTU 4145 непрацездатний bridge	Medium	Phase 4 = skeleton/mock тільки. Real Дія SDK integration deferred до Phase 8 (P2-N6 sign-twice 2-phase rollout)
URL redirects для existing customers (/fleet/, /containerhub/)	Low	Frontend route aliases, не breaking change

Effort breakdown¶

Backend models + migrations (rename + thin core lift): 5 days
Backend shipcore.compliance/ services skeleton: 6 days
Backend API + ViewSets (registry updates): 3 days
Frontend ShipCore.ts config + sidebar consolidation: 2 days
Frontend common components: 3 days
Tests (target ≥80% line coverage у new modules): 4 days
Documentation + AI bundle update (docs/ai/domains/shipcore/): 2 days
BAF Sync mapping update + verification: 2 days
Pilot client coordination + namespace freeze decision: 1 day
Buffer для unforeseen refactor surprises: 2 days
TOTAL: 30 working days ≈ 5 calendar weeks at 1.5 day/week tempo

Calendar window¶

Phase 4 — 2026-Q3 → 2026-Q4 (5 weeks at 1-1.5 sessions/week, або 2.5 weeks at 2 sessions/week). Початок умовно червень-липень 2026. Закриття серпень-вересень 2026 у baseline scenario.

Acceptance criteria¶

Phase 4 done означає що: - [ ] All Django migrations passed без data loss (verified через staging restore) - [ ] ≥50 tests green (existing tests survived refactor + new compliance skeleton tests) - [ ] eTTN end-to-end через Vchasno backend (sandbox) — verified manually - [ ] eTTN end-to-end через M.E.Doc backend (sandbox) — verified manually - [ ] Waybill.to_efti_road(), Waybill.to_ecmr(), Waybill.to_ettn() повертають valid XML/JSON-LD (schema-agnostic, не XSD-validated до Phase 8) - [ ] AI bundle оновлено (docs/ai/domains/shipcore/architecture.md, compliance-byDesign.md) per skill update-ai-bundle - [ ] modules/auto.md, terminal.md, forwarder.md оновлено з reflect actual namespace + scope зміни - [ ] docs/DOCS.md має секцію ShipCore vertical - [ ] docs/dop/overview.md згадує ShipCore у vertical-track сегменті - [ ] Pilot Wave 1 UA road carrier — kick-off meeting проведено, scope узгоджено - [ ] BAF Sync mapping не зламано — verified production-like staging

§ 3. Phase 5 — `shipcore_sea` (Maersk Spot + DCSA VGM REST + CargoWise migration playbook)¶

Goals¶

Запустити перший real ocean vertical модуль з Maersk Spot integration (sandbox). Закрити CargoWise migration playbook як ICP-attraction deliverable (C4) — реакція на CargoWise Value Packs disruption window (grudzień 2025). DCSA VGM REST замість VERMAS EDIFACT (C5/P2-R2). eBL stub (full eBL hubs — Phase 8).

Scope per module¶

shipcore_sea/ (NEW full): Vessel, VesselSchedule, Voyage, OceanBooking, BillOfLading (BL + HouseBL), BookingConfirmation, ContainerAssignment, DemurrageEvent (modules/sea.md).
shipcore.integrations.maersk/: OAuth2 client, Spot Booking API, Container Tracking API (sandbox-only — P2-N7).
shipcore_terminal.GateTransaction: VGM submission через DCSA VGM REST 1.0 (Nov 2025 version per P2-R2). REST API, не EDIFACT.
shipcore.compliance/exporters/emswe.py: sea → EMSWe / DCSA eBL TransportDocument (НЕ через eFTI per C-eFTI-byDesign). Stub у Phase 5 — повна реалізація у Phase 8.
shipcore_forwarder/migration_from_cargowise/: importer для CargoWise XML/CSV exports (Bookings, Quotes, Clients). Mapping documentation. Migration assistant UI (Step Wizard).
Vizion aggregator stub: shipcore.integrations.vizion/ connector skeleton (full integration якщо потреба у Phase 5.5-6 для non-Maersk carriers tracking fallback).
Container Booking lifecycle: Inquiry → Quote → Booking → Confirmation → Loading → Sailing → Discharge → Release → POD (state machine через ShipmentEvent з UNECE codes).
Frontend: BookingForm, BookingList, VesselSchedule (timeline component), BLPrintPreview, CargoWiseMigrationWizard.

Deliverables checklist¶

[ ] shipcore_sea/models.py — full схема (Vessel, Voyage, OceanBooking, BillOfLading, etc.)
[ ] Migrations passed
[ ] Maersk OAuth2 client implemented + token refresh
[ ] Maersk Spot Booking API — create/read/update flow (sandbox)
[ ] Maersk Container Tracking API — event polling + ShipmentEvent persist
[ ] DCSA VGM REST 1.0 client — shipcore_terminal.GateTransaction.send_vgm()
[ ] B/L PDF print template — DCSA-compatible structure (PrintFramework, docs/planning/reports-and-print-strategy.md)
[ ] eBL stub: manual PDF generation, no hub submission (Phase 8)
[ ] migration_from_cargowise/importer.py — XML/CSV parser
[ ] migration_from_cargowise/mapping.md — field-by-field mapping documentation
[ ] Migration assistant UI (Step Wizard) — frontend
[ ] BookingForm.tsx + BookingList.tsx + VesselSchedule.tsx (timeline) + BLPrintPreview.tsx
[ ] Demurrage timers integration з containerhub.DemurrageCalculation (lift до shipcore_terminal)
[ ] Tests: 25+ для booking lifecycle (target ≥80% coverage у new code)
[ ] Pilot Wave 1 UA road carrier sandbox demo — booking lifecycle end-to-end (P2-N7)
[ ] Documentation: modules/sea.md refresh з actual impl
[ ] AI bundle: docs/ai/domains/shipcore/sea.md + linkback з architecture.md

Dependencies¶

Previous phases: - Phase 4 done (namespace + compliance skeleton)

External: - Maersk Spot sandbox account (action item з Phase 2) - Maersk OAuth2 credentials - DCSA VGM REST 1.0 documentation access (verified publicly available) - Pilot sandbox tenant configured (pilot-sandbox.eswf.dev)

Internal: - Phase 4 ShipmentEvent з UNECE codes - Phase 4 shipcore.Carrier model - Phase 4 shipcore_forwarder.Booking skeleton

Risks + mitigations¶

Risk	Severity	Mitigation
Maersk sandbox rate limits / API instability	Medium	Retry-with-backoff + circuit breaker pattern + graceful degradation до Vizion fallback
Maersk production API requires customer agreement (P2-N7)	Medium	Pilot = sandbox-only demo. Production traffic deferred до Phase 5.5-6
DCSA VGM REST 1.0 carrier adoption неоднорідна	Medium	Fallback до VERMAS EDIFACT як emergency path (deferred — не budget Phase 5)
CargoWise migration playbook не приваблює клієнтів	Low	Marketing-driven deliverable, не technical blocker. Якщо ICP не реагує — Phase 9+ pivot
Container Booking lifecycle state machine bugs у production	Medium	Stress testing з 100+ synthetic bookings перед pilot demo

Effort breakdown¶

Backend models + migrations (shipcore_sea): 5 days
Backend Maersk client + OAuth2 + Spot/Tracking APIs: 6 days
Backend DCSA VGM REST integration: 2 days
Backend EMSWe exporter stub: 1 day
Backend CargoWise migration importer: 4 days
Backend BL PDF print template (PrintFramework): 3 days
Backend API + ViewSets: 3 days
Frontend BookingForm + BookingList + VesselSchedule: 5 days
Frontend CargoWiseMigrationWizard: 2 days
Frontend BLPrintPreview: 1 day
Tests (target ≥80% coverage, 25+ tests): 5 days
Documentation + AI bundle: 2 days
Pilot demo prep + iteration: 2 days
TOTAL: 41 working days ≈ 5-6 calendar weeks

Calendar window¶

Phase 5 — 2026-Q4 (5-6 weeks at baseline tempo). Початок умовно жовтень 2026 (після Phase 4). Закриття листопад-грудень 2026.

Можлива акселерація: якщо Maersk sandbox credentials отримаємо швидко + Wave 1 pilot готовий до demo paralel — пройти за 4 calendar weeks реалістично.

Acceptance criteria¶

Phase 5 done означає що: - [ ] Booking lifecycle end-to-end (Inquiry → POD) — verified через 5+ synthetic test scenarios - [ ] Maersk Spot sandbox — booking create + tracking read працює без manual workaround - [ ] DCSA VGM REST — VGM submission працює до Maersk sandbox endpoint - [ ] CargoWise CSV importer — 1 real export з pilot або partner верно імпортовано - [ ] BL PDF generation — verified pixel-perfect з DCSA template reference - [ ] eBL stub PDF — generated, не submitted (Phase 8 deliverable) - [ ] 25+ tests green (≥80% coverage у new code) - [ ] Pilot Wave 1 UA road carrier demo проведено — feedback документований - [ ] AI bundle оновлено (docs/ai/domains/shipcore/sea.md + cargowise-migration ADR if applicable) - [ ] modules/sea.md reflects implemented scope

§ 4. Phase 5.5 — Дунайські TOS adaptation (NEW)¶

Goals¶

Reaction на Octopi Romania expansion (SLS Bucharest 2024 — Surprise 2 з Phase 1). Заповнити white space для Дунайських + сухих портів UA де нема SaaS — наша ніша (C1 + P2-N16). Mini-phase, 1-2 calendar weeks, паралельно з кінцівкою Phase 5 або стартом Phase 6.

Scope per module¶

shipcore_terminal/ Дунайські profile: yard management primitives для Ізмаїл / Рені / Усть-Дунайськ — менш sophisticated ніж Constanța / Гданськ, але достатньо для барж + sea-river vessels.
MarketCorridor.Danube settings: customs_specifics JSON з UA-RO border crossings (Reni → Galați, Ust-Dunaisk → Tulcea), Дунайська комісія regulations.
GateTransaction Дунайський flow: barge ↔ vessel ↔ truck transfer без advanced container stacking (баржі — bulk + breakbulk).
CrossDockEvent — Дунайська specifics (deferred з Phase 5 у Phase 5.5 за P2-N16).
Чорноморський Corridor playbook як internal master data: CustomsBroker entities, InsuranceProvider (Unity facility до $50M), ePhytoCertificate placeholders. НЕ external integration — internal playbook + reference data.
Frontend: lightweight Yard view (Danube profile) — без drone CV / advanced stacking.

Deliverables checklist¶

[ ] shipcore_terminal/profiles/danube.py — profile config
[ ] Yard primitives для barge ↔ vessel transfer (без advanced container stacking)
[ ] CrossDockEvent model + flow
[ ] MarketCorridor seed: Danube Corridor entity з populated customs_specifics
[ ] CustomsBroker / InsuranceProvider / ePhytoCertificate master data placeholders (reference-grade, не full implementation)
[ ] Frontend Danube Yard view (lightweight)
[ ] Tests: 8+ для Дунайські flows
[ ] Documentation: modules/terminal.md refresh
[ ] Якщо успішно — pitch презентація для Ізмаїл / Рені port management

Dependencies¶

Previous phases: - Phase 5 in progress (terminal namespace stable)

External: - Інтерв'ю з 1-2 stakeholders з Дунайських портів (бажано через зв'язки Wave 1 pilot, якщо існують) - Знання Дунайської комісії regulations (Phase 1 research material vs domain expert consult)

Risks + mitigations¶

Risk	Severity	Mitigation
Дунайські порти не зацікавлені у SaaS (low IT-готовність)	High	Free tier для перших 2-3 portів. Pitch як «cooperate w UA forwarders» а не «replace your manual workflow»
Octopi expansion не на Дунай а тільки на Constanța	Medium	Verify через Octopi public materials Q3 2026. Якщо confirmed — Phase 5.5 reduce scope до Ізмаїл/Рені тільки
Scope creep — yard management для big terminals потрапить у Phase 5.5	Medium	C1 strict — big terminals = bridge through partner API only

Effort breakdown¶

Backend Danube profile + yard primitives: 3 days
Backend CrossDockEvent model: 2 days
Backend MarketCorridor seed + customs_specifics: 1 day
Master data placeholders (CustomsBroker etc.): 1 day
Frontend Danube Yard view: 2 days
Tests (8+): 1 day
Documentation: 1 day
TOTAL: 11 working days ≈ 1-2 calendar weeks (intentionally compact)

Calendar window¶

Phase 5.5 — 2026-Q4 (паралельно з end of Phase 5 або start of Phase 6).

Acceptance criteria¶

[ ] Danube Yard view відображає barge/vessel/truck transfer state для тестового tenant
[ ] CrossDockEvent можна створити через UI або API
[ ] MarketCorridor.Danube seed готовий для будь-якого tenant
[ ] 8+ tests green
[ ] modules/terminal.md має Danube profile section
[ ] Якщо outreach пройшов — pitch deck для Ізмаїл/Рені готовий

§ 5. Phase 6 — `shipcore_rail` (УЗ Cargo через ГІОЦ + Customs UA bonus)¶

Goals¶

Стати першою SaaS для приватних UA-операторів УЗ-вагонів. УЗ Cargo direct API через ГІОЦ (B2B-договір + NDA) — P2-N11 виявив що direct path viable, не fallback aggregator. Customs UA API (Держмитслужба) — Phase 6 bonus з P2-N14.

Scope per module¶

shipcore_rail/ (NEW full): WagonOwnership, WagonAvailability, RailTariff (УЗ-tariff structure), TrainManifest, RailwayWaybill (СМГС + CIM forms) (modules/rail.md).
shipcore.integrations.uz_cargo_gioc/: direct connector через ГІОЦ (АС Клієнт УЗ + е.Портал УЗ-Карго) — B2B-договір + NDA, 2-6 тижнів onboarding per tenant (P2-N11).
shipcore.compliance/integrations/customs_ua.py: Держмитслужба API (P2-N14) — митні декларації, easy win.
Railway Waybill розширення: existing containerhub.RailwayWaybill lifted до shipcore_rail.RailwayWaybill з СМГС + CIM dual forms.
AsMAP — road, не rail (виправлення Phase 1 assumption). Rail = ГІОЦ.
Frontend: WagonAvailabilityBoard, RailTariffCalculator, TrainManifestForm, CustomsDeclarationDrawer.

Deliverables checklist¶

[ ] shipcore_rail/ models — WagonOwnership, WagonAvailability, RailTariff, TrainManifest
[ ] Migrations passed
[ ] RailwayWaybill lifted з containerhub → shipcore_rail з СМГС + CIM forms
[ ] ГІОЦ B2B-договір + NDA для pilot tenant signed (legal phase)
[ ] shipcore.integrations.uz_cargo_gioc/ connector — wagon tracking + tariff queries
[ ] shipcore.compliance/integrations/customs_ua.py — митна декларація API client
[ ] Customs declaration document flow в shipcore_forwarder.Booking
[ ] WagonAvailabilityBoard (frontend)
[ ] RailTariffCalculator (frontend)
[ ] TrainManifestForm + RailwayWaybill print template (СМГС + CIM)
[ ] Tests: 15+ для rail workflow
[ ] Documentation: modules/rail.md refresh
[ ] AI bundle: docs/ai/domains/shipcore/rail.md

Dependencies¶

Previous phases: - Phase 4 done (compliance/integrations/ folder ready) - Phase 5 in progress or done (Booking lifecycle stable)

External: - ГІОЦ B2B-договір signed (2-6 weeks per tenant — start onboarding parallel з Phase 5) - ГІОЦ NDA signed - Держмитслужба API access (publicly available, low friction) - 1+ pilot client з UA rail operations (TBD — потенційно існуючий Wave 1 carrier, якщо має rail leg)

Risks + mitigations¶

Risk	Severity	Mitigation
ГІОЦ onboarding 6 тижнів затримає Phase 6	High	Start ГІОЦ contract negotiation у Phase 4 calendar window (paralel). Не блокуємо Phase 6 commits на ГІОЦ access — robustний mock backend
ГІОЦ API stability / breaking changes (post-ЕТРАН успадкована)	Medium	Wrap у adapter pattern + version pinning. Fallback на manual paste / file import
Customs UA API undocumented edge cases	Low	M.E.Doc bridge as fallback (already integrated in DOP)
Pilot не має rail operations	Medium	Outreach до інших UA rail operators (Wave 2/3 candidate)

Effort breakdown¶

Backend models + migrations (shipcore_rail): 4 days
Backend ГІОЦ connector + mock backend: 5 days
Backend Customs UA API integration: 2 days
Backend Railway Waybill (СМГС + CIM) print templates: 3 days
Backend API + ViewSets: 2 days
Frontend WagonAvailabilityBoard: 3 days
Frontend RailTariffCalculator: 2 days
Frontend TrainManifestForm + CustomsDeclarationDrawer: 3 days
Tests (15+): 3 days
Documentation + AI bundle: 2 days
ГІОЦ legal coordination (separate track): (paralel, not counted)
TOTAL: 29 working days ≈ 3-4 calendar weeks

Calendar window¶

Phase 6 — 2026-Q4 → 2027-Q1 (3-4 weeks at baseline tempo). Може стартувати паралельно з Phase 5 якщо ГІОЦ legal track у роботі заздалегідь.

Acceptance criteria¶

[ ] УЗ Cargo wagon tracking — verified через 3+ real wagon IDs
[ ] Customs UA declaration submission — sandbox tested
[ ] Railway Waybill PDF (СМГС + CIM) — pixel-perfect з referense templates
[ ] WagonAvailabilityBoard — відображає wagon state з ГІОЦ data (live або mock)
[ ] 15+ tests green
[ ] ГІОЦ B2B-договір signed для pilot tenant
[ ] AI bundle: docs/ai/domains/shipcore/rail.md + gioc-onboarding-playbook.md (для майбутніх tenants)
[ ] modules/rail.md reflects implemented scope

§ 6. Phase 7 — Quote builder + LaneRateHistory build¶

Goals¶

UA-internal "DAT" — самостійний lane rate aggregator на історії клієнта. WIN platform cleared як non-fit (P2-R1: WIN — air-cargo connectivity hub, не universal rate aggregator). Будуємо tenant-private LaneRateHistory як планувалось у Phase 0 D8. Quote builder з трьома цифрами (floor/median/margin band) — реалізація з docs/planning/truck-freight-pricing-western.md формул.

Scope per module¶

shipcore_pricing/ (full implementation): LaneRateHistory, Quote, QuoteLine, FuelSurchargeFormula, AccessorialTariff (detention/lumper/tolls), SeasonalAdjustment (modules/forwarder.md Pricing section).
CPM/CPK calculator per Vehicle (fixed + variable + driver pay) — implement truck-freight-pricing-western.md formulas. Service у shipcore_pricing.services.cpm_calculator.
Lane median/min/max — розрахунок з історії executed bookings. Tenant-private (один tenant не бачить інших).
Quote builder UI з трьома цифрами:
Floor (мінімальна ціна — break-even з CPM/CPK)
Median (історична lane-median з історії tenant)
Margin band (suggested price з desired margin %)
FSC окремим полем (DOE-style формула, адаптована для UA palwa price index).
Frontend: QuoteBuilder, LaneRateView dashboard, FSCConfigurator, CPMCalculatorDrawer.

Deliverables checklist¶

[ ] shipcore_pricing/models.py — full схема (LaneRateHistory, Quote, QuoteLine, FuelSurchargeFormula, AccessorialTariff, SeasonalAdjustment)
[ ] Migrations passed
[ ] CPM/CPK calculator service — verified проти truck-freight-pricing-western.md formulas
[ ] LaneRateHistory aggregation service — median/min/max query
[ ] FSC formula engine — DOE-style з UA palwa adaptation
[ ] Quote document model з 3 числами + FSC окремим полем
[ ] Backend API + ViewSets
[ ] QuoteBuilder UI (інтегрований з ShipCore-Forwarder Booking)
[ ] LaneRateView dashboard (з фільтрами по corridor/equipment type/season)
[ ] FSCConfigurator UI
[ ] CPMCalculatorDrawer (на Vehicle / FixedAsset side)
[ ] Tests: 20+ для pricing calculations
[ ] Documentation: modules/forwarder.md Pricing section refresh
[ ] AI bundle: docs/ai/domains/shipcore/pricing.md

Dependencies¶

Previous phases: - Phase 5 done (Sea booking lifecycle — real lane data sources) - Phase 6 done (Rail booking lifecycle — real lane data sources) - Phase 4 shipcore.Contract.default_tariff_plan FK existing

Internal cross-cutting: - Fleet ↔ Essentials data bridge (docs/todo.md) для FixedAsset costs у CPM - Real lane data from Phase 5 + Phase 6 bookings (тривалість 2-3 місяці після Phase 5/6 launch для накопичення)

Risks + mitigations¶

Risk	Severity	Mitigation
Тонкі lane data — недостатньо для median розрахунку	High	Cold-start strategy: до 10+ bookings на lane — show «not enough data». До тих пір CPM-based floor лише
CPM формули не reflect UA-specific costs (toll, fuel arbitrage)	Medium	Iterate з Wave 1 pilot UA carrier після Phase 5 → перевірити assumptions
FSC palwa index source unreliable	Medium	Multiple sources: ОККО, WOG, USAID Ukraine fuel report — average baseline
Customers просять competitor data (не tenant-private)	Medium	Out of scope для v1. Phase 9+ Awery partnership може unlock cross-tenant aggregation (з permission)

Effort breakdown¶

Backend models + migrations: 3 days
Backend CPM/CPK calculator service: 3 days
Backend LaneRateHistory aggregation: 2 days
Backend FSC formula engine: 2 days
Backend API + ViewSets: 2 days
Frontend QuoteBuilder: 3 days
Frontend LaneRateView dashboard: 2 days
Frontend FSCConfigurator + CPMCalculatorDrawer: 2 days
Tests (20+): 3 days
Documentation + AI bundle: 1 day
TOTAL: 23 working days ≈ 2-3 calendar weeks

Calendar window¶

Phase 7 — 2027-Q1 (2-3 weeks at baseline tempo). Може почати щойно Phase 5 + Phase 6 закриті. Real lane data можливо накопичиться лише через 2-3 місяці експлуатації — Quote builder UI готовий, але LaneRateView dashboard буде sparse спочатку.

Acceptance criteria¶

[ ] CPM/CPK calculator — verified проти manual Excel calculation для 5+ Vehicle profiles
[ ] LaneRateHistory aggregation — median розрахунок з 10+ synthetic bookings
[ ] FSC formula — verified для 1 month UA palwa data
[ ] Quote document створено з 3 числами (floor/median/margin) + FSC окремим
[ ] QuoteBuilder UI — end-to-end з Booking integration
[ ] LaneRateView dashboard — фільтри працюють
[ ] 20+ tests green
[ ] AI bundle оновлено
[ ] modules/forwarder.md Pricing section reflects impl

§ 7. Phase 8 — v1.5 EU expansion (full compliance + 2 EU carriers)¶

Goals¶

Реалістичний EU offering для DE/PL/RO mid-market forwarders з UA-маршрутами. Закрити eFTI mandatory deadline 2027-07-09 для public authorities acceptance. ICS2 R3 connector through ITSP (не direct). eCMR hybrid (OLF self-host + TransFollow connector). NCTS через AEB broker. eBL 2 hubs (CargoX + WaveBL primary). Sign-twice real Дія SDK + EU QTSP partnership. Sanctions screening upgrade (EU XML feed → Sanctions.io). +2 EU carriers (Hapag-Lloyd, CMA CGM).

Це найбільша фаза за scope і effort — P2-R3 revision з 6-10 weeks до 16 weeks.

Scope per module¶

shipcore.compliance/integrations/ics2_itsp.py: ITSP connector (Descartes / AEB) для ICS2 R3 pre-arrival declarations (P2-N2).
shipcore.compliance/integrations/ncts_broker.py: AEB EU broker bridge для NCTS-P5 (P2-N5).
shipcore.compliance/exporters/efti_road/rail/iwt/air.py: real schema-agnostic export з canonical Waybill. eFTI4EU release 0.5 base schema, pluggable architecture (P2-N1).
shipcore.compliance/exporters/ecmr_olf.py: OLF self-host backend (Apache-2.0, live June 2025) — UA-internal eCMR generation.
shipcore.compliance/exporters/ecmr_transfollow.py: TransFollow connector — для cross-border партнерів які вже на TransFollow (P2-N3 hybrid).
shipcore.compliance/integrations/ebl_cargox.py: CargoX hub primary.
shipcore.compliance/integrations/ebl_wavebl.py: WaveBL hub primary. (Enigio/TradeGo/IQAX-GSBN — deferred до Phase 9+ per P2-N4.)
shipcore.compliance/signing/kep_dia_real.py: real Дія SDK integration (replaces skeleton з Phase 4).
shipcore.compliance/signing/sign_twice.py: production-ready cross-border UA→EU (КЕП + XAdES). EU QTSP partnership signed.
shipcore.compliance/sanctions/sanctions_io.py: v2 upgrade з Sanctions.io (OFAC SDN + EU + UK HMT + DPL coverage). Free EU XML feed залишається baseline.
shipcore_sea/ carriers expansion: Hapag-Lloyd Quick Quotes integration + CMA CGM two-tier (free API key → OAuth2 upgrade per P2-N8).
MSC deferred (P2-N9): MSC eBL/Booking 2.0 scheduled не live — переноситься у Phase 8.5+ після MSC DCSA готовий (~Q3 2026 за original schedule, перевірити recheck).
shipcore.compliance/integrations/tir_carnet_iru.py: IRU TIR-EPD electronic submission.
Multi-language UI: додати de / pl / ro як addон до existing en / ua.
AEO compliance fields на Client.
Frontend: ComplianceCheckDrawer, ECMRPreview, T1DeclarationForm, EFTIDataSetViewer, eBLHubPicker, SanctionsScreeningResult.

Deliverables checklist¶

Compliance core: - [ ] compliance/integrations/ics2_itsp.py — ITSP partner connector (Descartes або AEB) - [ ] compliance/integrations/ncts_broker.py — AEB EU broker - [ ] compliance/exporters/efti_road.py — full schema-agnostic - [ ] compliance/exporters/efti_rail.py — full schema-agnostic - [ ] compliance/exporters/efti_iwt.py — full schema-agnostic - [ ] compliance/exporters/efti_air.py — full schema-agnostic (uses Awery PHP ONE Record OSS якщо available — P2-N10) - [ ] compliance/exporters/ecmr_olf.py — OLF self-host backend - [ ] compliance/exporters/ecmr_transfollow.py — TransFollow connector - [ ] compliance/exporters/emswe.py — full sea EMSWe (was stub у Phase 5) - [ ] compliance/integrations/ebl_cargox.py — CargoX hub - [ ] compliance/integrations/ebl_wavebl.py — WaveBL hub - [ ] compliance/integrations/tir_carnet_iru.py — IRU TIR-EPD - [ ] compliance/signing/kep_dia_real.py — real Дія SDK - [ ] compliance/signing/sign_twice.py — production cross-border - [ ] compliance/sanctions/sanctions_io.py — v2 upgrade - [ ] EU QTSP partnership signed (XAdES production recognition)

Carriers expansion: - [ ] Hapag-Lloyd Quick Quotes integration - [ ] CMA CGM free API key → OAuth2 upgrade pathway

UI + UX: - [ ] ComplianceCheckDrawer (на Client + Booking) - [ ] ECMRPreview (PDF preview з sign status) - [ ] T1DeclarationForm - [ ] EFTIDataSetViewer (debug + validation UI) - [ ] eBLHubPicker (CargoX vs WaveBL selection per booking) - [ ] SanctionsScreeningResult (на Client + Invoice issue flow) - [ ] Multi-language UI: de + pl + ro (i18n keys) - [ ] AEO compliance fields на Client form

Testing + Documentation: - [ ] Tests: 30+ для compliance flows - [ ] modules/forwarder.md, sea.md, auto.md — refresh з EU expansion impl - [ ] AI bundle: docs/ai/domains/shipcore/compliance/ повний — eFTI, eCMR, ICS2, NCTS, eBL, signing, sanctions - [ ] docs/dop/overview.md — ShipCore v1.5 EU GA announcement section

Dependencies¶

Previous phases: - Phase 7 done (LaneRateHistory + Quote builder для EU pricing) - Phase 4 compliance foundation (skeleton, canonical Waybill, signxml)

External (CRITICAL — багато moving parts): - ITSP partner contract signed (Descartes або AEB) — start outreach Phase 6 - AEB EU broker contract signed (для NCTS-P5) - TransFollow API access (для hybrid eCMR) - OLF eCMR live deployment validated (Apache-2.0, should be available June 2025+) - CargoX hub account + credentials - WaveBL hub account + credentials - Sanctions.io commercial subscription - EU QTSP partnership signed (XAdES production trust list recognition) - Real Дія SDK access (через офіційний registration) - Hapag-Lloyd Quick Quotes API access - CMA CGM free API key (30-day trial → production OAuth2) - IRU TIR-EPD certified party status (якщо direct; інакше through broker)

Internal: - Phase 4 canonical Waybill — 3 projections validated за час Phase 5-7 expansion - Pilot Wave 2 — ZAMMLER або інший EU forwarder onboard ready

Risks + mitigations¶

Risk	Severity	Mitigation
ITSP / NCTS broker contract delays (3-6 months)	Critical	Outreach з Phase 6 calendar (parallel). Backup: temporary direct connect для 1 EU member state як stop-gap
OLF eCMR not production-ready при Phase 8 entry	High	TransFollow connector як primary fallback. OLF — long-term self-host
EU QTSP partnership не signed до 2027-07-09 deadline	Critical	Mitigation impossible — eFTI public authority acceptance потребує trusted XAdES. Якщо QTSP затримується — narrow scope до eFTI generation без sign (public authorities приймають unsigned у baseline)
MSC переноситься з Phase 8 у 8.5 (P2-N9)	Medium	Acceptable — два carriers (Hapag-Lloyd + CMA CGM) достатньо для v1.5
Real Дія SDK API change	Medium	Wrap у adapter pattern (already в Phase 4 skeleton design)
16 weeks плюс slip → запізнюємось на eFTI deadline 2027-07-09	High	Buffer 4 weeks вбудовано в estimate. Якщо Phase 4 ковзне >2 months → Phase 8 starts на місяць пізніше → переносимо v1 GA, не v1.5
Sanctions.io pricing tier mismatch	Low	EU XML feed free залишається baseline. Sanctions.io upgrade tied до paid tier customers

Effort breakdown¶

Compliance core (~10 weeks): - ICS2 ITSP integration: 5 days - NCTS broker integration: 4 days - eFTI 4 connectors (road/rail/iwt/air): 8 days - eCMR hybrid (OLF + TransFollow): 6 days - EMSWe full sea export: 4 days - eBL 2 hubs (CargoX + WaveBL): 8 days - TIR-EPD integration: 3 days - Real Дія SDK + sign-twice production: 5 days - EU QTSP partnership integration: 3 days - Sanctions.io v2 upgrade: 2 days

Carriers (~1.5 weeks): - Hapag-Lloyd Quick Quotes: 3 days - CMA CGM two-tier: 3 days

Frontend (~3 weeks): - ComplianceCheckDrawer + ECMRPreview + T1DeclarationForm: 5 days - EFTIDataSetViewer + eBLHubPicker + SanctionsScreeningResult: 4 days - Multi-language i18n (de/pl/ro): 3 days - AEO fields on Client + UI polish: 2 days

Tests + Docs (~1.5 weeks): - Tests (30+): 5 days - Documentation + AI bundle: 3 days

Buffer / unforeseen integration surprises: 5 days
TOTAL: 81 working days ≈ 16 calendar weeks (P2-R3 revised)

Calendar window¶

Phase 8 — 2027-Q1 → 2027-Q3 (16 weeks at baseline tempo). Початок Q1 2027 (після Phase 7). Закриття Q2-Q3 2027. Deadline eFTI public authorities 2027-07-09 — буфер ~1 квартал якщо все по плану.

Якщо акселератор (другий розробник) — Phase 8 можна стиснути до 10-12 weeks за рахунок розпаралелення compliance connectors.

Acceptance criteria¶

Phase 8 done означає що: - [ ] eFTI Data Set valid (schema-agnostic, eFTI4EU 0.5) — verified для road/rail/iwt/air projections - [ ] eCMR generation working через OLF backend (1+ real shipment) - [ ] eCMR working через TransFollow backend (1+ partner test) - [ ] ICS2 pre-arrival declaration submitted через ITSP — verified - [ ] NCTS-P5 declaration submitted через AEB broker — verified - [ ] eBL issued через CargoX hub — verified end-to-end - [ ] eBL issued через WaveBL hub — verified end-to-end - [ ] Sign-twice (КЕП + XAdES) — verified для UA→EU cross-border shipment - [ ] EU QTSP recognition — XAdES signature accepted by EU public authority test endpoint - [ ] Hapag-Lloyd booking — sandbox-tested - [ ] CMA CGM tracking — free API key working - [ ] Sanctions screening — Client + Invoice flow returns hits/non-hits з Sanctions.io - [ ] Multi-language: de/pl/ro UI повністю переведено - [ ] 30+ tests green - [ ] Pilot ZAMMLER (Wave 2) — onboard demo проведено - [ ] AI bundle: docs/ai/domains/shipcore/compliance/ complete - [ ] docs/dop/overview.md — ShipCore v1.5 EU GA section published

§ 8. Phase 9+ — Awery partnership + advanced¶

Goals¶

Long-horizon — Awery partnership для shipcore_avia (avoid рік розробки on greenfield air cargo module). Advanced analytics (margin per lane, carrier scorecard, empty-mile %). Client Portal B2B розширення. Mobile dispatcher app. AI-агент розширений на quote-from-email.

Candidates (detail TBD з Awery response):¶

ShipCore-Avia з Awery partnership — outreach з Phase 4-5 calendar window. P2-N10 — Awery готує OSS PHP ONE Record reference server (5× IATA hackathon winner). Phase 9+ scope: «Awery API integration + white-label opportunity», не «build AWB module». Outreach conversation з Awery (Phase 4-5 calendar window).
WIN platform partnership (alternative до Awery) — якщо Awery не зацікавлені, WIN connector для air-cargo connectivity hub (e-AWB до 160+ airlines).
Advanced analytics: Margin per lane / Carrier scorecard / Empty-mile %. Реалізація поверх Phase 7 LaneRateHistory + Phase 5/6 booking data.
Client Portal B2B: shipper self-service quote + booking (на базі existing frontend/shop/ Next.js client portal — P2-N16 не стосується, окрема story).
Mobile dispatcher app: extension з existing driver app (RN + WatermelonDB у mobile/).
AI-агент «quote з email клієнта» — extension з existing eswf_chat.ai-invoice-agent (recently added — див recent commits).
eBL hubs phase 2: Enigio + TradeGo + IQAX-GSBN (P2-N4 deferred з Phase 8).
MSC — після MSC DCSA готовий (~2026-Q3+ за original schedule, recheck).
ShipCore for SMB shipper (B2C cabinet — інтеграція з Client Portal).

Effort breakdown (orientative)¶

Awery partnership conversation + technical due diligence: 2-3 weeks
Advanced analytics dashboards: 3-4 weeks
Client Portal B2B extension: 4-6 weeks
Mobile dispatcher app: 6-8 weeks
AI quote-from-email: 2-3 weeks

TOTAL: 17-24 weeks — split into mini-phases 9.1, 9.2, etc.

Calendar window¶

Phase 9+ — 2027-Q4 і пізніше. Залежить від v1.5 GA reception і ринкового pull.

§ 9. Dependencies map (розширений з Phase 2 corrections)¶

Phase 0 (skeleton) ────► Phase 1 (research) ────► Phase 2 (integrations) ────► Phase 3 (final concept) ✅ all closed 2026-05-12
                                                                                       │
                              Cash & Bank S6-S8 ───────────────────────────────────────┤
                              Sales Order Architecture Phase 1 ────────────────────────┤
                              eTTN mandate 2027-01-01 ─────► hard dependency on P4 ────┤
                                                                                       ▼
                                                                            Phase 4 (refactor + compliance/ foundation, ~5 weeks)
                                                                                       │
                                                              ┌────────────────────────┼────────────────────────┐
                                                              ▼                        ▼                        ▼
                              Maersk sandbox ─────────► Phase 5 (Sea, 5-6 weeks)   Phase 5.5 (Danube TOS,     Phase 6 (Rail, 3-4 weeks)
                              Pilot Wave 1 carrier ────► CargoWise migration         1-2 weeks, paralel)        │
                              DCSA VGM REST 1.0 ──────► VGM submission                                          ▲
                                                              │                                                 │
                              Octopi Romania reaction ─► triggers 5.5 mini-phase                       ГІОЦ B2B-договір
                                                              │                                       (start outreach Phase 4)
                                                              ▼                                       Customs UA API
                              Real lane data (3+ months ops) ─► Phase 7 (Quote+RateView, 2-3 weeks)
                                                              │
                              ITSP partner contract ──┐       │
                              NCTS broker contract ───┤       │
                              EU QTSP partnership ────┤       │
                              CargoX + WaveBL hubs ───┤       │
                              OLF eCMR live ──────────┤       │
                              TransFollow API ────────┤       │
                              Real Дія SDK ───────────┤       │
                              Sanctions.io subscription┤      │
                              Hapag-Lloyd API ────────┤       ▼
                              CMA CGM API ────────────┴──► Phase 8 (EU expansion v1.5, 16 weeks revised) — DEADLINE 2027-07-09 eFTI
                              Pilot ZAMMLER ──────────────► onboard у Phase 8                          (буфер ~1 квартал)
                                                              │
                                                              ▼
                              Awery outreach (Phase 4-5)─► Phase 9+ (Awery partnership / advanced, TBD)

КРИТИЧНІ КАЛЕНДАРНІ DEADLINES (verified):
─────────────────────────────────────────────────────────────
❌ 2026-06-01 — ICS2 R3 mandatory (PL/RO/SK/HR/LV)             → НЕ встигаємо. v1 = UA-only підтверджено
⚠️  2026-12-30 — EUDR mandatory                                 → не блокує. Data fields у v1.5 якщо є попит
✅ 2027-01-01 — eTTN UA mandatory                              → Phase 4 deliverable (Vchasno + M.E.Doc backends)
✅ 2027-07-09 — eFTI mandatory public authorities acceptance   → Phase 8 deliverable (буфер ~1 квартал)
📅 2030       — DCSA eBL 100% adoption (9 carriers)            → CargoX + WaveBL у Phase 8 baseline OK
─────────────────────────────────────────────────────────────

§ 10. Resource constraints + acceleration triggers¶

Baseline¶

Solo dev + AI-asst. Calendar tracks 1-2 коротких сесії на тиждень.
Календарне очікування Phase 4-8 — ~7-8 місяців at this pace (28-32 working weeks).
Pilot Wave 1 — UA mid-market road carrier архетип (короткий decision cycle, низька IT-зрілість, Auto+Pricing perfect fit) — onboard parallel з Phase 4-5. Конкретний клієнт TBD.
Pilot Wave 2 — ZAMMLER forwarder (висока ARPU justifies onboarding для Sea+eBL) — onboard Phase 8.

Pilot client constraints¶

UA road carrier — Wave 1. Перший pilot — внутрішній або close-circle, для максимального контролю + швидких ітерацій. Sandbox-only Maersk demo (P2-N7). Конкретна компанія ще не визначена.
ZAMMLER — Wave 2. Wave 2 кандидати з EU exposure — onboard Phase 8 коли eCMR/T1/eFTI works.
Skip TIS / ЛЕМТРАНС як direct (занадто корпоративні, EU enterprise stack).
Phase 4 pilot — узгодити з менеджментом обраного pilot перед refactor commits (C8).

Acceleration triggers¶

Trigger	Impact на календар	Implication
Інший розробник приєднується	Compress 1.5-2×	Phase 5 + Phase 6 паралельно. Phase 8 compliance connectors розпаралелити (eCMR + ICS2 + NCTS — independent tracks)
Awery response до partnership outreach	Phase 9+ unlocks	Convert avia від stub до integration deliverable. Phase 9+ becomes concrete не TBD
Maersk customer agreement	Phase 5 production traffic	З sandbox-only demo до real production booking у Phase 5 кінці або Phase 5.5-6
ITSP / NCTS broker fast onboarding (<8 weeks)	Phase 8 starts earlier	Якщо contracts підписали у Phase 6 calendar — Phase 8 може стартувати в Q4 2026
OLF eCMR live + production-ready	Phase 8 -2 weeks	Eliminates fallback complexity. OLF self-host alone достатньо для UA-internal
EU QTSP partner pre-signed	Phase 8 -3 weeks	Sign-twice integration tested під real partnership terms
Pilot client provides early production data	Phase 7 starts earlier	LaneRateHistory accumulates з Phase 5 booking data, ready для Phase 7 build
Awery OSS PHP ONE Record server live	Phase 9+ avia -4 weeks	Reuse Awery foundation замість build from scratch
CargoX або WaveBL fast onboard	Phase 8 -1 week	Single hub primary замість 2

Deceleration risks¶

Risk	Impact
Phase 4 ковзне >2 months (BAF Sync surprises, compliance skeleton complexity)	Phase 5 starts late → Phase 8 ризик упустити 2027-07-09 deadline
ГІОЦ B2B-договір 8+ weeks	Phase 6 blocks, переносимо у Q1 2027
Pilot Wave 1 drops out / не вдалось знайти	Wave 2 ZAMMLER потребує більший effort для cold start
EU QTSP partnership не signed до Phase 8 mid	eFTI public authority acceptance ризик. Mitigation: narrow scope до eFTI без sign (acceptable baseline)

§ 11. Mandatory calendar deadlines (verified standards-matrix.md)¶

Дата	Що	ShipCore позиція	Risk
2026-06-01	ICS2 R3 mandatory pre-arrival declarations для PL/RO/SK/HR/LV/LT	❌ Не встигаємо. v1 = UA-only підтверджено user 2026-05-12. EU cross-border транзити в v1.5 (Phase 8)	Acceptable — пілоти не роблять UA→EU транзити через ShipCore у v1
2026-12-30	EUDR mandatory (deforestation regulation)	⚠️ Не пряма ShipCore feature. У v1.5 додаємо EUDR data fields на Booking якщо є попит	Low — не блокує Phase 8
2027-01-01	eTTN UA mandatory (всі road carriers)	✅ Phase 4 deliverable. Vchasno + M.E.Doc backends. Phase 4 готова не пізніше Q3 2026	Medium — критичний deliverable у Phase 4
2027-07-09	eFTI mandatory для public authorities (acceptance, не submission)	✅ Phase 8 deliverable. v1.5 EU expansion. Phase 8 планується закрити Q2-Q3 2027 — буфер ~1 квартал	High — якщо Phase 4 ковзне на 2+ months, ризик missed
2030	DCSA eBL 100% adoption commitment (9 carriers)	✅ Phase 8 CargoX + WaveBL hubs покривають baseline. Решта hubs (Enigio/TradeGo/IQAX) — Phase 9+	Low — довгий горизонт

Verified чесна позиція¶

ICS2 2026-06-01 — пропускаємо свідомо через v1 = UA-only. Це не баг, це продуктове рішення з C7.
eTTN 2027-01-01 — must hit. Якщо Phase 4 ризикує не встигнути — режемо інші deliverables (shipcore_pricing skeleton, frontend components), зберігаємо eTTN backends + skeleton compliance.
eFTI 2027-07-09 — design-time deadline. Підтекст: public authority acceptance, не operator submission obligation. Якщо EU QTSP partnership затримується — narrow scope до eFTI generation без sign (поки acceptable у baseline спецификації).
DCSA eBL 2030 — комфортний горизонт. Phase 8 hubs primary, Phase 9+ closes the rest.

§ 12. Phase update protocol¶

Кожна закрита implementation-фаза → обов'язкове оновлення: 1. Цього файлу (status + actual dates + scope deviations + lessons learned) 2. Відповідного modules/{name}.md (implemented section з actual schema) 3. docs/done.md (як з horizontal-фазами зараз) 4. docs/ai/domains/shipcore/ через skill update-ai-bundle: - architecture.md — якщо архітектурні зміни - compliance-byDesign.md — якщо compliance/ змінення - Per-domain (sea/rail/pricing/...) — окремий файл per module 5. ADR через skill update-ai-bundle § ADR section — якщо рішення нетривіальне 6. docs/DOCS.md + docs/dop/overview.md — якщо feature-level зміни (user-visible) 7. README.md цього проекту (shipcore/README.md) — status secrtion update

Phase 4 specific (з огляду на critical deadlines):¶

Прі closing Phase 4 — додати «ICS2 deadline check» section до README з confirmation чи на target track для eTTN 2027-01-01.
Якщо Phase 4 ковзає >2 weeks за оригинал baseline — escalation note до user з re-planning recommendation.

§ 13. Linkbacks¶

Source-of-truth документи¶

README — програмний overview ShipCore vertical
decisions-2026-05-12 — Phase 0 + Phase 1 corrections (D1-D12 + C1-C8 + C-eFTI-byDesign)
phase2-summary — Phase 2 corrections (P2-R1..R3 + P2-N1..N16) — особливо § 2 effort estimates revised

Research deliverables¶

Phase 1:
phase1-summary — cross-track synthesis
phase1-competitors, phase1-ua-customers, phase1-use-cases
standards-matrix — verified mandatory deadlines
efti-compliance-deep-dive — eFTI / EMSWe термінологія
Phase 2:
phase2-carrier-apis, phase2-eu-compliance, phase2-ua-integrations, phase2-tracking-partnerships

Concept + Modules¶

concept — final concept narrative (Phase 3 deliverable)
modules/README — module map
modules/auto, forwarder, sea, rail, terminal, avia

Cross-cutting plans¶

integration-matrix — ~25 інтеграцій з статусом per phase
market-research — early Phase 1 framing

External references¶

docs/planning/truck-freight-pricing-western.md — CPM/CPK formulas для Phase 7
docs/planning/reports-and-print-strategy.md — Print Framework для BL templates
docs/dop/overview.md, docs/DOCS.md, docs/manifesto.md — root-level linkbacks
docs/todo.md — Cash & Bank S6-S8 / Sales Order Architecture Phase 1 dependencies

Phase 3 detailed roadmap closed 2026-05-12. Phase 4 entry awaiting user trigger.

ShipCore — Implementation Roadmap¶

§ 0. TL;DR Calendar Map¶

§ 1. Phases overview (revised after Phase 2)¶

§ 2. Phase 4 — Refactor + shipcore.compliance/ foundation¶

Goals¶

Scope per module¶

Deliverables checklist¶

Dependencies¶

Risks + mitigations¶

Effort breakdown¶

Calendar window¶

Acceptance criteria¶

§ 3. Phase 5 — shipcore_sea (Maersk Spot + DCSA VGM REST + CargoWise migration playbook)¶

Goals¶

Scope per module¶

Deliverables checklist¶

Dependencies¶

Risks + mitigations¶

Effort breakdown¶

Calendar window¶

Acceptance criteria¶

§ 4. Phase 5.5 — Дунайські TOS adaptation (NEW)¶

Goals¶

Scope per module¶

Deliverables checklist¶

Dependencies¶

Risks + mitigations¶

Effort breakdown¶

Calendar window¶

Acceptance criteria¶

§ 5. Phase 6 — shipcore_rail (УЗ Cargo через ГІОЦ + Customs UA bonus)¶

Goals¶

Scope per module¶

Deliverables checklist¶

Dependencies¶

Risks + mitigations¶

Effort breakdown¶

Calendar window¶

Acceptance criteria¶

§ 6. Phase 7 — Quote builder + LaneRateHistory build¶

Goals¶

Scope per module¶

Deliverables checklist¶

Dependencies¶

Risks + mitigations¶

Effort breakdown¶

Calendar window¶

Acceptance criteria¶

§ 7. Phase 8 — v1.5 EU expansion (full compliance + 2 EU carriers)¶

Goals¶

Scope per module¶

Deliverables checklist¶

Dependencies¶

Risks + mitigations¶

Effort breakdown¶

Calendar window¶

Acceptance criteria¶

§ 8. Phase 9+ — Awery partnership + advanced¶

Goals¶

Candidates (detail TBD з Awery response):¶

Effort breakdown (orientative)¶

Calendar window¶

§ 9. Dependencies map (розширений з Phase 2 corrections)¶

§ 10. Resource constraints + acceleration triggers¶

Baseline¶

Pilot client constraints¶

Acceleration triggers¶

Deceleration risks¶

§ 11. Mandatory calendar deadlines (verified standards-matrix.md)¶

Verified чесна позиція¶

§ 12. Phase update protocol¶

Phase 4 specific (з огляду на critical deadlines):¶

§ 13. Linkbacks¶

Source-of-truth документи¶

Research deliverables¶

Concept + Modules¶

Cross-cutting plans¶

External references¶

§ 2. Phase 4 — Refactor + `shipcore.compliance/` foundation¶

§ 3. Phase 5 — `shipcore_sea` (Maersk Spot + DCSA VGM REST + CargoWise migration playbook)¶

§ 5. Phase 6 — `shipcore_rail` (УЗ Cargo через ГІОЦ + Customs UA bonus)¶