Технический справочник
Технический справочник
English · Руководство · ОКТМО
Содержание
- Разбор адреса
- Слоты
- Проходы сопоставления
- Настройки
- Источники
- Артефакты прогонов
- Оформление результата
- Устройство проекта
Устройство разбора адреса, слоты, проходы сопоставления, файлы настроек и артефакты прогонов.
Разбор адреса
Сырая строка адреса раскладывается на составляющие. Порядок разбора важен: сперва отсекается хвост с номером дома, затем определяется тип и имя улицы или территории, затем населённый пункт и вышестоящая административная единица.
Что распознаётся
Типы улиц. улица, переулок, проспект, бульвар, тракт, шоссе, тупик, проезд, аллея, линия, набережная, площадь, квартал, микрорайон, километр, автодорога — со всеми обычными сокращениями (ул., пер., пр-т, б-р, наб., мкр.).
Типы территорий. тер., территория, СНТ, ДНТ, ТСН.
Типы населённых пунктов. город, посёлок, деревня, село, слобода, станица, станция, хутор, улус, местечко, кишлак, аул, аал, арбан, починок, выселок, заимка, кордон, маяк, погост, слободка, усадьба, лесоучасток, метеостанция, разъезд. Отдельно разбираются железнодорожные формы: п. ж/д ст., ж/д остановочный пункт, ж/д блокпост, ж/д будка, ж/д ветка, ж/д казарма, ж/д платформа, ж/д площадка, ж/д путевой пост, рзд.. Компактные формы гп, рп, кп, дп, пгт, нп понимаются с точками и без.
Номер дома. Хвост строки разбирается на базу и модификаторы: 10, 10а, 10/2, 10к2, 10 корп. 2, 10 стр. 1, 10 литера А. База — число, модификаторы — всё остальное, приведённое к одному виду.
Ключевое правило номера дома
Модификаторы дома нельзя схлопывать с чистым номером. 10к2 не забирает 10, и 10 не забирает 10к2 — ни на строгом проходе, ни на мягком. Мягкость проходов касается написания улицы, а не корпусов и литер.
Слоты
Слот — это одна именованная составляющая адреса. Из включённых слотов собирается адресная строка; в разложенном виде каждый слот становится колонкой.
Слоты адресной строки
| Слот | Колонка | Короткая | Что это |
|---|---|---|---|
postal_index | Postal_Index | Index | Почтовый индекс |
federal_district | Federal_District | Fed_District | Федеральный округ |
parent_subject | Parent_Subject | Parent | Вышестоящий субъект |
subject | Subject | Subject | Субъект федерации |
autonomous_okrug | Autonomous_Okrug | AO | Автономный округ |
municipality | Municipality | Municipality | Муниципальное образование |
locality | Locality | Locality | Населённый пункт |
territory | Territory | Territory | Территория, СНТ и подобное |
microdistrict | Microdistrict | Mkr_Qtr | Микрорайон, квартал |
street | Street | Street | Улица |
house | House | House | Дом целиком |
premise | Premise | Premise | Помещение, квартира |
Технические слоты
| Слот | Колонка | Короткая | Что это |
|---|---|---|---|
oktmo_code | OKTMO_Code | OKTMO | Код ОКТМО |
oktmo_name | OKTMO_Name | OKTMO_Name | Наименование по ОКТМО |
house_base | House_Base | House_No | Номер дома без модификаторов |
house_mods | House_Mods | House_Mods | Модификаторы в приведённом виде |
house_modifiers | House_Modifiers | House_Parts | Модификаторы списком |
street_numbers | Street_Numbers | Street_Nums | Числа в названии улицы |
territory_key | Territory_Key | Territory_Key | Ключ территории |
match_key | Match_Key | Match_Key | Ключ сопоставления |
Умолчания
Порядок сборки адресной строки по умолчанию — порядок слотов адресной строки из таблицы выше, сверху вниз.
Включены по умолчанию все слоты, кроме microdistrict: микрорайон и квартал в российских адресах чаще дублируют улицу, чем дополняют её. Колонка микрорайона при этом остаётся — из строки исключается только значение.
Заголовки слот-колонок пишутся в полном или коротком виде, это выбирается на экране обработки эталона.
Проходы сопоставления
Движок сопоставления — Ultimate_GT_Aligner. Для каждой адресной колонки строится пул кандидатов, и строки эталона забирают из него пары.
Найденная пара немедленно изымается из пула. Один кандидат не может быть выдан дважды, а проход, отработавший раньше, не переигрывается более поздним.
Проходы идут строго по возрастанию мягкости.
| Проход | Название | Условие совпадения |
|---|---|---|
| 0 | Исходная строка | Только в режиме сбора до сопоставления: кандидат происходит из той же строки источника, и его составляющие сходятся |
| 1 | Точная строка | Совпадение приведённых текстов адреса |
| 2 | Хэш составляющих | Совпали территория, слова улицы, числа улицы, номер дома и модификаторы |
| 2R | Мягкий хэш | То же без модификаторов в ключе — но проверка дома всё равно требует совпадения модификаторов |
| 2C | Ключевой хэш | Только в режиме сбора: улица и дом без территории. Требуется строгая проверка дома и совместимость территориальных кодов |
| 3 | Приблизительный, внутри территории | Похожесть названия улицы внутри одного территориального кластера, порог 85 |
| 4 | Приблизительный, между территориями | То же по всему пулу, порог 85, с весами |
| 5 | Мягкий | Порог 80, модификаторы дома по-прежнему защищены |
Точными считаются проходы 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/gui_settings.yaml
gui:
language: "en" # ru | en
theme: "code_dark"
emoji: false
allow_runtime_switching: true
advanced_open: false # раскрывать блок «Дополнительно» сразу
source_path: ''
destination_path: ''Прочие файлы настроек
| Файл | Что в нём |
|---|---|
config/tool_manifest.yaml | Описание всех команд, полей, подсказок и служебных функций |
config/version.json | Версия и язык корневого README |
config/path_history.json | История и закрепления путей источника и назначения |
config/ui_colors.yaml | Цвета интерфейса |
config/oktmo_current_keys.txt | Ключи поиска ОКТМО |
config/oktmo_*_pins.json | Закреплённые регионы и муниципалитеты |
tool_manifest.yaml — то, из чего строится окно. Каждая команда описана названием, описанием, набором полей и ссылкой на функцию сервисного слоя. Оба языка живут в одном файле парами label / label_ru.
Источники
Поддерживаются .xlsx, .docx, .odt, .txt, .csv, .md, .markdown и .pdf с текстовым слоем. PDF без текстового слоя не распознаётся — это не задача этой программы.
Старые .doc и .xls обрабатываются только после конвертации отдельной командой.
Временные файлы Office (~$*) пропускаются и удаляются при проверке исходников.
Двухуровневые шапки
Строка, которая не содержит значений-данных и стоит под горизонтально объединённым родительским заголовком, считается строкой подзаголовков. Её значения присоединяются к родительским заголовкам, а сама строка не попадает в данные.
Столбец «Проектная мощность, мест» над «по корпусам» становится «Проектная мощность, мест по корпусам» вместо безымянного column_5.
Артефакты прогонов
Результаты
| Префикс | Что это |
|---|---|
AddressCollection_*.xlsx | Книга собранных адресов |
AddressReference_*.xlsx | Эталонный справочник |
Имена содержат метку времени ГГГГММДД_ЧЧММСС.
Отчёты в report/
| Файл | Прогон |
|---|---|
address_collection_summary.json | Сбор адресов |
address_collection_benchmark.json | Сверка сбора с контрольной колонкой |
address_alignment_summary.json | Сопоставление адресов |
reference_normalization_summary.json | Нормализация эталона |
reference_processing_summary.json | Обработка эталона |
table_comparison_summary.json | Сравнение двух таблиц |
safe_table_join_summary.json | Перенос колонок по адресу |
legacy_office_conversion_report.json | Конвертация DOC/XLS |
rosstat_oktmo_update_summary.json | Обновление реестра ОКТМО |
Часть операций дополнительно пишет <имя результата>.summary.json рядом с книгой.
Листы аудита
Перенос колонок по адресу добавляет в результат лист AUDIT_ADDRESS_JOIN. Сбор адресов при включённой опции пишет лист отбраковки.
Оформление результата
Книги результата проходят постобработку: ширина колонок подбирается по содержимому, длинный текст переносится, высота строк растёт, статусные колонки получают цветовую заливку.
Это не косметика: без неё каждую выгрузку приходится доводить руками, а строку с длинным адресом невозможно прочитать в узкой колонке.
Устройство проекта
| Слой | Где | За что отвечает |
|---|---|---|
| Окно | system_core/ui_nicegui/ | Интерфейс, рабочие папки, журнал, артефакты |
| Сервисы | system_core/services/ | Связь окна с движками, отчёты, параметры |
| Адресный движок | system_core/address_engine/ | Разбор, слоты, ОКТМО, справочник, сбор |
| Сопоставление | system_core/Ultimate_GT_Aligner.py | Проходы сопоставления и перенос связанных колонок |
| Перенос по адресу | system_core/safe_table_join.py | Сравнение таблиц и перенос колонок через Excel |
| Ядро | system_core/core/ | Задания, пути, кодировки, манифест |
Подробная карта файлов — tools/PROJECT_FILES_GUIDE_RU.md.