EN · RU

Руководство пользователя

English · Описание · ОКТМО · Справочник

Содержание

• 1. Запуск
• 2. Окно и рабочие папки
• 3. Как устроена карточка операции
• 4. Операции
• 5. Обслуживание
• 6. Порядок работы

Программа работает окном: операции выбираются мышью, столбцы задаются буквами Excel, результат уходит в отдельную папку. Править файлы настроек для обычной работы не требуется. Те же операции запускаются и без окна — консольной командой (см. Справочник).

1. Запуск

Start.exe в корне проекта открывает окно программы. Если окно уже открыто, второй запуск выводит его вперёд, а не открывает второе. При первом запуске окно русское; кнопки RU и EN справа в заголовке переключают язык на лету, выбор запоминается.

Если окно не появилось или в журнале написано, что нет Python проекта, смотрите Установку.

2. Окно и рабочие папки

Окно состоит из трёх частей.

Заголовок. Название, версия и значки машины: дата снимка реестра ОКТМО и наличие Excel и Word (зелёная точка — на месте; Excel нужен переносу колонок и сравнению таблиц, Word — конвертации старых .doc). Справа: СЕРВИС (открыть папки программы, очистить input и output), Aa (размер шрифта: обычный, крупнее, мельче), RU / EN, смена темы и ABOUT (версия, папки, автор, лицензия).

Разделы. Под заголовком пять больших кнопок: ИСТОЧНИКИ, СБОР, ЭТАЛОН, СОПОСТАВЛЕНИЕ, ОКТМО. Если в разделе несколько операций, под ними стоит вторая строка — вкладки операций.

Две колонки. Слева — карточка выбранной операции. Справа — рабочая зона (ИСТОЧНИК и НАЗНАЧЕНИЕ), РЕЗУЛЬТАТ и ЖУРНАЛ. Внизу — строка состояния: во время работы в ней ход, время и кнопка СТОП.

Рабочие папки

Проект работает с шестью управляемыми папками:

ИСТОЧНИК — откуда операции берут таблицы и документы: папка или один файл. НАЗНАЧЕНИЕ — куда они кладут результат. При запуске это всегда input и output проекта: прошлый выбор не вспоминается. Путь можно выбрать кнопкой папки (у источника ещё и кнопкой файла), вписать в строку, выбрать из истории или бросить файл либо папку прямо в окно. Путь можно закрепить булавкой — закреплённые идут в списке первыми — и открыть в проводнике. История путей хранится в config/path_history.json. Пока идёт операция, пути не меняются.

Кнопки под путями:

Пробелы и кириллица в путях поддерживаются.

Проверяйте список перед запуском. Команда работает с подготовленным набором файлов, а не с последним, который вы открывали в проводнике.

3. Как устроена карточка операции

Каждая операция открывается одинаково.

• Сверху — название, строка «для чего» и справа залитая кнопка ЗАПУСТИТЬ (Ctrl+Enter). Объяснения полей и кнопок — в подсказках: они появляются, если задержать указатель.
• Поля сгруппированы рамками по смыслу: Файлы, Листы, Колонки, Строки, Опции, Режим. Рамки встают в одну, две или три колонки по ширине окна. У короткого поля подпись слева; выбор из нескольких вариантов и наборы флажков подписаны сверху. Маленькая оранжевая точка у поля — значение отличается от умолчания.
• Дополнительно — поля, которые обычно не нужны: пути к папкам данных, ручные переопределения.
• ЖУРНАЛ справа — ход операции в реальном времени; длинная стадия показывает одну живую строку, а не сотню одинаковых. Вкладки LOGS, REPORT и CONFIG открывают папки, кнопки справа копируют журнал, очищают панель (файлы в logs остаются) и разворачивают журнал на всю колонку.
• РЕЗУЛЬТАТ — итог последней операции: что она нашла и сколько. Кнопки: ОТЧЁТ (сводка отчёта), ПАПКА (папка, куда легли книги), В ИСТОЧНИК (сделать эту папку источником следующей операции); ниже — ОЧИСТИТЬ ПУСТЫЕ СТРОКИ и УПАКОВАТЬ РЕЗУЛЬТАТЫ (см. Обслуживание).

Одновременно выполняется одна операция. Пока идёт прогон, другая не запустится. СТОП просит операцию закончить в ближайшей безопасной точке: готовые книги остаются, свои Excel и Word операции закрываются. Закрыть окно во время работы можно — оно спросит и закроется, когда операция остановится.

Операции, которые изменяют управляемую рабочую область, спрашивают подтверждение и показывают, что именно будет затронуто.

Как задаются колонки

Буквами, как в Excel: B, C,D, AC. Порядковые номера тоже принимаются. Несколько колонок — через запятую.

Пустое поле почти всегда означает автоматический режим, а не ошибку.

Там, где есть поле «заголовок», колонку можно выбрать по названию из первой строки книги. Явно заданная буква имеет приоритет над заголовком.

4. Операции

4.1. ОКТМО / ключи проекта

Реестр территорий, ключи поиска и пины. Реестр скачивается операцией ОБНОВИТЬ РОССТАТ и обновляется ею же, кэш перестраивается сразу.

Это отдельный документ: ОКТМО и ключи проекта.

4.2. Сбор адресов

Рекурсивно собирает адресоподобные значения из XLSX, DOCX, ODT, TXT, CSV, MD и PDF с текстовым слоем, объединяет свидетельства по слотам, отбрасывает неполные строки и пишет книгу адресов.

Применяется, когда сначала нужна инвентаризация, а не сопоставление.

Действие

• Создать новую таблицу — собрать всё с нуля.
• Добавить адреса к готовой — дописать собранное в существующую книгу.

Источники. «Папка источников» — необязательная папка для рекурсивного обхода; пусто означает всю папку исходников. «Папка адресной таблицы» — где лежит готовая книга адресов.

Колонки. «Адресные колонки» ограничивают разбор конкретными колонками XLSX; пусто — сканируются все ячейки и все поддерживаемые файлы. Для режима дописывания задаются «Колонка собранного адреса» и «Целевая адресная колонка».

Слоты. Одно поле — Линейка адреса. Вверху она показывает, как запишется адрес (образец, менять его нельзя). Под образцом — по фишке на каждый слот иерархии: галочка включает слот, число справа — его место среди включённых, а саму фишку можно перетащить, чтобы поменять порядок. Ниже — «Технические ключи» (код ОКТМО, основание дома и другие): у них только галочки. Кнопка со стрелкой возвращает включённые слоты и порядок к умолчаниям манифеста. Полный список слотов — в Справочнике.

Опции

Эталон для сверки. Необязательная книга с контрольной адресной колонкой. Используется только для оценки качества сбора и пишет report/address_collection_benchmark.json.

Результат. Книга AddressCollection_*.xlsx в папке результата и отчёт report/address_collection_summary.json.

После сбора проверьте: пустые значения, дубли, ячейки с несколькими адресами и строки, где есть организация, но нет адреса.

4.3. Сопоставление адресов

Основной режим. Сравнивает адресные колонки с эталонной, переставляет строки так, чтобы адреса встали напротив своих пар, и переносит связанные колонки вместе с ними.

Колонки. «Колонка GT» — эталонная адресная колонка (пусто = автоопределение). «Адресные колонки» — что сопоставлять; пусто означает взять до пяти колонок справа от эталона.

Режим выравнивания

• Быстрое выравнивание — сопоставление без дополнительной обработки.
• Выравнивание + нормализация — тот же поиск, затем очистка адресных колонок результата.

Связанные колонки. Значения из связанных колонок едут вместе с найденным адресом, чтобы данные не разъехались.

Последний режим отвечает на частый случай: эталон в A, адрес в AC, и всё B:AB должно переехать вместе с AC.

Поле «Сателлитные колонки» задаёт связи явно, если автоматика не подходит.

Выравнивание и нормализация. «Нормализовать до сопоставления» — более медленный режим с общим нормализатором. «Собрать до сопоставления» строит чистых кандидатов из выбранных колонок перед поиском; «Весь документ» расширяет сбор на всю книгу. «Город по умолчанию» задаёт название города, которое вычищается из ключей при нормализованном сопоставлении.

Результат. Книга результата в папке вывода и report/address_alignment_summary.json. В журнале — сводка по каждой колонке: сколько строк нашлось каждым проходом, сколько точных, сколько мягких, сколько осталось без пары.

Как читать сводку. Высокий процент мягких попаданий — повод посмотреть глазами. Точное совпадение доказательно, приблизительное — гипотеза.

4.4. Нормализация эталона

Создаёт эталонный справочник адресов из источников или приводит существующий к текущему набору слотов.

Действие

• Сгенерировать — новый справочник из источников.
• Обновить — дополнить существующий.
• Чистка слотов — перестроить устаревшие слот-колонки.

Опции. «Схлопывать старые дубли» объединяет записи с одинаковым ключом слотов. «Перестроить старые слоты» удаляет устаревшие слот-колонки и пишет только текущий набор. «Чистая новая книга» даёт компактный результат.

Результат. Книга AddressReference_*.xlsx и report/reference_normalization_summary.json.

Нормализация детерминирована: пробелы, пунктуация, регистр, сокращения и выделение составляющих обрабатываются одинаково от прогона к прогону. Исходное значение адреса сохраняется в результате.

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

4.5. Обработка эталона

Сортирует эталонную адресную колонку по слотам или раскладывает её на отдельные слот-колонки.

Действие: Сортировать, Разложить, Сортировать + разложить.

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

Заголовки слот-колонок: Полные (Postal_Index, Municipality) или Короткие (Index, Municipality).

Удалить исходную адресную колонку — при разложении слот-колонки вставляются, а исходная убирается.

Результат. Обработанная книга и report/reference_processing_summary.json.

4.6. Сравнить две таблицы

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

Поля. Таблица A и Таблица B, листы, адресные колонки каждой, первая строка данных каждой. Адресные колонки B могут стоять на других позициях, чем в A.

Сортировать адреса внутри групп. Выключено — сначала идут сопоставленные строки в порядке A, затем «только A» и «только B». Включено — внутри каждой группы строки отсортированы по адресу.

Результат. Книга сравнения со статусной колонкой и цветовой заливкой:

Плюс report/table_comparison_summary.json.

4.7. Перенести колонки по адресу

Находит одинаковые дома в двух книгах и переносит выбранные колонки из источника в соответствующие строки основной книги.

Простое копирование строк здесь не годится: порядок строк основной книги, её формулы, оформление и листы должны остаться на месте. Поэтому перенос идёт через Excel, а основная книга сначала копируется в папку результата и правится уже копия.

Поля. Основная книга и книга-источник, листы (в источнике можно отметить несколько), адресные колонки обеих, «Поля для переноса» — что именно переносить, первые строки данных и строка заголовка результата.

Результат. Копия основной книги с добавленными колонками, статусной колонкой и листом аудита AUDIT_ADDRESS_JOIN. Статусы: сопоставлено, сопоставлено: N записи, не найдено. Отчёт — report/safe_table_join_summary.json.

Проверьте, что один адрес не разрешился в несколько несовместимых строк: именно это показывает статус с числом.

4.8. Конвертация DOC/XLS

Превращает старые .doc и .xls в исходниках в .docx и .xlsx.

Перезаписывать существующие — выключено, существующие .docx/.xlsx сохраняются. Дополнительно удаляются одноимённые PDF/TXT/CSV/MD дубликаты, оставшиеся от прежних конвертаций.

Отчёт — report/legacy_office_conversion_report.json.

4.9. Диагностика

Две подкоманды.

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

Проверить исходники перечисляет поддерживаемые таблицы в папке исходников и попутно убирает временные файлы Office.

5. Обслуживание

Очистка пустых строк убирает только строки, пустые целиком. Строка с данными в одной-единственной колонке считается непустой и остаётся.

Очистка папок ограничена управляемой рабочей областью: cleanup_managed_workspace_only и never_delete_original_inputs в config/project.yaml не дают ей выйти за пределы проекта и удалить оригиналы.

6. Порядок работы

Типовой прогон:

1. Подготовьте реестр ОКТМО, если работаете с территориальным контекстом — один раз операцией ОБНОВИТЬ РОССТАТ, дальше по мере выхода новых срезов.
2. Наберите ключи региона или муниципалитета в разделе ОКТМО.
3. Сложите исходники, проверьте список.
4. Прогоните на маленьком контролируемом наборе — десяток строк, где ответ известен заранее.
5. Запустите полный прогон.
6. Прочитайте отчёт. Прогон не закончен, пока отчёт не просмотрен.
7. Откройте результат в табличном приложении и сверьте заголовки, порядок строк, формулы и перенесённые значения.

Что смотреть в отчёте

• пустые адреса;
• дубли ключей;
• связи «один ко многим» и «многие к одному»;
• расхождения по дому и корпусу;
• кандидаты с низкой уверенностью;
• строки, не попавшие в результат;
• неожиданное изменение количества строк.

Правила безопасной работы

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

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

Держите исходники и отчёт до приёмки результата.

После изменения логики сопоставления сначала прогоняйте маленький контролируемый набор.

При сбое сохраните журнал и отчёт. Исправьте источник, эталон или разметку колонок — и повторяйте прогон только после того, как поняли причину.