185 lines
20 KiB
Markdown
185 lines
20 KiB
Markdown
# 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** выпадающее окно видно поверх полноэкранного блока
|