arm-core/openspec/changes/consolidations-ui/design.md

## Context

PR RSHB/arm-core#166 (ветка `AURORA-1589`, автор — Степанов, задача AURORA-1589) доводит до макета экраны консолидаций:
список консолидаций ГК [34] (`widgets/ConsoleTable/`), модалку «Взять в работу» и перехват [35]
(`widgets/ConsoleTable/LockModal.tsx`), панель «Организации» (`widgets/ConsoleLegalEntities/`), модалку «Новая
консолидация» [42] (`widgets/NewConsoleModal/`, строка ЮЛ — `CompanyOptionRow.tsx`), кнопку «Изменить статус» в шапке
карточки версии [30] (`layouts/ConsolidatedOsvPage.tsx`) и модалку [33-01] (`widgets/StatusChangeModal/ChangeStatusModal.tsx`).
Бэкенд — спека `consolidations-api` (список с `in_work_only`, «Взять в работу, перехват, снятие», «Статусы Среза 4»); API не
меняется. В ветку добавлена вторая библиотека иконок `lucide-react` (иконки макета: меню «⋯», «Взять в работу», «К
отчётности», боковое меню).

Спеку, документацию и тесты ведёт ревьюер коммитами в ветку автора (правило владельца для чужих PR); продуктовый код
правит автор. Спека описывает **целевое** поведение; расхождения кода ветки (коммит 71ef633) — раздел «Known issues».
Источники: макет [34], [35], [42], [30], [33-01], [33], [31-00] (`docs/mockup/INDEX.md`), описание AURORA-1589, ТЗ
«Статусная модель» (`docs/source/tz/…08_4. Статусная модель.md`), гайд фронта по API §5.7.

## Decisions

- **D-1. Ручные переходы — зеркало `MANUAL_TRANSITIONS` во фронте.** API не отдаёт допустимые переходы (в `VersionCard`
  нет `allowed_transitions`, заметка AURORA-1589 от 12.10.2026). Фронт держит одну константу «статус → допустимые ручные
  переходы», совпадающую с `api/src/services/consolidation_status.py`: `INITIATED → {CANCELLED}`,
  `DOCUMENTS_PROCESSING → {CANCELLED, INITIATED}`, `DATA_CORRECTION → {CANCELLED, INITIATED}`. С маршрутом согласования
  (Срез 7) константа заменяется ответом API без переделки модалки. Расхождение константы с бэком сервер ловит 409
  `TRANSITION_NOT_ALLOWED`; заметка о зеркале — в гайде фронта §5.7 (PR в RSHB/arm-ka-docs).
- **D-2. Комментарий обязателен для обоих ручных переходов** (AURORA-1589): для `CANCELLED` его требует и сервер (422
  `COMMENT_REQUIRED`), для возврата в `INITIATED` — только фронт.
- **D-3. «Изменить статус» доступна по `lock` карточки и `/me`**: активна, если `lock.locked_by` = текущий пользователь и в
  D-1 есть переходы из текущего статуса. Подсказка «Возьмите консолидацию в работу» (текст задачи AURORA-1589).
- **D-4. После смены статуса экран берёт карточку из ответа** `POST …/status` (`VersionCard`), без повторного
  `GET`: бейдж, пояснение и кнопка обновляются сразу; после `CANCELLED` сервер снимает блокировку, кнопка становится
  неактивной.
- **D-5. По умолчанию в «Новом этапе» ничего не выбрано** (ревью раунда 1): в макете [33-01] предложен следующий этап, но
  сейчас один из двух вариантов — необратимая «Отменена», и случайная отправка по умолчанию недопустима.
- **D-6. «Только в работе» — серверный фильтр `in_work_only`**, по умолчанию выключен (макет [34], значение API по
  умолчанию `false`). Фронт не фильтрует по статусу сам: множество «в работе» для списка определяет сервер.
- **D-7. Модалка [35] читает свежую карточку версии** перед показом: данные `lock` строки списка могут устареть. Перехват —
  в той же модалке: при известной чужой блокировке сразу поле причины, при 409 `LOCKED_BY_OTHER` (гонка) — предупреждение
  и поле причины.
- **D-8. ГСК в API нет (решение владельца П-3)**: колонка «ГСК» — «—», в тексте модалки [35] вместо ГСК макета — ГК
  (`company_group.name` карточки).
- **D-9. Подпись `CANCELLED` — «Отменена»** (AURORA-1589, ревью): в ТЗ «Статусная модель» — «Отменен», в словаре UI
  `10-user-journey.md` — «Отмена КФО»; выбран вариант задачи (согласование с «консолидацией»). «Корректировка данных» —
  как в ТЗ (было «Коррекция данных»).
- **D-10. Кнопку «Взять в работу» блокирует код статуса `CANCELLED`, а не подпись** — подпись меняется (D-9), условие по
  подписи ломается молча.

## Known issues

Расхождения кода ветки `AURORA-1589` (71ef633) с целевой спекой — по пунктам ревью раунда 1; исправляет автор PR.

1. **404 при смене статуса.** `services/api/consolidations.ts` `updateStatus` шлёт `POST /consolidation/versions/{id}/status`
   (нет «s»); нужен `/consolidations/versions/{id}/status`.
2. **Переходы — заглушка `mockStatusMappingFetch()` внутри модалки** (`ChangeStatusModal.tsx`). Нужна одна константа (D-1)
   рядом с подписями статусов. Для статусов без переходов сейчас `nextStatusOptions = undefined`: форма скрыта, кнопка
   «Изменить статус» в шапке при этом активна.
3. **«Новый этап» предвыбран** (`initialValues.to_status = nextStatusOptions[0]`, на стенде — «Отменён»); нужно пусто (D-5).
4. **Кнопка «Изменить статус»**: подсказка «Сначала возьмите версию в работу» вместо «Возьмите консолидацию в работу»;
   отсутствие ручных переходов не учитывается (при своей блокировке `VERIFIED` кнопка активна, модалка пустая).
5. **Колонка «Версия» инвертирована** (`ConsoleTable/config.tsx`): показывает «1» и скрывает 2+; нужно наоборот.
6. **«Только в работе» включён по умолчанию** (`ConsoleTable.tsx`: `searchParams.get('in_work_only') || true`, флажок
   отмечен, пока параметр не `'false'`); нужно выключен (D-6).
7. **Пункты «⋯» не `disabled`**: у них только класс `ant-dropdown-menu-item-disabled`, клик обрабатывается
   («История изменений» ведёт в пустой «Журнал действий», остальные — `message.info('Будет позже')`); в `ITEMS` лишний
   пустой элемент `{}`.
8. **Подпись `CANCELLED` — «Отменён»** (нужно «Отменена», D-9); «Взять в работу» блокируется сравнением
   `row.status === 'Отменён'` — после переименования условие перестанет срабатывать (D-10).
9. **Перехват [35]**: плейсхолдер поля причины «Type message»; проверка длины `< 1000` вместо `≤ 1000`; квартал в тексте —
   `Q3` вместо «К3»; опечатки «обнаржуена», «нформацию».
10. **Пояснение под заголовком**: для `INITIATED`, `DOCUMENTS_PROCESSING`, `DATA_CORRECTION` повторяется название статуса;
    тексты `VERIFIED` и `CONSOLIDATION_RF` в `consStatusDescriptionMapping` расходятся с макетом [30], [33-01].
11. **Модалка [31-00] «Остались неуказанные ИНН»** не реализована. Другие вкладки отчёта в ветке пока неактивны
    (`OsvTabs`), поэтому сценарий проверяется после появления вкладки «Шахматка» (PR #158) или в нём же.
12. **«+ Создать» активна при одном отмеченном ЮЛ** (`NewConsoleModal.tsx`, `!legEntIds?.length`); нужно не меньше двух
    (сервер отвечает 422 `PERIMETER_TOO_SMALL`).
13. **Модалка «Изменить статус», замечено при написании спеки** (в комментарий ревью раунда 1 не вошло): ошибка
    `getVersionCard` не обрабатывается — модалка остаётся в загрузке; `comment.trim()` вызывается на значении
    `Form.useWatch`, которое до монтирования формы `undefined`.
14. **Тестов нет.** Чистые правила (подпись версии, переходы, активность кнопок, параметр `in_work_only`) зашиты в
    компоненты; тесты vitest — после их выноса в чистые функции (`tasks.md`).
15. **`lucide-react@0.263.1` в зеркале npm банка не проверен.** Пакет в `dependencies`, снимок контура его оставляет
    (`docs/dev/contour-transfer-guide.md` §3.2); если версии нет в Nexus, сборка в контуре упадёт.
16. **Предупреждение браузера о несохранённых правках** (пункт AURORA-1589) не реализовано; в спеку не входит (решение (е)).

## Decisions made without discussion

- **2026-10-23 (а). Новая capability `consolidations-ui`; `consolidation-setup` и `consolidated-osv-ui` не правятся.** Вид
  модалки [42], шапка карточки версии и модалка [31-00] описаны в новой спеке; состав модалки [42], создание и «К
  отчётности» остаются в `consolidation-setup`, сводная ОСВ — в `consolidated-osv-ui`. Обоснование: не смешивать дельты
  трёх спек в одном PR фронта. Цена ошибки: при архивации модалку [42] и страницу отчёта описывают по две спеки; сведение —
  MODIFIED-дельтой позже.
- **2026-10-23 (б). Временные пояснения статусов первой очереди и `CANCELLED` — дословные фрагменты ТЗ «Статусная
  модель»** (колонка «Описание»), пока аналитик не дал тексты (AURORA-1589: «тексты для статусов первой очереди — у
  аналитика»); для `VERIFIED` и `CONSOLIDATION_RF` — тексты макета вместо текстов автора. Обоснование: подзаголовок не
  должен повторять название статуса, а придумывать формулировки нельзя. Цена ошибки: замена строк в одном месте.
- **2026-10-23 (в). Порядок версий в дереве — как в ответе API** (сверху последняя версия периода, под ней предыдущие), как
  в `main`. В макете [34] версия 1 стоит сверху, версия 2 — под ней. Цена ошибки: правка `flatten.ts` / `groupAdjacent.ts`
  и MODIFIED требования «Список консолидаций ГК».
- **2026-10-23 (г). Минимум два ЮЛ для «+ Создать»** — из описания [42] в `docs/mockup/INDEX.md` («минимум 2») и 422
  `PERIMETER_TOO_SMALL`; фронт блокирует раньше сервера. Цена ошибки: одно условие.
- **2026-10-23 (д). Модалка [31-00] — только при переходе на другую вкладку отчёта**, не при «Назад» и переходах по меню.
  Открытые вопросы владельцу: (1) нужно ли предупреждать и при уходе со страницы отчёта; (2) AURORA-1589: «на реальных
  данных в счётчик попадают строки, которые не являются организациями… до нуля он не доводится» — поведение согласовать с
  задачей «Блокировка шага до сопоставления контрагентов без ИНН»; до решения модалка не блокирует переход. Цена ошибки:
  расширение триггера — MODIFIED требования.
- **2026-10-23 (е). Предупреждение браузера о несохранённых правках не включено в спеку**: пункт задачи касается всех форм
  и модалок приложения, а не экранов консолидаций; остаётся задачей автора в `tasks.md`. Цена ошибки: требование появится
  отдельной спекой (или дельтой) позже.
- **2026-10-23 (ж). Подпись `DOCUMENTS_PROCESSING` оставлена «Обработка документов»** (как в `main`); в ТЗ — «Загрузка,
  распознавание и корректировка документов», в словаре UI — «Загрузка и распознавание документов». Вопрос аналитику.
  Цена ошибки: замена одной подписи.
- **2026-10-23 (з). Тексты сообщений об ошибках 409/422 в модалке «Изменить статус» не фиксируются дословно**: спека
  требует сообщение и открытую модалку. Цена ошибки: низкая.
- **2026-10-23 (и). В ветку влит `origin/main`** (шахматка «пара без встречной стороны» PR #165 и архивы OpenSpec
  PR #160, #167, #168) — без конфликтов; файлы `web/` ветки слиянием не затронуты. Цена ошибки: низкая, PR и так
  сливается в этот `main`.
- **2026-10-23 (к). «Единицы» и «Знаков после запятой» сводной ОСВ (коммит 71ef633, AURORA-1539) в спеку не включены** —
  автору предложено вынести их в отдельный PR. Цена ошибки: если коммит останется в PR, его поведение будет без спеки.