EN · RU

Технический справочник

English · Руководство · ОКТМО

Содержание

• Разбор адреса
• Слоты
• Проходы сопоставления
• Настройки
• Источники
• Артефакты прогонов
• Оформление результата
• Консольная команда
• Устройство проекта

Устройство разбора адреса, слоты, проходы сопоставления, файлы настроек и артефакты прогонов.

Разбор адреса

Сырая строка адреса раскладывается на составляющие. Порядок разбора важен: сперва отсекается хвост с номером дома, затем определяется тип и имя улицы или территории, затем населённый пункт и вышестоящая административная единица.

Что распознаётся

Типы улиц. улица, переулок, проспект, бульвар, тракт, шоссе, тупик, проезд, аллея, линия, набережная, площадь, квартал, микрорайон, километр, автодорога — со всеми обычными сокращениями (ул., пер., пр-т, б-р, наб., мкр.).

Типы территорий. тер., территория, СНТ, ДНТ, ТСН.

Типы населённых пунктов. город, посёлок, деревня, село, слобода, станица, станция, хутор, улус, местечко, кишлак, аул, аал, арбан, починок, выселок, заимка, кордон, маяк, погост, слободка, усадьба, лесоучасток, метеостанция, разъезд. Отдельно разбираются железнодорожные формы: п. ж/д ст., ж/д остановочный пункт, ж/д блокпост, ж/д будка, ж/д ветка, ж/д казарма, ж/д платформа, ж/д площадка, ж/д путевой пост, рзд.. Компактные формы гп, рп, кп, дп, пгт, нп понимаются с точками и без.

Номер дома. Хвост строки разбирается на базу и модификаторы: 10, 10а, 10/2, 10к2, 10 корп. 2, 10 стр. 1, 10 литера А. База — число, модификаторы — всё остальное, приведённое к одному виду.

Ключевое правило номера дома

Модификаторы дома нельзя схлопывать с чистым номером. 10к2 не забирает 10, и 10 не забирает 10к2 — ни на строгом проходе, ни на мягком. Мягкость проходов касается написания улицы, а не корпусов и литер.

Слоты

Слот — это одна именованная составляющая адреса. Из включённых слотов собирается адресная строка; в разложенном виде каждый слот становится колонкой.

Слоты адресной строки

Технические слоты

Умолчания

Порядок сборки адресной строки по умолчанию — порядок слотов адресной строки из таблицы выше, сверху вниз.

Включены по умолчанию все слоты, кроме microdistrict: микрорайон и квартал в российских адресах чаще дублируют улицу, чем дополняют её. Колонка микрорайона при этом остаётся — из строки исключается только значение.

Заголовки слот-колонок пишутся в полном или коротком виде, это выбирается на экране обработки эталона.

Проходы сопоставления

Движок сопоставления — Ultimate_GT_Aligner. Для каждой адресной колонки строится пул кандидатов, и строки эталона забирают из него пары.

Найденная пара немедленно изымается из пула. Один кандидат не может быть выдан дважды, а проход, отработавший раньше, не переигрывается более поздним.

Проходы идут строго по возрастанию мягкости.

Точными считаются проходы 0, 1, 2, 2C, 3 и 4. Мягкими — 2R и 5. Сводка в журнале разделяет их отдельными строками.

Веса на приблизительных проходах

При равной похожести названия улицы кандидат получает надбавки:

• совпал номер дома — плюс 50;
• совпала территория — плюс 30;
• совпали модификаторы дома (проход 5) — плюс 20;
• совпал территориальный контекст ОКТМО — надбавка от профиля области поиска.

Пара с несовместимыми территориальными кодами отбрасывается до подсчёта весов.

Строки без улицы

Если в эталонной строке номер дома есть, а улицы нет, приблизительное сравнение названий бессмысленно. Такие строки ищут кандидата с тем же номером дома, модификаторами и числами улицы, и выбирают лучшего по территориальным весам.

Настройки

config/project.yaml

address_aligner:
  city: "тюмень"              # город, вычищаемый из ключей при нормализации
  ground_truth_column: "B"    # эталонная колонка; "" = автоопределение
  target_columns: "C,D"       # адресные колонки; "" = авто
  companion_mode: "auto"      # auto | none | left | right | between
  max_auto_align_columns: 5   # сколько колонок брать справа в авто-режиме

safety:
  cleanup_managed_workspace_only: true   # чистить только папки проекта
  never_delete_original_inputs: true     # не удалять оригиналы исходников

Значения из окна имеют приоритет над файлом: пустое поле в окне означает «взять из настроек или определить автоматически», заполненное — переопределяет.

config/window_settings.json

Настройки окна: размер, язык (ru | en), тема (dark, codedark, vault, light), размер шрифта и ширина правой колонки. Окно пишет файл само; удалить его — вернуть умолчания (русский язык, тема Code Dark). Источник и назначение при запуске всегда input и output проекта: прошлый выбор не вспоминается, история путей хранится отдельно.

Прочие файлы настроек

tool_manifest.yaml — то, из чего строится окно. Каждая операция описана названием, описанием, набором полей и ссылкой на функцию сервисного слоя. Оба языка живут в одном файле парами label / label_ru. Окно не знает ни одной операции по имени: что нарисовать, говорят ключи манифеста и раскладка window_layout.yaml. Каждая операция манифеста обязана стоять в раскладке — это проверяют тесты и самопроверка окна.

Источники

Поддерживаются .xlsx, .docx, .odt, .txt, .csv, .md, .markdown и .pdf с текстовым слоем. PDF без текстового слоя не распознаётся — это не задача этой программы.

Старые .doc и .xls обрабатываются только после конвертации отдельной командой.

Временные файлы Office (~$*) пропускаются и удаляются при проверке исходников.

Двухуровневые шапки

Строка, которая не содержит значений-данных и стоит под горизонтально объединённым родительским заголовком, считается строкой подзаголовков. Её значения присоединяются к родительским заголовкам, а сама строка не попадает в данные.

Столбец «Проектная мощность, мест» над «по корпусам» становится «Проектная мощность, мест по корпусам» вместо безымянного column_5.

Артефакты прогонов

Результаты

Имена содержат метку времени ГГГГММДД_ЧЧММСС.

Отчёты в report/

Часть операций дополнительно пишет <имя результата>.summary.json рядом с книгой.

Листы аудита

Перенос колонок по адресу добавляет в результат лист AUDIT_ADDRESS_JOIN. Сбор адресов при включённой опции пишет лист отбраковки.

Оформление результата

Книги результата проходят постобработку: ширина колонок подбирается по содержимому, длинный текст переносится, высота строк растёт, статусные колонки получают цветовую заливку.

Это не косметика: без неё каждую выгрузку приходится доводить руками, а строку с длинным адресом невозможно прочитать в узкой колонке.

Консольная команда

Всё, что делает кнопка окна, делает и консольная команда address_cli.cmd: окно — её «лицо», у него нет своего способа запустить операцию. Операция идёт теми же умолчаниями полей и теми же правилами, поэтому прогон из командной строки даёт ту же книгу, что и прогон из окна.

Обычная строка вывода идёт в журнал. Строка, начинающаяся с ::address::, — служебная и несёт JSON: куда пишется журнал операции, доля работы, живая строка хода длинной стадии, итог. Итог операции — файл --result; остановка — файл --cancel-file: операция видит его и заканчивает работу в ближайшей безопасной точке. Коды выхода: 0 — готово, 1 — операция не удалась, 2 — неверный вызов, 130 — остановлено.

Правила, по которым собираются параметры запуска (умолчания, условия показа поля, порядок слотов, сброс полей нормализации в режиме «быстро», значения вне списка), живут в одном месте — system_core/core/operation_model.py, их держат тесты.

Устройство проекта

Подробная карта файлов — tools/PROJECT_FILES_GUIDE_RU.md.