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

[English](USER_GUIDE_EN.md) · [Описание](README_RU.md) · [ОКТМО](OKTMO_RU.md) · [Справочник](REFERENCE_RU.md)

**Содержание**

- [1. Запуск](#1-запуск)
- [2. Окно и рабочие папки](#2-окно-и-рабочие-папки)
- [3. Как устроена карточка операции](#3-как-устроена-карточка-операции)
- [4. Операции](#4-операции)
- [5. Обслуживание](#5-обслуживание)
- [6. Порядок работы](#6-порядок-работы)

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

---

## 1. Запуск

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

Если окно не появилось или в журнале написано, что нет Python проекта, смотрите
[Установку](INSTALL_RU.md#если-окно-не-открылось).

---

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

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

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

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

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

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

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

| Папка | Что в ней |
| --- | --- |
| `input` | Исходные файлы |
| `output` | Результаты |
| `report` | JSON-отчёты прогонов |
| `logs` | Журналы операций |
| `workspace` | Промежуточные файлы |
| `release` | Архивы результатов |

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

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

| Кнопка | Действие |
| --- | --- |
| СБРОСИТЬ | Вернуть оба пути к `input` и `output`; закрепления остаются |
| СПИСОК | Назвать файлы источника в журнале: по алфавиту, с номерами |
| ПРОВЕРИТЬ | Операция «Проверить исходники»: перечислить поддерживаемые таблицы |
| ОЧИСТИТЬ | Удалить содержимое источника и назначения; сами папки остаются. Окно спрашивает и называет оба пути, удалённое уходит в Корзину |

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

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

---

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

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

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

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

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

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

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

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

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

---

## 4. Операции

| Раздел | Вкладки | Где описано |
| --- | --- | --- |
| ИСТОЧНИКИ | КОНВЕРТАЦИЯ DOC/XLS · ПРОВЕРКА ИСХОДНИКОВ · ДИАГНОСТИКА ПАРСЕРА | 4.8, 4.9 |
| СБОР | — | 4.2 |
| ЭТАЛОН | НОРМАЛИЗАЦИЯ · ОБРАБОТКА | 4.4, 4.5 |
| СОПОСТАВЛЕНИЕ | АДРЕСА · ДВЕ ТАБЛИЦЫ · ПЕРЕНОС КОЛОНОК | 4.3, 4.6, 4.7 |
| ОКТМО | КЛЮЧИ И ОБЛАСТЬ · ОБНОВИТЬ РОССТАТ | 4.1 |

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

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

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

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

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

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

**Действие**

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

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

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

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

**Опции**

| Опция | Что делает |
| --- | --- |
| Пропускать микрорайон при наличии улицы | Колонка микрорайона остаётся, но в собранную строку не входит |
| Чистая новая книга | Компактная книга только с адресной колонкой вместо полной |
| Схлопывать дубли | Объединить кандидатов с одинаковым адресным ключом и выбрать лучшие значения слотов голосованием |
| Чистить неполные адреса | Убрать улицу без дома, дом без улицы, адрес из одного региона и табличный мусор |
| Писать лист отбраковки | Отбракованные кандидаты уходят на отдельный лист для аудита |
| Включить ключи ОКТМО | Определять территорию по реестру и ключам проекта |

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

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

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

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

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

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

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

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

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

| Режим | Поведение |
| --- | --- |
| Авто | Прежняя автоматика |
| Нет | Чистое сопоставление адресных колонок |
| Слева | Колонки левее каждого адреса |
| Справа | Колонки правее каждого адреса |
| Всё между 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». Включено — внутри каждой
группы строки отсортированы по адресу.

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

| Статус | Цвет | Значение |
| --- | --- | --- |
| сопоставлено | зелёный | Ровно одна пара |
| сопоставлено: N строк B | жёлтый | Несколько кандидатов, нужен просмотр |
| только A | оттенок A | Пары нет |
| только B | оттенок 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. Обслуживание

| Кнопка | Что делает |
| --- | --- |
| ОЧИСТИТЬ (рабочая зона) | Удалить содержимое выбранных источника и назначения; сами папки остаются, удалённое уходит в Корзину |
| СЕРВИС → «Очистить input и output программы (операция)» | Операция: удалить содержимое управляемых `input` и `output` проекта, сами папки остаются |
| ОЧИСТИТЬ ПУСТЫЕ СТРОКИ (панель результата) | Создать копии результатов без строк, пустых по всем колонкам |
| УПАКОВАТЬ РЕЗУЛЬТАТЫ (панель результата) | Собрать `release/address_aligner_output.zip` из папки результата |

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

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

---

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

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

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

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

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

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

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

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

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

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

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