docs-staff-list — сводный список сотрудников

Создавать один .xlsx с нумерацией и всеми содержательными колонками исходника. Минимальный набор для простых выгрузок:

Более полный исходник не сокращать до этого набора: сохранять СНИЛС, документы, контакты, адреса, занятость, состояние и прочие поля. Порядок колонок брать из основного исходника; при объединении добавлять отсутствующие поля других файлов.

Использовать scripts/normalize.py. Не классифицировать форматы вручную до запуска --probe.

1. Определить вход

Собрать переданные .xls/.xlsx. При правке готового списка брать его последнюю пользовательскую версию. Если для одного филиала есть основной, внешний и объединённый варианты, выбрать один файл с нужным охватом — обычно объединённый. Основной файл с наиболее полной схемой указывать первым. Не включать готовый общий сводный вместе с филиальными файлами как независимые входы консолидации.

При новой или непонятной структуре прочитать references/formats.md.

2. Выполнить probe

python3 scripts/normalize.py --probe --input-dir "/path/to/input"

Для выбранных файлов:

python3 scripts/normalize.py --probe \
  --input-dir "/path/to/input" \
  --files "branch-a.xlsx" "branch-b.xls"

Проверить для каждого файла формат, число строк и источник филиала. Если филиал угадан из имени, задать человекочитаемое значение через --branch-map. Пустые и сокращённые ошибочные значения в существующей колонке уточнять по подразделению и заполненным строкам того же подразделения. При неоднозначности не угадывать. Пустые должность и подразделение сохранять пустыми до получения сведений.

3. Выбрать выход

Прочитать ~/.docs-plugin/org_details.md, если он существует.

• Сохранять дату состояния списка из исходника или запроса в названии файла и папки. Дата обработки не заменяет дату списка. Для нового списка без указанной даты использовать текущую дату.
• Если staff_file указывает на каталог, использовать подпапку и сводный файл с датой списка: <staff_file>/<ДД.ММ.ГГГГ>/Сводный список сотрудников <ДД.ММ.ГГГГ>.xlsx.
• Если staff_file указывает на конкретный файл или не задан, выбрать явный путь в папке текущей задачи.
• Всегда передавать итоговый путь через --output. Не перезаписывать существующий файл без явной просьбы.

4. Создать сводный

python3 scripts/normalize.py \
  --input-dir "/path/to/input" \
  --files "branch-a.xlsx" "branch-b.xls" \
  --branch-map "branch-a.xlsx:Филиал А;branch-b.xls:Филиал Б" \
  --title "Сводный список сотрудников 10.08.2026" \
  --output "/path/to/output/Сводный список сотрудников 10.08.2026.xlsx"

Переопределения использовать только после ошибочного probe:

• --format-map "file.xls:shtatnaya" — задать формат;
• --year-only "file.xlsx" — сохранить только год рождения;
• --date-col "file.xls:4" — задать индекс колонки даты;
• --dedup — удалить повторы по ФИО и дате рождения, только после осмысленной проверки дублей.

По умолчанию дубли сохранять: один человек может занимать несколько должностей.

Дополнить готовый список

Дополнительную выгрузку сопоставлять с нужным филиалом готового списка, а не добавлять целиком повторными строками. Предпочитать СНИЛС, сверяя ФИО и дату рождения. При отсутствии СНИЛС использовать ФИО вместе с датой рождения; совпадение должно быть однозначным. Заполнять пропуски, сохранять существующие значения и сообщать о расхождениях и ненайденных сотрудниках. Сохранять состав строк, нумерацию, все колонки и дату списка, если пользователь не просит иного.

5. Оформить и проверить

Эталон оформления: Arial 14 пт, чёрный текст, жирная шапка в строке 1 и данные со строки 2. Все колонки находятся в одной строке шапки, без объединений, отдельного титульного блока, подзаголовков и заливок. Ячейки могут переносить текст внутри строки. Тонкие чёрные границы, выравнивание слева и по центру высоты, достаточные ширины колонок и высоты строк. Стандартная сетка видима. Закрепление — B2, фильтр охватывает всю таблицу. Указанный --title сохраняется только в метаданных книги. При точечном дополнении уже оформленного списка сохранять оформление пользователя.

• Сверить итоговое число строк и разбивку по филиалам с probe.
• Сверить состав колонок и дополнительные данные с исходником. Многоярусную шапку свести к листовым заголовкам в строке 1; при одинаковых названиях уточнить группу.
• Сохранять ведущие нули и текстовый тип идентификаторов, серий, номеров и телефонов.
• Добиться Верификация: OK либо разобрать каждую проблему.
• Просмотреть все изменённые ФИО и исключить ложные срезы.
• Проверить группы дублей.
• Перечитать сохранённый .xlsx и проверить значения, нумерацию и структуру. Визуальную проверку выполнять только по запросу.

Исходники не перемещать и не удалять без явной просьбы.

Зависимости

Python 3.8+, pandas, openpyxl; для чтения .xls также нужен xlrd.