openspec/specs/intercompany-matrix-ui/spec.md

@@ -0,0 +1,184 @@
+# intercompany-matrix-ui Specification
+
+## Purpose
+Аналитик видит шахматку ВГО версии [31-01] (матрица Дт/Кт по компаниям с фильтрами компаний и счетов, единицами и полноэкранным режимом) и результирующую таблицу ВГО [31-01-01], выгружает обе в xlsx; суммы и итоги приходят с бэка, фронт их только форматирует.
+
+## Requirements
+
+### Requirement: Вкладки страницы отчёта по версии
+Страница `/groups/:group_id/versions/:version_id/:tab` SHALL показывать шапку версии (ГК, период, статус отчёта) один раз
+и под ней ряд вкладок шагов консолидации и содержимое активной вкладки. Активная вкладка определяется сегментом `:tab`:
+`osv` — «ОСВ» (сводная ОСВ), `chess` — «Шахматка». Выбор вкладки SHALL менять последний сегмент адреса на ключ вкладки
+(навигация, не локальное состояние), активная вкладка подсвечена зелёным и выделена жирным. Неизвестный ключ вкладки SHALL
+заменяться на `osv` без новой записи в истории браузера. Вкладки «Таблица корректировки», «Гудвилл», «КФО», «КФО Общий»,
+«Подтверждение КФО клиента» SHALL быть недоступны с подсказкой «Будет в следующих срезах». При смене `version_id` всё
+состояние страницы (карточка версии, данные, фильтры) SHALL создаваться заново.
+
+#### Scenario: Переход на шахматку
+- **WHEN** открыта сводная ОСВ версии по адресу `…/versions/{id}/osv` и нажата вкладка «Шахматка»
+- **THEN** адрес становится `…/versions/{id}/chess`, шапка версии остаётся, под вкладками показана шахматка
+
+#### Scenario: Прежний адрес сводной ОСВ
+- **WHEN** открыт адрес `…/versions/{id}/osv`
+- **THEN** показана сводная ОСВ, вкладка «ОСВ» активна
+
+#### Scenario: Неизвестная вкладка
+- **WHEN** открыт адрес `…/versions/{id}/abc`
+- **THEN** адрес заменяется на `…/versions/{id}/osv`, показана сводная ОСВ; кнопка «Назад» браузера не возвращает на `…/abc`
+
+### Requirement: Таблица шахматки ЮЛ × ЮЛ
+Экран SHALL загружать матрицу при открытии вкладки (`GET /consolidations/versions/{id}/intercompany-matrix/all`) и показывать
+таблицу: первая колонка «ДБ / КТ» (закреплена слева) — компании периметра в порядке ответа (`companies[]`), остальные колонки —
+те же компании. В ячейке пары (строка A, колонка Б) SHALL быть три числа друг под другом: сумма `amount_a`, сумма `amount_b`
+и расхождение `variance_amount` в скобках; расхождение выделяется красным, если `exceeds_threshold = true` или
+`one_sided = true` (пара без встречной стороны; правило подсветки — как в API и xlsx, AURORA-1651). Если у пары есть
+строки ОСВ без сопоставленного счёта (`skipped_osv_entry_count > 0`), рядом с первым числом SHALL показываться значок
+предупреждения с подсказкой «Строк ОСВ без сопоставленного счёта: N; в суммы не вошли». Если ячейки пары в ответе нет
+(в том числе на диагонали), SHALL показываться прочерк «—» на приглушённом фоне. Ниже таблицы закреплена строка «Итого»: до
+появления итогов в API (AURORA-1756, AURORA-1757) она временно считается на клиенте точным сложением десятичных строк — сумма
+`amount_a` по колонке видимых ячеек; итог, который не удалось сложить, показывается прочерком «—», а не нулём. Пока идёт
+загрузка, таблица показывает индикатор загрузки; ошибка API показывается уведомлением с текстом сервера. Панель фильтров
+показывает год и квартал версии неактивными полями «Год» и «Период» (например, `2024` и `К1`): версия задаётся адресом.
+
+#### Scenario: Ячейка с расхождением выше порога
+- **WHEN** для пары `(A, Б)` сервер вернул `exceeds_threshold = true`
+- **THEN** третье число ячейки (расхождение) показано красным, первые два — обычным цветом
+
+#### Scenario: Пара без встречной стороны
+- **WHEN** для пары `(A, Б)` сервер вернул `amount_b = 0`, `one_sided = true`, `exceeds_threshold = false`
+- **THEN** третье число ячейки (расхождение) показано красным
+
+#### Scenario: Пары нет в ответе
+- **WHEN** в `cells[]` нет ячейки для пары компаний
+- **THEN** на их пересечении показан прочерк «—»
+
+#### Scenario: Пропущенные строки ОСВ
+- **WHEN** у ячейки `skipped_osv_entry_count = 2`
+- **THEN** у первого числа ячейки виден значок предупреждения, подсказка — «Строк ОСВ без сопоставленного счёта: 2; в суммы не вошли»
+
+### Requirement: Результирующая таблица ВГО
+Под матрицей экран SHALL показывать результирующую таблицу ВГО, загруженную при открытии вкладки
+(`GET /consolidations/versions/{id}/intercompany-matrix/result-table`): первая колонка «Статья» — статьи ответа (`articles[]`,
+`name`) в порядке ответа, далее колонки компаний (`companies[]`) с суммой статьи по компании (`amounts[]` по `company_id`) и
+колонка «Итого» со значением `group_total` из ответа; пустая сумма — прочерк «—». Ниже таблицы закреплена строка «Итого»: до
+появления итогов в API (AURORA-1756, AURORA-1757) она временно считается на клиенте точным сложением сумм всех статей по
+колонке (итог, который не удалось сложить, — «—»). У таблицы свои выбор единиц и знаков (по правилам требования «Единицы и знаки», независимо от
+матрицы), кнопка «Экспорт» и кнопка «На весь экран». Пока идёт загрузка, таблица показывает индикатор; ошибка API (в том числе
+422 `RESULT_ACCOUNTS_MISSING`) показывается уведомлением с текстом сервера.
+
+#### Scenario: Колонка «Итого» из ответа
+- **WHEN** сервер вернул статью «Дебиторская задолженность» с `group_total = "1296510.00"`, выбраны «тыс. руб.» и 2 знака
+- **THEN** в колонке «Итого» этой статьи показано `1 296,51`
+
+#### Scenario: Нет обязательного счёта
+- **WHEN** сервер ответил 422 `RESULT_ACCOUNTS_MISSING`
+- **THEN** показано уведомление с текстом сервера, матрица шахматки при этом показывается как обычно
+
+### Requirement: Единицы и знаки
+Экран SHALL позволять выбрать единицы суммы — «руб.», «тыс. руб.» (по умолчанию), «млн. руб.», «млрд руб.» — и число знаков
+после запятой 0–3 (по умолчанию 2). Выбор применяется на клиенте к уже загруженным значениям (повторного запроса не делает):
+запятая сдвигается в десятичной строке на 3 / 6 / 9 разрядов, значение округляется до выбранного числа знаков (половина —
+от нуля) без перевода в число с плавающей точкой и показывается с разделителем разрядов и десятичной запятой. Значение,
+округлённое до нуля, показывается без минуса. Пустое значение — пустая ячейка. Значение, которое не удаётся прочитать как
+число, SHALL показываться как пришло — при любых единицах.
+
+#### Scenario: Смена единиц
+- **WHEN** выбраны «млн. руб.» и 1 знак, а сервер вернул `amount_a = "2346459.05"`
+- **THEN** в ячейке показано `2,3`
+
+#### Scenario: Точное округление
+- **WHEN** выбраны «тыс. руб.» и 2 знака, а сервер вернул `"1005"`
+- **THEN** показано `1,01` (не `1,00`, как дало бы округление числа с плавающей точкой)
+
+#### Scenario: Маленькая отрицательная сумма
+- **WHEN** выбраны «тыс. руб.» и 2 знака, а сервер вернул `"-4.00"`
+- **THEN** показано `0,00`, а не `-0,00`
+
+### Requirement: Фильтр компаний
+Выбор «Компании» (множественный, пустой выбор — «Все компании») SHALL ограничивать матрицу на клиенте: остаются строки и
+колонки выбранных компаний и ячейки, у которых обе компании выбраны. Запрос на сервер при этом не отправляется. Список
+вариантов — компании последнего загруженного ответа. Выпадающее окно выбора — дерево с поиском по названию, кнопками
+применения и сброса.
+
+#### Scenario: Две компании из периметра
+- **WHEN** выбраны две компании из пяти
+- **THEN** матрица содержит две строки и две колонки, «Итого» считается по оставшимся ячейкам
+
+### Requirement: Фильтр счетов Дт и Кт и режимы расчёта
+Экран SHALL загружать план счетов `GET /directories/accounts` один раз при открытии и строить из него два дерева по иерархии
+`parent_id`: дебетовые счета (`is_debit`) и кредитовые (`is_credit`); подпись узла — «код - название», в том числе у выбранных
+дочерних счетов в поле выбора. Выбор счетов Дт и Кт — множественный, пустой выбор — «Все счета».
+
+Отметки в дереве SHALL считаться по полному плану счетов: родительский счёт отмечен тогда и только тогда, когда отмечены все
+его потомки в полном дереве. Поиск по дереву скрывает не совпавшие узлы, но не меняет этого правила: отметка единственного
+видимого при поиске субсчёта не отмечает его родителя, а снятие отметки с субсчёта снимает её и с родителя. Скрытые поиском
+отметки при отметке видимых узлов сохраняются.
+
+Режим расчёта определяется выбором:
+- ничего не выбрано ни в Дт, ни в Кт — SHALL выполняться `GET …/intercompany-matrix/all` (режим `all`);
+- выбраны счета и в Дт, и в Кт — SHALL выполняться `POST …/intercompany-matrix/manual` с `{debit_account_ids,
+  credit_account_ids}` (режим `manual`);
+- выбрана только одна сторона — запрос SHALL NOT отправляться, таблица матрицы SHALL быть пустой и вместо данных показывать
+  текст «Для расчёта по счетам выберите счета и в Дт, и в Кт»; тот же текст SHALL показываться у фильтров Дт/Кт (не
+  всплывающим уведомлением) и только в этом состоянии; кнопка «Экспорт» матрицы SHALL быть недоступна.
+
+Каждое изменение выбора счетов, приводящее к режиму `all` или `manual`, перезапрашивает матрицу; на экране остаётся ответ на
+последний запрос, индикатор загрузки снимается и при переходе в состояние «выбрана одна сторона». Кнопка «Сбросить фильтры»
+появляется, когда выбрано что-либо в компаниях, Дт или Кт, и очищает все три выбора. Выбор единиц и знаков кнопкой не
+сбрасывается. Ошибка загрузки плана счетов показывается уведомлением.
+
+#### Scenario: Обе стороны выбраны
+- **WHEN** выбран счёт 60.01 в Дт и счёт 62.01 в Кт
+- **THEN** отправляется `POST …/intercompany-matrix/manual` с идентификаторами этих счетов и таблица показывает ответ
+
+#### Scenario: Выбрана одна сторона
+- **WHEN** выбран счёт только в Дт
+- **THEN** запрос матрицы не отправляется, таблица пуста и показывает «Для расчёта по счетам выберите счета и в Дт, и в Кт»,
+  тот же текст виден у фильтров, «Экспорт» матрицы недоступен, выбор Дт остаётся в фильтре
+
+#### Scenario: Выбрана одна сторона во время загрузки
+- **WHEN** выбраны Дт и Кт, запрос `manual` ещё выполняется, и пользователь очищает Кт
+- **THEN** индикатор загрузки снят, ответ прежнего запроса на экран не выводится, таблица в состоянии «выбрана одна сторона»
+
+#### Scenario: Поиск и отметка субсчёта
+- **WHEN** в дереве Дт введён поиск, видна ветка 60 с единственным субсчётом 60.02, и отмечен 60.02
+- **THEN** выбранным остаётся только 60.02; после сброса поиска счёт 60 и его прочие субсчета не отмечены
+
+#### Scenario: Снятие субсчёта отмеченного родителя
+- **WHEN** отмечен счёт 60 (отмечены 60, 60.01, 60.02) и снята отметка с 60.01
+- **THEN** выбранным остаётся 60.02, счёт 60 не отмечен
+
+#### Scenario: Сброс
+- **WHEN** выбраны компании и счета, нажато «Сбросить фильтры»
+- **THEN** все три выбора пусты, матрица перезапрошена в режиме `all`, кнопка исчезла
+
+### Requirement: Экспорт в XLSX
+Кнопка «Экспорт» матрицы SHALL скачивать XLSX в том же режиме, что и таблица: в режиме `manual` —
+`POST …/intercompany-matrix/manual/export` с телом `{debit_account_ids, credit_account_ids}`, в режиме `all` —
+`GET …/intercompany-matrix/all/export`; при выбранной одной стороне кнопка недоступна. Кнопка «Экспорт» результирующей таблицы
+SHALL скачивать `GET …/intercompany-matrix/result-table/export`. Файл сохраняется под именем из `Content-Disposition`, при его
+отсутствии — `Шахматка_<ГК>_<год>_<квартал>.xlsx` и `Результирующая_таблица_ВГО_<ГК>_<год>_<квартал>.xlsx` соответственно.
+Пока идёт выгрузка, в состоянии загрузки только нажатая кнопка; ошибка API показывается уведомлением. Фильтр компаний, единицы и
+знаки в запрос экспорта не передаются.
+
+#### Scenario: Экспорт по всем счетам
+- **WHEN** счета не выбраны и нажато «Экспорт» матрицы
+- **THEN** отправлен `GET …/intercompany-matrix/all/export`, браузер сохраняет файл `intercompany-matrix_….xlsx`
+
+#### Scenario: Экспорт результирующей таблицы
+- **WHEN** нажато «Экспорт» результирующей таблицы
+- **THEN** отправлен `GET …/intercompany-matrix/result-table/export`, кнопка «Экспорт» матрицы не переходит в состояние загрузки
+
+### Requirement: Полноэкранный режим
+Кнопка «На весь экран» матрицы и результирующей таблицы SHALL переводить свой блок (панель фильтров и таблицу) в
+полноэкранный режим средствами Fullscreen API с белым фоном и таблицей на высоту окна; в нём кнопка меняется на «Свернуть».
+Выпадающие списки фильтров и подсказки SHALL оставаться видимыми в полноэкранном режиме. Выход клавишей Esc SHALL возвращать
+обычный вид и подпись кнопки. Отказ браузера войти в полноэкранный режим показывается уведомлением.
+
+#### Scenario: Вход и выход
+- **WHEN** нажато «На весь экран», затем Esc
+- **THEN** блок разворачивается на весь экран, затем возвращается в страницу, кнопка снова «На весь экран»
+
+#### Scenario: Фильтр в полноэкранном режиме
+- **WHEN** матрица в полноэкранном режиме и открыт выбор «Компании»
+- **THEN** выпадающее окно видно поверх полноэкранного блока