Tjenester

SEARCH module: routing algorithm and POST_DRONE

Appendix A to the framework spec: flowchart No. 3.1.1 — the main and only routing algorithm for any shipment needing more than one transport mode, extended to six modes without changing the graph structure.

This is an algorithm specification, not a running service: there is no points/lots database, no /search/routes API and no Go SEARCH service anywhere in this demo. The POST_DRONE contract's JSON Schema (schemas/post-drone.schema.json) and its checker (schemas/check_schema.py) are real, working files in this repository: 12 examples valid, 37 of 37 mutations rejected. ci/check_contract_text.py is also a real file, and it now runs: the proto/ directory and grpc_tools are in place, a run yields 24 checks reconciling the spec text with the schema and the proto contract, and the self-test catches 10 of 10 mutations. That run is a step of the proto job in contract.yml, i.e. part of the required check «Контракт proto модуля SEARCH».

Module subsystems (S1-S8)

ID	Name	What it covers
`S1`	Простий пошук заявок	Пошук по одному розділу за фільтрами: країна, регіон, пункт, дата, тип транспорту, тип завантаження, маса, обʼєм
`S2`	Фільтр «інші напрямки»	Два незалежні списки пунктів відправлення / призначення
`S3`	Пошук зворотних рейсів	Заявки, виставлені до пункту відправлення (ймовірний зворотний рейс)
`S4`	Пошук мультимодального маршруту	Основний алгоритм — блок-схема № 3.1.1; ланцюг заявок з 2–4 плечима по 6 видах транспорту
`S5`	Fallback «компанії напрямку»	Перелік компаній, які коли-небудь перевозили в цьому напрямку
`S6`	Fallback «можливі сполучення»	Перелік станцій/портів/аеропортів/точок дрона, між якими існує сполучення
`S7`	Ранжування	Сортування за критерієм «вартість» або «швидкість» + успадкований коефіцієнт переваги
`S8`	Збереження запиту	Історія запитів, підписка, сповіщення про нові відповідні заявки

Six transport modes in the route graph

The drone isn't a graph leg - it's post-processing of an already-found route: one implementation instead of four copies of the same condition in every branch.

Code	Name	Role in the graph	Point base
`M`	Море	Магістральне плече (гілка 1)	порти (seaport)
`F`	Авіа	Магістральне плече — альтернатива морю	аеропорти (airport)
`T`	ЖД	Фідерне плече 1-го рівня	станції (rail_station)
`A`	Авто	Фідерне плече 2-го рівня, «остання миля»	міста (city)
`D`	Дрон	Не плече графа — пост-обробка останнього авто-плеча	майданчики (drone_pad)
`X`	Мультимодальний	Не окреме плече — розділ із доступом до заявок усіх розділів	усі типи пунктів

POST_DRONE module gates (figure 3.1.1-7)

Every "no" exits the module: the auto leg is left unchanged, and no drone variant is created or replaces it.

Gate	Check	Reason code	Scenario
1	Плече останнє й вид — авто	`not_last_auto_leg`	T16
2	Зона дозволена (немає no_permit)	`no_permit`	T17
3	d ≤ range_km × drone_range_margin	`out_of_range`	T18
4	weight_t × 1000 ≤ max_payload_kg, габарити, ADR, не живі тварини	`cargo_not_allowed`	T19
5	Лот D знайдено або підставлено площадку в межах max_legs=4	`no_drone_lot / no_landing_pad / max_legs_exceeded / extra_leg_disabled`	T20, T22, T23
6	Погода у вікні вильоту (не відмова — прапорець weather_risk)	`— (weather_risk)`	T21, T26
—	Модуль вимкнено запитом	`drone_disabled`	T24
—	Перевищено бюджет модуля	`timeout`	T25

Ranking: criterion weights and flag penalties

Criterion	w_c	w_t	w_k	w_r	w_n
`cost`	0.55	0.10	0.15	0.10	0.10
`time`	0.10	0.55	0.10	0.10	0.15
`balanced`	0.30	0.30	0.15	0.15	0.10

Flag	Penalty	Rationale
`weather_risk`	0.08	Ризик погоди або невідома погода у дрон-плечі
`no_permit`	0.10	Плече без дозволу вимагає дій учасника
`customs_missing`	0.06	У плечі немає потрібного документа CMR/T1/TIR
`estimated_price`	0.03	Вартість не з лота, а з медіан link_stats

CI steps (required for merge)

Contract, branch-rule and currency/language scenarios need no database or app - only the spec text, the schema and fixtures.

Step	Command	What fails
Контракт	`schemas/validate_schema.py, schemas/check_schema.py`	невалідний приклад A.8.4.1, порушення програмної перевірки, непокрита мутація, непокритий код reason
Правило гілки	`ci/check_ruleset.py`	перевірка з правила не відповідає job-у, gate не залежить від нового job-а, фільтр paths у тригері, сценарій не описаний у ТЗ
Числа в документації	`ci/check_doc_counts.py`	твердження ТЗ про кількість обовʼязкових перевірок, діапазон правил R1–RN, кількість сценаріїв pull request чи назва групи сценаріїв відстали від фактичного складу правила гілки й конвеєрів
Валюти й мови	`schemas/check_i18n.py`	різна базова валюта в A.5 і рамковому ТЗ, застарілий курс без позначки, непокрита мутація
Текст/схема/proto	`ci/check_contract_text.py (U1–U5, N1–N5)`	розбіжність носія одиниці ваги або коду валюти між ТЗ, схемою і proto
Юніт і приймання	`тести модуля + сценарії T1–T27`	розбіжність реалізації або поведінки з контрактом (модуль ще не реалізований)