arm-web/openspec/changes/statements-v2/design.md

Context

Реализация плана 6 сквозного change unified-statement-normalization (../docs/openspec/changes/unified-statement-normalization/, спека specs/arm-web/spec.md). Вся логика экрана — чистые функции в .ts с vitest-тестами, компоненты React только рисуют их результат. Черновик правок аналитика — одна структура StatementDraft, из которой одна функция собирает тело единственного PATCH. Подробный план — docs/superpowers/plans/2026-10-18-statements-v2.md.

Decisions made without discussion

Дата: 2026-10-18. Решения плана, принятые без обсуждения с владельцем; если решение неверно, цена ошибки — в последнем столбце.

Маркер	Решение	Обоснование	Цена ошибки
P6-1	Подсказка кода — StatementOut.edition_lines (справочник строк редакции формы, у формы без даты — всех редакций; план 3 P3-22), затем коды строк ok файла, которых в справочнике нет (имя — reference_name ?? line_name); отдельного запроса нет	справочник приходит с ответом формы	нет
P6-2	Якорь строки unreadable / missing — строка ok из источника (row_index не null) с наибольшим row_index меньше своего; якорь detail — строка ok из источника с row_index = parent_row_index; нет якоря (в том числе detail с parent_row_index = null или указывающим не на ok) — в начало первого раздела (после ведущих заголовков разделов; у ОФР — в начало таблицы). Вложение встаёт сразу после строки-якоря; несколько вложений одного якоря — по row_index	спека arm-web «Раскладка», S-62 («строка detail без родителя на экране — в начале раздела»), P3-17 (тот же порядок вложений в ответе ядра)	нет
P6-3	Скрытие (пустые подстроки, расшифровки) применяется после раскладки, фильтром	иначе скрытый якорь сдвинул бы вложения к соседу	нет
P6-4	Справочное имя (reference_name) — основное; файловое (line_name, после срезания приклеенных заголовков разделов) показывается вторым серым текстом, только если отличается после нормализации: нижний регистр, ё → е, оставлены только буквы и цифры	переносы OCR («задолжен-ность») не должны давать ложного «отличается»	лишнее или пропущенное второе имя — только показ
P6-5	Маркеры «у места» строятся из всех записей issues (в том числе relation / soft — у них line_ids + column_id); список IssuesPanel показывает только kind = warning; нарушения §7 остаются списком в ChecksPanel (из checks, с акцептом) и получают ссылку «Показать» по line_ids[0]. Запись с column_id без line_ids (например, COLUMN_WITHOUT_DATE) показывается у заголовка колонки; поле шапки, которого нет в блоке шапки, и строки, которых нет в ответе, — у документа	одна запись не дублируется в двух списках; заголовок колонки — естественное место для предупреждения о дате колонки	нет
P6-6	Подтверждение ячейки — в черновике; доступно, только если у строки есть id и у значения есть id (у достроенных ячеек — нет, ядро ответит UNKNOWN_CELL); сумма в черновике той же ячейки отменяет её подтверждение	PATCH: в элементе values ровно одно из amount / confirmed; правка суммы и так снимает needs_review	нет
P6-7	Одно действие на строку в черновике (code / detail / confirm), новое заменяет прежнее; пустое поле кода и код, равный текущему, — не действие; у достроенных шаблонных строк (id = null) действий строки нет	422 INVALID_LINE_PATCH при двух действиях; lines[] адресуется только line_id	нет
P6-8	Сумма в шаблонную строку по line_code X и назначение кода X другой строке в одном сохранении — ошибка черновика «Код X назначается строке, а в шаблонную строку X введены суммы — сохраните по очереди», запрос не уходит	ядро ответит 422 UNKNOWN_CELL (P3-10), а сообщение ядра не говорит, что делать	нет
P6-9	Ошибка элемента lines[] (409 LINE_CODE_TAKEN, 422 INVALID_LINE_CODE, INVALID_LINE_PATCH, UNKNOWN_LINE, LINE_CODE_REQUIRED) показывается у поля кода строки detail.line_id (текст сервера в подсказке поля и message.error); строки с этим id на экране нет — текстом над таблицей	ядро отдаёт detail.line_id и detail.line_code (план 3 P3-24)	нет
P6-10	Строка «неразобранная» для кнопки «Подтвердить данные» — line_status ∈ {unreadable, missing} и хотя бы у одного значения amount !== null или string_value !== null (ровно условие ядра для 409 LINES_UNRESOLVED)	кнопка и сервер считают одинаково	нет
P6-11	Подтверждение даты отчёта — кнопка «Подтвердить дату» у поля из needs_review_fields (уходит header.report_date тем же значением); дата колонки — поле ГГГГ-ММ-ДД у заголовка колонки (как поле даты отчёта) с кнопкой «Подтвердить дату», если дата есть и у колонки COLUMN_DATE_UNCERTAIN / COLUMN_WITHOUT_DATE	перепечатывать ту же дату ради подтверждения неочевидно; формат ввода — как у существующего поля даты	нет
P6-12	Панель файлов: у строки документа — значок с числом «предупреждения файла (job.warnings) + issue_counts.error + issue_counts.info» документа, красный при хотя бы одном error (в файле или issue_counts.error > 0); у строки файла без документов — только job.warnings; нуль — значка нет. Клик открывает список: предупреждения файла (message и locator), job.mapping_warnings (как info) и DocumentOut.issues документа, загружаемые при открытии (GET /documents/{id})	DocumentBrief.issue_counts (план 3 P3-23) помечает документ без запроса на каждый; подробности — по клику	акцептованное нарушение тоже даёт значок — подробности в списке
P6-13	job.warnings на клиенте нормализуется так же, как ядро: строка → {code: "LEGACY_WARNING", severity: "info", message, locator: null}, объект с code, severity ∈ {error, info}, message — как есть, прочее пропускается, не список → []	экран не падает при ошибке порядка выкладки	нет
P6-14	Сценарий T11 — на локальном стенде; строки unreadable / missing / detail и записи issues всех видов подставляются перехватом GET и PATCH …/statement (page.route) из фикстуры плана, пока сервисы шлют 1.x; на реальных формах 1.x — регрессия	до шага 5 выкладки 2.0-данных на стенде нет	повторный прогон на aep_3 после шага 5 — follow-up
P6-15	Цвета: ячейка needs_review — #fff7e6, исправлено — #e6f4ff, строка unreadable / missing целиком — #fff1f0, строка ok с needs_review — фон ячеек наименования и кода #fff7e6; подтверждённая ячейка — маленькая серая галочка перед суммой; уровень error — красный значок ExclamationCircleOutlined #cf1322, info — синий InfoCircleOutlined #1677ff	палитра уже используется на экране и в панели файлов	только вид
P6-16	Ячейка кода: ok — код; unreadable — серым line_code_text (пусто — «—»), подсказка «Код не распознан: «<текст>»»; missing — серым «—», подсказка «Кода в строке нет»; detail — пусто, подсказка «Расшифровка — в суммы формы не входит»; у ok в подсказке «Уверенность кода: N%» (если меньше 100 и код не правлен), «Код подтверждён», «Код назначен аналитиком»	спека: «в ячейке кода серым — сырой текст с подсказкой»	только вид
P6-17	header.source.<поле>.confidence — string | null (строка Decimal, как прочие уверенности API, план 3 P3-20), в подсказке — Number() и округление до целого	одно правило для всех уверенностей	нет
P6-18	node_modules worktree — симлинк на установленный каталог с eslint, prettier и vitest 3.1.4; поэтому вместо make check (он начинается с npm install и поставил бы пакеты в чужой каталог) гоняется make lint typecheck test build — те же проверки без установки	память владельца: симлинк, как в прежних срезах	нет; в описании PR сказано, что install пропущен
P6-19	Предупреждения ОСВ-документа (DocumentOut.issues, OSV_*) — блок IssuesPanel над таблицей экрана ОСВ, все записи — у документа (строки ОСВ не адресуются line_ids)	спека: «предупреждения листа ОСВ … из DocumentOut.issues[]»; экран документа уже загружает DocumentOut	нет
R-1	Шаги «сверка с макетом / прогон в браузере» (T3 s5, T4 s4, T7–T10) перенесены в T11 (дата 2026-10-18)	нет стенда ядра с v5.19, общий Playwright-браузер делят параллельные дорожки	визуальные дефекты найдутся позже, в T11
R-2	Ссылка «Показать» также у проверок со статусом soft_failed (дата 2026-10-18)	согласованное расширение: нарушение так же адресуется строкой	только показ
R-3	Компонент меню строки назван LineMenuButton.tsx, а не LineMenu.tsx (дата 2026-10-18)	на регистронезависимой ФС (macOS) LineMenu.tsx и lineMenu.ts дают TS1149	нет
O-1	Два MODIFIED-требования («Форма ББ/ОФР — просмотр и правка», «Подтверждение документа») составлены исполнителем из текущей спеки: в docs-спеке arm-web все требования ADDED. «Предупреждения ОСВ-документа» (P6-19) в docs-спеке нет; написано по плану. Сверить в arm-ka-docs#116 (дата 2026-10-18)	иначе change нельзя было бы описать дельтой	расхождение формулировок со спекой docs при архивации
T1.D-1	cellFlags возвращает ещё и confirmed; двум старым ожиданиям добавлен confirmed: false; тест «внимание по уверенности» заменён на «внимание только по needs_review» (дата 2026-10-18)	toEqual падает на новом ключе; так велит бриф	только тесты
T1.D-2	В тестовый хелпер doc() добавлен issue_counts: {error: 0, info: 0} (дата 2026-10-18)	поле обязательно в DocumentBrief, иначе падает tsc	нет
T1.D-3	Значения фикстуры statement-v2.json, которых нет в брифе, придуманы исполнителем (форматы сумм, уверенности, text, UUID, codes, сообщения, is_current, пустая колонка c2, порядок edition_lines) (дата 2026-10-18)	фикстура должна быть полной	тесты завязаны на выдуманные значения; реальные данные — в T11
T1.D-4	Фикстура приведена к StatementOut через as в тесте (дата 2026-10-18)	импорт JSON расширяет литералы до string; полноту проверяет рантайм-тест пар «строка × колонка»	слабая проверка типов фикстуры
T1.D-5	Тест «переносит поля v2» проверяет ключи по l-u7, code-1250, l-1230, l-d2 (дата 2026-10-18)	ровно как в брифе	нет
T3.D-1	Несколько строк подсказки кода склеиваются переводом строки; у codeModified уверенность не показывается (дата 2026-10-18)	читаемость подсказки	только вид
T3.D-2	Подсказка сумм принимает необязательный issues (добавляет message) (дата 2026-10-18)	задел для T4	нет
T3.D-3	Уверенность округляется Math.round(Number()) (P6-17) (дата 2026-10-18)	одно правило для всех уверенностей	нет
T3.D-4	В режиме правки у подтверждённой ячейки галочка — prefix поля ввода (дата 2026-10-18)	ячейка в режиме правки — Input	наложение значков, см. T8.D-3
T3.D-5	id строки row-<key> выставляется только на строках-линиях, не на заголовках разделов (дата 2026-10-18)	якорь прокрутки нужен только строкам	нет
T4.D-1	Подписи мест полей шапки: organization_name — «Организация», inn — «ИНН», report_date — «Дата отчёта», units — «Единица измерения»; неизвестное поле — своим кодом, запись уходит в document (дата 2026-10-18)	P6-5	только вид
T4.D-2	Запись с field из блока шапки всегда в byField, независимо от line_ids (дата 2026-10-18)	поле шапки — самостоятельное место	нет
T4.D-3	warning с line_ids без column_id — место «строка …», с column_id — «<строка>, колонка «…»»; relation / soft в список не входят (дата 2026-10-18)	P6-5	только вид
T4.D-5	onShow панелей передаёт ключ строки; для достроенных строк (id = null) перехода нет — line_ids их не содержат (дата 2026-10-18)	нет id — нет адреса	нет ссылки «Показать» у достроенной строки
T4.D-6	Значок у наименования строки — только по byRow; записи byCell дают значок только в ячейке (дата 2026-10-18)	не дублировать	только вид
T5.D-1	Кнопка «Подтвердить дату» рисуется только при переданном onConfirmDate (дата 2026-10-18)	иначе мёртвая кнопка	нет
T5.D-2	У организации в подсказке при modified — «Распознано: «…»»; нет source — подсказки нет (дата 2026-10-18)	нечего показывать	нет
T5.D-3	Уверенность в подсказке шапки через Number() ('67.00' → 67%) (дата 2026-10-18)	P6-17	нет
T5.D-4	Placeholder организации — «Наименование организации» (текст не из плана) (дата 2026-10-18)	поле в режиме правки должно быть подписано	только вид
T6.D-1	buildStatementPatch для суммы в неизвестную строку возвращает ошибку amount (раньше бросалось исключение) (дата 2026-10-18)	экран не должен падать	нет
T6.D-2	Подтверждение ячейки и действие строки у строк без id молча пропускаются (дата 2026-10-18)	UI их не создаёт (P6-6, P6-7)	молчаливая потеря действия при ошибке UI
T6.D-3	Код сравнивается после trim; пустой или равный текущему — не действие и не ошибка, проверка до формата (дата 2026-10-18)	P6-7	нет
T6.D-4	Конфликт P6-8 ищется по сумме в шаблонную строку (id = null) с тем же кодом; key ошибки — lineId строки с действием (дата 2026-10-18)	P6-8	нет
T6.D-5	Тексты ошибок: «Наименование организации — не длиннее 1000 символов» (длина организации); «Исправьте суммы с неверным форматом» (суммы, как раньше) (дата 2026-10-18)	тексты не из плана	только вид
T6.D-6	confirm_report_date при отсутствии текущей даты ничего не отправляет (дата 2026-10-18)	нечего подтверждать	пустое тело PATCH, «Сохранить» молчит
T6.D-7	Ошибка amount подсвечивает ячейку красной рамкой и сама по себе (дата 2026-10-18)	раньше подсветка шла только по разбору формата	только вид
T7.D-2	Подпись пункта меню: «Это расшифровка» для unreadable / missing, «Сделать расшифровкой» для ok (дата 2026-10-18)	разные смыслы действия	только вид
T7.D-3	Меню строки у ok — только при origin = 'source'; шаблонные строки с id меню не получают (дата 2026-10-18)	бриф	нет
T7.D-4	lineErrorTarget читает ApiError.body.detail (отдельного поля detail у ApiError нет) (дата 2026-10-18)	иначе деталей ошибки не достать	нет
T7.D-5	Ошибка сервера сбрасывается любой правкой черновика (в setDraft) (дата 2026-10-18)	иначе устаревшая ошибка висит после правки	нет
T7.D-6	У unreadable / missing с действием detail / confirm поле кода остаётся, рядом тег (дата 2026-10-18)	бриф: поле всегда	см. T7.2: очистка поля теряет действие
T8.D-1	Подтверждение ячейки без id значения молча пропускается в buildStatementPatch; кнопка не рисуется (cellConfirmState → null) (дата 2026-10-18)	P6-6	нет
T8.D-2	Ожидающая кнопка даты — disabled с текстом «Дата подтверждена (до сохранения)»; без ожидания «Подтвердить дату»; отменить подтверждение даты можно только отменой всей правки. Для колонки ожидание = черновая дата равна period_date. Затем текст подсказки при нажатой кнопке подтверждения ячейки: «Подтверждение будет сохранено — нажмите, чтобы убрать» (дата 2026-10-18)	пользователь должен видеть, что подтверждение в черновике	текст не из плана; ширина колонки (T8.2) проверяется в T11
T8.D-3	При значке записи у Input paddingLeft: 14, чтобы значок не перекрывал галочку (дата 2026-10-18)	без браузера не проверено	визуальное наложение; проверка в T11
T8.D-4	cellConfirmState возвращает pending-unconfirm при confirms[key] === false (дата 2026-10-18)	нужно третье состояние	нет
T8.D-5	Подтверждение ячейки только строкам с lineId (дата 2026-10-18)	P6-6, P6-7	нет
T9.D-1	«Значения есть» = `amount !== null		string_value !== nullпо любой ячейке;detail` не блокирует независимо от значений (дата 2026-10-18)
T9.D-2	Ключ ссылки в 409 LINES_UNRESOLVED — line_id (дата 2026-10-18)	ключ GridRow для строк из БД	ссылка молчит, если строки нет в таблице (T9.6)
T9.D-3	Описание Alert подтверждения собирается императивно (confirmDescription); приоритет: failures > lines > duplicate (дата 2026-10-18)	линтер запрещает вложенные тернарники	только вид
T10.D-1	toFileWarnings отбрасывает объекты без code / message или с severity не error / info (дата 2026-10-18)	P6-13	нет
T10.D-2	В режиме document у IssuesPanel колонка «место» не показывается; OsvDocument кладёт place '' / targetKey null (дата 2026-10-18)	у документа нет места	нет
T10.D-3	Подробности документа в поповере грузятся при открытии (trigger=click), состояние сбрасывается при закрытии (дата 2026-10-18)	P6-12	лишний запрос при повторном открытии
T10.D-4	Значок — <button> под плашкой статуса; без documentId раздел «Предупреждения документа» не показывается (дата 2026-10-18)	правила a11y	нет
T10.D-5	Пустой список в разделе «Предупреждения документа» — «Нет» (дата 2026-10-18)	текст не из плана	только вид
UI-1	Тексты, которых нет в плане: «Дата подтверждена (до сохранения)», «Подтверждение будет сохранено — нажмите, чтобы убрать», «Строка не найдена в форме», «Наименование организации — не длиннее 1000 символов» (дата 2026-10-18)	нужны для состояний, плана для них не было	только формулировки
T11.D-1	Колонки значений 128px вместо 112 (поле даты из 10 символов и сумма с галочкой обрезались), tableLayout='fixed' (дата 2026-10-18)	замечание T11.1: колонка «прыгала» при появлении кнопки даты	только вид
T11.D-2	Кнопка подтверждения даты — короткая «Подтвердить» / «Подтверждено», длинный текст «Подтвердить дату» / «Дата подтверждена (до сохранения)» в подсказке и aria-label (дата 2026-10-18)	фиксированная ширина колонки; отклонение от формулировки «Подтвердить дату» в P6-11	только подпись
T11.D-3	Ссылка «Разберите строки без кода: N» — Button type=link отдельной строкой над шапкой карточки, видна и в режиме правки (дата 2026-10-18)	клавиатурный доступ; строки нужно разбирать именно при правке	только вид
T11.D-4	Список предупреждений документа показывает первые 3 записи (ошибки первыми) и «Показать все (N)»; то же на экране ОСВ (дата 2026-10-18)	таблица уезжала ниже сгиба	только вид
T11.D-5	Значение со string_value без суммы показывается серым текстом, а не «-» (дата 2026-10-18)	аналитик должен видеть нераспознанный текст	только вид

Решения контроллера и исполнителей поверх плана (R-n, O-n) дописываются сюда по ходу исполнения.