dev/README.md

@@ -6,6 +6,7 @@
 поднимается только инфраструктура, а сервисы можно запускать из venv (см. «Запуск сервисов из venv»).
 
 Для ручного тестирования стенда (установка ПО, запуск, чек-лист сценариев по ролям) — [`qa-guide.md`](qa-guide.md).
+Инструкция пользователя по экранам прототипа со скриншотами (для передачи в тестирование) — [`../user/user-guide.md`](../user/user-guide.md).
 Разработчику фронта: **начинать с [`frontend-api-guide.md`](frontend-api-guide.md)** — единый гайд по API `arm-core` (подключение,
 общие правила, все маршруты, ошибки, сценарии экранов, что недавно изменилось и что изменится); как устроены вход и права `arm-core`, какие ручки когда дёргать, семантика 401/403/404 —
 [`frontend-auth-guide.md`](frontend-auth-guide.md); файлы, документы и справочники — [`api-contract-files-directories.md`](api-contract-files-directories.md); контракт API консолидации — [`api-contract-slice-4.md`](api-contract-slice-4.md); контракт API форм ББ/ОФР и пути

dev/qa-guide.md

@@ -6,6 +6,7 @@ macOS (Docker 28, compose 2.34, Node 24, uv 0.10): от пустого ката
 
 Как читать: раздел 4 — поднять стенд, раздел 8 — пройти основной путь аналитика в браузере, разделы 6–7 — то же и
 глубже через API (Swagger/curl): там проверяются права, коды ошибок и граничные случаи, до которых UI не доходит.
+Инструкция пользователя по экранам со скриншотами (без стенда и API) — [`../user/user-guide.md`](../user/user-guide.md).
 
 ## 1. Что сейчас есть и чего нет
 

user/user-guide.md

@@ -0,0 +1,502 @@
+# Инструкция пользователя АРМ КА (прототип)
+
+Документ описывает работу с текущей версией приложения **АРМ КА** — автоматизированного рабочего места кредитного
+аналитика ДКБ: фронт `arm-web` (ветка `test`) и ядро `arm-core` (`main`) по состоянию на 09.10.2026. Снимки экранов
+сделаны на локальном стенде с демо-данными группы компаний «Русский Бисквит» (окно браузера 1600×1000); на вашем стенде
+названия организаций, даты и суммы могут отличаться, устройство экранов — то же.
+
+Для кого: аналитик, который проверяет приложение или работает в нём впервые. Как поднять стенд, какие учётные записи
+есть и как заводить дефекты — в гайде тестировщика [`../dev/qa-guide.md`](../dev/qa-guide.md) (разделы 4, 4.4 и 11);
+здесь только путь пользователя по экранам.
+
+## Содержание
+
+1. [Что умеет текущая версия](#1-что-умеет-текущая-версия)
+2. [Вход в систему](#2-вход-в-систему)
+3. [Устройство интерфейса](#3-устройство-интерфейса)
+4. [Группы компаний](#4-группы-компаний)
+5. [Страница группы компаний: консолидации и организации](#5-страница-группы-компаний-консолидации-и-организации)
+6. [Новая консолидация](#6-новая-консолидация)
+7. [Первичные документы: загрузка и статусы](#7-первичные-документы-загрузка-и-статусы)
+8. [Просмотр ОСВ](#8-просмотр-осв)
+9. [Проверка форм ББ и ОФР](#9-проверка-форм-бб-и-офр)
+10. [Сводная ОСВ](#10-сводная-осв)
+11. [Администрирование: пользователи и роли](#11-администрирование-пользователи-и-роли)
+12. [Статусы и термины](#12-статусы-и-термины)
+13. [Ограничения текущей версии](#13-ограничения-текущей-версии)
+14. [Если что-то пошло не так](#14-если-что-то-пошло-не-так)
+
+## 1. Что умеет текущая версия
+
+Основной путь аналитика от создания консолидации до сводной оборотно-сальдовой ведомости (ОСВ) группы:
+
+- список групп компаний (ГК) с поиском и фильтрами;
+- создание консолидации за квартал: ГК, группа связанных компаний (ГСК), год, квартал, состав юридических лиц (ЮЛ);
+- страница ГК: список консолидаций и версий, состав организаций версии, чек-лист документов в CSV;
+- загрузка первичных документов по каждому ЮЛ: ОСВ в Excel (`xls`, `xlsx`, `xlsb`), бухгалтерский баланс (ББ) и отчёт
+  о финансовых результатах (ОФР) в PDF и Excel; тип документа и период определяются автоматически;
+- просмотр распознанной ОСВ (только чтение) и подтверждение документа;
+- проверка форм ББ/ОФР рядом со сканом: правка значений, логические проверки, принятие нарушений с комментарием,
+  подтверждение;
+- сводная ОСВ по версии: фильтры, список пробелов по кварталам, тип контрагента (ГСК / ГК / Внешний), сопоставление
+  контрагента без ИНН с организацией справочника, экспорт в Excel;
+- администрирование: пользователи, роли, матрица «роль × право».
+
+Чего в этой версии **нет** (пункты меню и вкладки показаны, но не работают — см. раздел 13): шахматка, таблица
+корректировок, гудвилл, КФО, маршрут согласования и смена статусов вручную, Единое хранилище, журнал действий, экраны
+справочников ГК/ЮЛ, монозаёмщики. Вход через корпоративный SSO заменён формой входа для разработки.
+
+## 2. Вход в систему
+
+Откройте адрес стенда (на локальном стенде — `http://localhost:3000/`). Появится форма «Вход для разработки».
+
+![Форма входа](img/01-login.png)
+
+1. Введите **email** пользователя (не имя и не логин), например `ka_go@armka.local`. Пароля нет.
+2. Нажмите «Войти (dev)».
+
+Список учётных записей стенда и их ролей — `qa-guide.md`, раздел 4.4. Для прохода по этой инструкции достаточно
+`ka_go@armka.local` (аналитик головного офиса, роль KA_GO); раздел 11 требует `admin@armka.local`.
+
+После входа открывается главная страница с ФИО пользователя и его ролями.
+
+![Главная страница после входа](img/02-main.png)
+
+Особенности сессии:
+
+- токен действует 8 часов и живёт в текущей вкладке браузера: новая вкладка — новый вход;
+- кнопки «Выйти» нет; чтобы сменить пользователя, откройте новую вкладку или закройте текущую;
+- после истечения токена форма входа появится снова с сообщением «Сессия истекла».
+
+## 3. Устройство интерфейса
+
+Слева — боковое меню, справа — рабочая область с «хлебными крошками» (например, «Отчётность › Группы компаний»)
+и кнопкой «← Назад» на вложенных экранах.
+
+Меню:
+
+| Раздел | Пункт | Что открывает |
+|---|---|---|
+| — | **+ Новая консолидация** | окно создания консолидации (раздел 6) |
+| Отчётность | Группы компаний | список ГК (раздел 4) — основной вход в работу |
+| Отчётность | Монозаемщики | заглушка |
+| Справочники | ГК и организации, ЮЛ вне ГК | заглушки |
+| Документы | Единое хранилище | заглушка |
+| Система | Журнал действий | заглушка |
+| Система | Пользователи и роли | администрирование (раздел 11) |
+
+Кнопка «‹» в шапке меню сворачивает его до иконок; «›» разворачивает обратно.
+
+![Свёрнутое меню](img/44-sidebar-collapsed.png)
+
+Заглушки показывают только заголовок страницы:
+
+![Заглушка «Монозаёмщики»](img/43-stub-mono.png)
+
+Общие элементы таблиц: строка поиска над таблицей, воронка в заголовке колонки — фильтр по этой колонке (зелёная
+воронка — фильтр активен), «Настройка таблицы» — выбор видимых колонок, «Сбросить фильтры» появляется, когда хотя бы
+один фильтр применён. Уведомления об успехе и ошибках появляются вверху экрана и исчезают через несколько секунд.
+
+## 4. Группы компаний
+
+«Отчётность → Группы компаний». Таблица: «Группа компаний», «CRM ID», «Основной РФ» (региональный филиал), «Организаций»
+(число ЮЛ в группе). Пользователь филиала видит только ГК своего филиала, головной офис — все.
+
+![Список групп компаний](img/03-groups.png)
+
+- Поиск «Поиск по ГК, CRM ID или…» ищет по названию и идентификаторам.
+- Кнопка «→ Консолидации» в строке открывает страницу группы (раздел 5).
+
+## 5. Страница группы компаний: консолидации и организации
+
+Страница ГК состоит из двух блоков.
+
+![Страница группы компаний](img/04-group-page.png)
+
+**Консолидации** — все консолидации группы, по строке на версию: «Год», «Квартал» (К1…К4), «Версия» (номер),
+«Статус» (цветной бейдж, раздел 12), «ГСК», «Дата создания», «Дата верификации», «Организаций» (размер периметра).
+Клик по строке выбирает версию: строка подсвечивается зелёным, адрес страницы получает `?version=<id>`, а блок
+«Организации» заполняется составом этой версии.
+
+![Выбранная версия](img/08-group-version-selected.png)
+
+В строке версии:
+
+- «К отчётности →» — переход к сводной ОСВ версии (раздел 10);
+- меню «⋮»: «Добавить версию» (в прототипе отвечает «Будет позже»), «Отключить подтверждение КФО» и «История
+  изменений» (заглушки).
+
+![Меню строки версии](img/09-version-row-menu.png)
+
+**Организации** — периметр выбранной версии. Над таблицей: «Ответственный» (кто создал версию), «Утверждён в РФ» и
+«Верифицирован в ГО» (в этой версии всегда «—»), кнопки «Настройка таблицы» и «Скачать чек-лист». Колонки:
+«Наименование», «Документы» (кнопка открытия панели документов, раздел 7), «ОФР» и «Бух.баланс» (статус формы за
+отчётный период: «Отсутствует», «Обработка», «Требуется проверка», «Загружен»), «ОСВ» (счета, по которым загружены
+ведомости), «ИНН», «Тип» (ЮЛ / ИП).
+
+«Скачать чек-лист» сохраняет файл `checklist-<ГК>-<год>-Q<квартал>.csv` (разделитель `;`, открывается в Excel) со
+статусом каждого требуемого документа по каждому ЮЛ периметра. Кнопка активна только при выбранной версии.
+
+Таблица консолидаций обновляется при перезагрузке страницы (F5): сразу после создания консолидации новая строка может
+появиться только после обновления.
+
+## 6. Новая консолидация
+
+Нажмите «+ Новая консолидация» в меню (с любого экрана).
+
+![Пустое окно создания консолидации](img/05-new-consolidation-empty.png)
+
+Заполните поля по порядку:
+
+1. «Группа компаний» — ГК из списка доступных вам.
+2. «ГСК» — группа связанных компаний внутри ГК (поле активно после выбора ГК).
+3. «Год» — текущий и три предыдущих.
+4. «Квартал» — 1–4 квартал.
+
+После выбора всех четырёх полей появляется блок «ЮЛ консолидации»: все открытые ЮЛ группы с ИНН. Участники ГСК уже
+отмечены и стоят первыми, счётчик «Выбрано: N / M» показывает размер периметра. Поле «Поиск ЮЛ…» фильтрует список;
+галочками можно добавить или исключить организации.
+
+![Заполненное окно с составом ЮЛ](img/06-new-consolidation-filled.png)
+
+«Создать» создаёт консолидацию и версию 1 в статусе «Инициация», показывает уведомление «Создана консолидация <год>,
+<квартал>» и открывает страницу ГК с выбранной версией.
+
+![Консолидация создана](img/07-consolidation-created.png)
+
+Проверки при создании:
+
+| Ситуация | Что покажет система |
+|---|---|
+| Консолидация этой ГК за тот же год и квартал уже есть | уведомление «Консолидация ГК за этот период уже создана», окно остаётся открытым |
+| В периметре одно ЮЛ | уведомление с текстом сервера: периметр должен содержать не меньше двух организаций |
+| Ни одного ЮЛ | кнопка «Создать» неактивна |
+
+## 7. Первичные документы: загрузка и статусы
+
+Документы загружаются по каждой организации отдельно. На странице ГК выберите версию и нажмите «Документы» в строке
+организации (или кликните по строке). Справа откроется панель «ПЕРВИЧНЫЕ ДОКУМЕНТЫ» с названием и ИНН организации и
+списком всех её файлов (не только текущего периода).
+
+![Панель первичных документов](img/10-documents-panel.png)
+
+Колонки панели: «Документ» (имя файла; под ним — тип документа, формат и дата загрузки, например «ОСВ 60 · XLS ·
+09.10.2026»), «Период» (определённый из документа, например «2024 К3»), «Проверка» (две отметки: «Период» и
+«Контрагент» — совпадает ли организация в шапке документа с ЮЛ, на которое он загружен: ✓ совпадает, ✗ не совпадает,
+— не проверялось), «Статус» (раздел 12). Крестик в правом верхнем углу закрывает панель.
+
+### 7.1 Загрузка
+
+1. «Загрузить документы» → окно «Загрузка документов».
+2. Перетащите файлы в область или нажмите «Выбрать документы». Принимаются ОСВ, ББ и ОФР в форматах `xls`, `xlsx`,
+   `xlsb`, `pdf`, `png`, `jpg`; тип документа и период система определяет сама.
+
+![Окно загрузки](img/11-upload-modal-empty.png)
+
+![Выбранные файлы перед отправкой](img/12-upload-modal-files.png)
+
+3. «Загрузить». Результат появится в том же окне: зелёный блок «Принято: N» с именами файлов и, если есть, красный
+   «Отклонено: N» с причиной по каждому файлу. Кнопка «Загрузить» сменится на «Готово».
+
+![Файлы приняты](img/13-upload-accepted.png)
+
+4. «Готово» закрывает окно. Принятые файлы появляются в панели со статусом «Обработка»; панель сама опрашивает сервер
+   раз в 5 секунд, пока есть файлы в обработке. Распознавание Excel-ОСВ занимает 5–15 секунд, PDF — до минуты.
+
+![Файлы в обработке](img/14-documents-panel-processing.png)
+
+Когда распознавание завершено, у каждого файла заполняются тип, период и проверки; чистые ОСВ (период распознан,
+организация совпала) подтверждаются автоматически и получают статус «Загружен».
+
+![Документы распознаны](img/15-documents-panel-loaded.png)
+
+Повторная загрузка файла с тем же именем для того же ЮЛ отклоняется: «Отклонено: 1 — файл «…» уже загружен для этого
+ЮЛ», уведомление «Ни один файл не принят».
+
+![Дубликат отклонён](img/16-upload-rejected-duplicate.png)
+
+### 7.2 Один файл — несколько документов
+
+PDF с бухгалтерской отчётностью даёт два документа: «Бух. баланс · PDF» и «ОФР · PDF». Если в скане другая
+организация, у обоих будет «Контрагент ✗» и статус «Требуется проверка» — их нужно проверить вручную (раздел 9).
+
+![PDF распознан в два документа](img/18-documents-panel-pdf.png)
+
+После того как по всем организациям периметра загружены документы, статус версии в таблице консолидаций меняется:
+«Обработка документов», пока идёт распознавание, затем «Коррекция данных» (видно после F5).
+
+## 8. Просмотр ОСВ
+
+Клик по строке ОСВ в панели документов открывает экран «Просмотр ОСВ»: крошки «Отчётность › <ЮЛ> › Проверка
+документа», имя файла, формат и дата, справа — статус документа.
+
+![Просмотр ОСВ](img/17-osv-document.png)
+
+- Строки ОСВ только для чтения, суммы в рублях. Колонки: «Субсчёт», «Контрагент / аналитика», «ИНН», сальдо на начало
+  периода (Дебет / Кредит), обороты за период (Дебет / Кредит), сальдо на конец периода (Дебет / Кредит). Ноль
+  показывается как «—».
+- Поле «Контрагент или ИНН» фильтрует строки, «Субсчёт» — выбор субсчёта; «Строк: N» — число строк после фильтра.
+- Внизу «Итого по документу».
+- «✓ Подтвердить» активна только для документа в статусе «Требуется проверка»; у автоматически подтверждённых ОСВ
+  («Загружен») она неактивна. Подтверждение переводит документ в «Загружен», после чего он участвует в сводной ОСВ.
+
+## 9. Проверка форм ББ и ОФР
+
+Клик по строке «Бух. баланс» или «ОФР» в панели документов открывает экран «Проверка распознавания». Слева —
+«ИСХОДНЫЙ ДОКУМЕНТ»: страницы PDF с масштабом («−», «100%», «+», сброс). Справа — «РЕЗУЛЬТАТ РАСПОЗНАВАНИЯ».
+
+![Проверка бухгалтерского баланса](img/19-review-bb.png)
+
+Правая часть сверху вниз:
+
+- шапка: «ИНН», «Дата отчёта», «Единица измерения». Нераспознанное значение — «—» на оранжевом фоне;
+- название формы («Бухгалтерский баланс» / «Отчёт о финансовых результатах») и дата, если она есть;
+- блок проверок: зелёный «Проверки пройдены» или красный «Нарушения (N)» с формулами (раздел 9.2);
+- таблица формы: «Наименование показателя», «Код», колонки периодов как в документе. Разделы («АКТИВ», «I. Внеоборотные
+  активы» …) — серые полосы, итоговые строки — жирным, строки «БАЛАНС» (1600 и 1700) — фиолетовым фоном. Пустые
+  значения — «-». Ячейка с уверенностью распознавания ниже 100 % подсвечена оранжевым, при наведении — «Уверенность:
+  N%». В форме показаны все строки шаблона, в том числе отсутствующие в источнике (пустые).
+
+Кнопки: «✎ Редактировать» и «✓ Подтвердить данные».
+
+Формы, загруженные в Excel, открываются тем же экраном, но слева вместо скана — «Превью недоступно для этого формата»
+и кнопка «Скачать исходник».
+
+### 9.1 Правка значений
+
+«✎ Редактировать» переводит таблицу и шапку в режим ввода; кнопки меняются на «✓ Сохранить» и «Отменить».
+
+![Режим правки](img/20-review-edit.png)
+
+- Суммы вводятся числом (без пробелов, дробная часть через точку или запятую); знак «−» допустим.
+- Шапка: «ИНН», «Дата отчёта» строго в формате `ГГГГ-ММ-ДД`, «Единица измерения». Поля шапки можно заменить, но нельзя
+  очистить.
+- «Отменить» сбрасывает все несохранённые правки.
+- «✓ Сохранить» отправляет изменения: уведомление «Изменения сохранены», проверки пересчитываются. Исправленная ячейка
+  подсвечивается голубым, при наведении видно «Исходное: <значение>» — распознанное значение не теряется.
+
+![Правка шапки: дата отчёта](img/26-review-edit-header.png)
+
+Если в ячейке не число (например `abc`), она обводится красным с подсказкой «Неверный формат суммы», появляется
+уведомление «Исправьте суммы с неверным форматом», и запрос на сервер не уходит.
+
+![Неверный формат суммы](img/25-review-invalid-format.png)
+
+### 9.2 Логические проверки и нарушения
+
+После каждого сохранения система проверяет форму по контрольным соотношениям (итоги разделов, баланс актива и пассива,
+связи строк ОФР). Нарушения показываются красным блоком «Нарушения (N)»: «Колонка N: <формула> — ожидалось X,
+получено Y». Жёлтый блок «Расхождения в пределах округления» — отклонения, которые не блокируют подтверждение.
+
+![Нарушения после правки](img/21-review-violations.png)
+
+Пока есть нарушения, «✓ Подтвердить данные» отвечает красным блоком «не пройдены логические проверки формы: исправьте
+значения или акцептуйте с комментарием» с тем же списком, документ не подтверждается.
+
+![Подтверждение заблокировано нарушениями](img/22-review-confirm-blocked.png)
+
+Два пути: исправить значения (раздел 9.1) или принять нарушения осознанно — «Принять с комментарием». В окне
+«Принять нарушения» комментарий обязателен (до 2000 символов), без него «Принять» неактивна.
+
+![Окно принятия нарушений](img/23-review-accept-modal.png)
+
+После принятия под нарушениями появляется синий блок «Нарушения приняты» с датой, временем и комментарием; подтверждение
+становится возможным. Любая новая правка значений сбрасывает принятие — нарушения нужно принять заново.
+
+![Нарушения приняты](img/24-review-accepted.png)
+
+### 9.3 Подтверждение
+
+Для подтверждения в шапке должна быть «Дата отчёта» на конец квартала (например `2025-06-30`). Если дата пустая или не
+на конец квартала, «✓ Подтвердить данные» показывает красный блок с текстом сервера и подсказкой «Исправьте дату отчёта
+в шапке и сохраните».
+
+Когда проверки пройдены (или нарушения приняты) и дата указана, «✓ Подтвердить данные» подтверждает документ:
+уведомление «Документ подтверждён», статус «Загружен», кнопки «Редактировать» и «Подтвердить данные» становятся
+неактивными — дальнейшая правка невозможна.
+
+![Документ подтверждён](img/27-review-confirmed.png)
+
+ОФР того же файла открывается отдельным документом с колонками периодов ОФР («За январь – июнь 2025 г.» и т. п.);
+правила проверки и подтверждения те же.
+
+![Проверка ОФР](img/28-review-ofr.png)
+
+## 10. Сводная ОСВ
+
+Нажмите «К отчётности →» в строке версии. Откроется экран «<ГК> — <год> К<квартал>» со статусом отчёта в правом
+верхнем углу и вкладками: «ОСВ» (активна), «Шахматка», «Таблица корректировки», «Гудвилл», «КФО», «КФО Общий»,
+«Подтверждение КФО клиента» (неактивны, подсказка «Будет в следующих срезах»).
+
+![Сводная ОСВ](img/30-osv-summary.png)
+
+Что на экране:
+
+- **Жёлтый баннер «Требуется указать соответствия»** — сколько строк с внешними контрагентами без ИНН ещё не
+  сопоставлено («Осталось: N»); кнопка «Показать ЮЛ без ИНН» включает фильтр только по таким строкам (раздел 10.3).
+- **«Пробелы: N»** — свёрнутый список счетов, по которым за часть кварталов периода нет ОСВ; строки таких счетов в
+  свод не попадают. Клик раскрывает список: «<ЮЛ> — счёт <код> — нет кварталов: Q1, Q2».
+
+![Список пробелов](img/31-osv-gaps.png)
+
+- **Таблица**: «Компания ГК», «Счёт» (субсчёт), «Период» (например «9 мес. 2024 г.»), «Контрагенты», «ИНН», сальдо на
+  начало, обороты, сальдо на конец (Дебет / Кредит), «Тип контрагента». Суммы в рублях с копейками, ноль — «—».
+  По 500 строк на страницу, внизу «Строк: N» — общее число строк по текущим фильтрам и переключатель страниц. Таблица
+  прокручивается по горизонтали.
+- **«Экспорт»** — сохраняет `svod-osv_<ГК>_<год>-Q<квартал>_v<версия>.xlsx` с листами «Сводная ОСВ» и «Пробелы» по
+  текущим фильтрам.
+
+Если по версии ещё нет подтверждённых ОСВ, вместо таблицы — «В своде пока нет строк: загрузите и подтвердите ОСВ
+организаций».
+
+### 10.1 Фильтры
+
+Фильтр открывается воронкой в заголовке колонки, применяется кнопкой «Применить», снимается «Сбросить»; активный фильтр
+окрашивает воронку зелёным.
+
+| Колонка | Фильтр |
+|---|---|
+| Компания ГК | выбор организации периметра из списка |
+| Счёт | корень счёта, например `62` (не субсчёт: `60.01` не найдёт ничего) |
+| Контрагенты | подстрока названия контрагента или начало ИНН, например `бисквит` |
+| ИНН | только строки без ИНН (то же, что «Показать ЮЛ без ИНН») |
+| Тип контрагента | одно значение: ГСК, ГК или Внешний |
+
+![Фильтр по организации](img/32-osv-filter-company.png)
+
+![Фильтр по контрагенту](img/33-osv-filter-counterparty.png)
+
+![Фильтр по счёту](img/38-osv-filter-account.png)
+
+Пример: организация «ПЕКАРНЯ СЧАСТЛИВОЧНАЯ» и контрагент `бисквит` оставляют строки расчётов с «РУССКИЙ БИСКВИТ, АО»
+по счетам 60, 62, 76 — это внутригрупповые обороты.
+
+![Отфильтрованные строки](img/34-osv-filtered.png)
+
+### 10.2 Тип контрагента
+
+Последняя колонка — признак контрагента, вычисленный по ИНН и справочнику: синий бейдж «ГСК» (участник группы связанных
+компаний версии), зелёный «ГК» (организация той же ГК вне ГСК), серый «Внешний» (все остальные).
+
+![Бейджи типа контрагента](img/35-osv-counterparty-type.png)
+
+### 10.3 Контрагенты без ИНН и сопоставление
+
+В ячейке «ИНН» возможны три варианта:
+
+- ИНН из файла — просто число моноширинным шрифтом;
+- красная кнопка «Указать» на подсвеченном фоне — в файле ИНН нет и контрагент не связан с организацией справочника;
+- серая «таблетка» с ИНН — в файле ИНН не было, но контрагент уже связан с организацией справочника (подсказка
+  «Связано с организацией справочника — изменить»).
+
+«Показать ЮЛ без ИНН» в баннере оставляет только строки с «Указать»; кнопка меняется на «Показать все строки».
+
+![Только строки без ИНН](img/36-osv-no-inn.png)
+
+Клик по «Указать» (или по серой таблетке) открывает окно «Выбор организации для связи с <контрагент>»:
+
+1. Введите часть названия или ИНН в поле поиска. По умолчанию поиск идёт по организациям ГК и периметра; галочка
+   «Искать во всём справочнике (не только в группе)» расширяет его на весь справочник (нужно не меньше трёх символов).
+2. В таблице — «ИНН», «Организация», «ГК», «ГСК», «ГСЗ» и кнопка «Связать»; у уже связанной организации — неактивное
+   «Связано». Рекомендуемые совпадения показываются первыми.
+3. «Связать» сохраняет связь: имя контрагента из ОСВ закрепляется за организацией как псевдоним, строка получает ИНН и
+   тип контрагента, счётчик «Осталось» уменьшается.
+
+![Окно выбора организации](img/37-osv-map-modal.png)
+
+Сопоставление — правка версии, для неё нужна ваша блокировка (создание версии её не берёт). Если версия ещё не
+взята вами в работу, перед первой связью система спросит «Взять версию в работу?» с пояснением, что пока блокировка у вас, другие пользователи не смогут править версию;
+«Взять в работу» продолжает, «Отмена» прерывает. Если версия уже в работе у другого пользователя, связь невозможна —
+появится сообщение с его именем.
+
+Связь действует на все версии, в которые входит документ с этим контрагентом, и сохраняется для следующих периодов:
+в новой консолидации те же имена сопоставятся автоматически.
+
+## 11. Администрирование: пользователи и роли
+
+«Система → Пользователи и роли». Раздел доступен пользователю с правом администрирования (на стенде —
+`admin@armka.local`); остальным показывается «Нет доступа».
+
+Вкладка **«Пользователи»** — таблица: «Email», «ФИО», «Филиал», «Роли» (редактируются прямо в строке: добавить или снять
+роль в выпадающем списке), «Активен» (переключатель деактивирует пользователя).
+
+![Пользователи](img/40-admin-users.png)
+
+«Создать пользователя» → окно «Новый пользователь»: «Email» (обязателен; адреса в домене `.local` отклоняются),
+«ФИО» (обязательно), «Табельный номер», «Филиал» (обязателен), «Сегмент», «Роли». Созданный пользователь может войти
+сразу.
+
+![Новый пользователь](img/41-admin-create-user.png)
+
+Вкладка **«Матрица прав»** — таблица «право × роль» с галочками; роли системные. Изменения накапливаются и
+отправляются кнопкой «Сохранить», «Отменить изменения» возвращает исходное состояние.
+
+![Матрица прав](img/42-admin-matrix.png)
+
+Защита последнего администратора: нельзя снять роль ADMIN или право администрирования у единственного администратора и
+нельзя его деактивировать — сервер отвечает ошибкой, роли не меняются.
+
+Известный дефект этого экрана в прототипе: уведомления об успехе и ошибке не показываются; результат виден по
+обновлению таблицы или по ответу сервера во вкладке Network браузера.
+
+## 12. Статусы и термины
+
+**Статус версии консолидации** (бейдж в таблице консолидаций и в шапке сводной ОСВ):
+
+| Статус | Когда |
+|---|---|
+| Инициация | версия создана, документов ещё нет |
+| Обработка документов | есть загруженные файлы, распознавание не завершено |
+| Коррекция данных | документы распознаны, аналитик проверяет и сопоставляет данные |
+| Консолидация РФ, Верификация РФ, Консолидация ГО, Верифицирован, Отмена КФО | следующие этапы маршрута; в этой версии недостижимы |
+
+**Статус документа** (панель документов, экраны просмотра):
+
+| Статус | Значение |
+|---|---|
+| Обработка | файл принят, идёт распознавание |
+| Требуется проверка | распознан с замечаниями (шапка другой организации, не определён период, нарушения проверок) — нужна проверка и подтверждение аналитиком |
+| Загружен | подтверждён (автоматически или вручную), участвует в своде и чек-листе |
+| Ошибка | распознавание не удалось |
+| Отсутствует | в блоке «Организации»: документ этого типа за период не загружен |
+
+**Проверка документа**: «Период» — распознан ли отчётный период и попадает ли в период версии; «Контрагент» —
+совпадает ли организация из документа с ЮЛ, на которое он загружен.
+
+**Тип контрагента**: ГСК — участник группы связанных компаний версии; ГК — другая организация той же группы компаний;
+Внешний — все остальные.
+
+Сокращения: ГК — группа компаний; ГСК — группа связанных компаний; ГСЗ — группа связанных заёмщиков; ЮЛ — юридическое
+лицо (включая ИП); РФ — региональный филиал; ГО — головной офис; ОСВ — оборотно-сальдовая ведомость; ББ —
+бухгалтерский баланс; ОФР — отчёт о финансовых результатах; КФО — консолидированная финансовая отчётность.
+
+## 13. Ограничения текущей версии
+
+Это особенности прототипа, а не дефекты:
+
+- Нет экранов: справочники ГК/ЮЛ/ГСК, монозаёмщики, Единое хранилище, журнал действий, шахматка, корректировки,
+  гудвилл, КФО, смена статусов и маршрут согласования, «Добавить версию», редактирование состава версии, экран
+  чек-листа (только CSV), комментарии к документам, удаление файлов, правка строк ОСВ.
+- «ГСК» и «Дата верификации» в таблице консолидаций, «Утверждён в РФ» и «Верифицирован в ГО» всегда «—».
+- Таблица консолидаций и статус версии обновляются по F5; блок «Организации» перечитывается при закрытии панели
+  документов.
+- Панель документов показывает первые 100 файлов организации, все периоды вместе; загрузка возможна только из панели
+  организации внутри выбранной версии.
+- Документы типа «Прочий документ» (расшифровки) в панели не открываются.
+- Фильтр «Счёт» принимает только корень счёта; фильтр «Тип контрагента» — одно значение.
+- Шапку формы (ИНН, дату, единицу измерения) нельзя очистить, только заменить. Время принятия нарушений показывается
+  в часовом поясе браузера, остальные даты — по Москве.
+- Распознавание PDF на локальном стенде работает через эмулятор ИС Сканирование: распознаются только PDF из набора
+  тестовых данных (`fixtures/ocr`), остальные получают статус «Ошибка».
+- Уведомления в «Пользователи и роли» не появляются (дефект зарегистрирован).
+- Предупреждения в консоли браузера от библиотеки компонентов ни на что не влияют.
+
+## 14. Если что-то пошло не так
+
+- «Сессия истекла» — войдите заново (раздел 2).
+- Файл остаётся в «Обработке» дольше минуты — проверьте, что на стенде запущены сервисы распознавания
+  (`qa-guide.md`, раздел 4.2 и 12); панель продолжит опрашивать сервер сама.
+- Документ в статусе «Ошибка» — распознавание не удалось; для PDF на локальном стенде это ожидаемо для файлов вне
+  тестового набора.
+- Дефект — issue в Gitea: экраны — `RSHB/arm-web`, ответы сервера — `RSHB/arm-core`. Шаблон и как понять, чей баг —
+  `qa-guide.md`, раздел 11. Приложите скриншот экрана и запрос с ответом из вкладки Network.