DFiP_Budget_planing/openspec/specs/realtime-sheet-updates/spec.md

realtime-sheet-updates Specification

Purpose

Как редактируемая таблица фронта (лист формы, отчёт проекта) применяет входящие правки соавторов и эхо собственных правок к уже загруженным строкам и как она показывает значения, которых нет в строке. Цель — чтобы правки не терялись, даже если строки загружены без null-полей.

Requirements

Requirement: Входящая правка применяется к отсутствующему ключу

Когда приходит обновление строк — сообщение WebSocket cell_updated или ответ PATCH на собственную правку — фронт SHALL записать в найденную строку каждое поле из обновления, на любой глубине. Это делается и тогда, когда ключа этого поля или содержащего его блока в загруженной строке нет. Правка SHALL NOT теряться из-за того, что при загрузке листа поле было опущено.

Scenario: Соавтор заполняет пустую ячейку

• WHEN лист загружен без ключа data.q1.<поле> у строки (ячейка пустая), а соавтор вводит в эту ячейку значение
• THEN у пользователя ячейка показывает новое значение без перезагрузки листа

Scenario: Отсутствует весь блок

• WHEN в загруженной строке нет ключа блока data.<блок>, а приходит обновление с data.<блок>.<поле>
• THEN в строке появляется блок с этим полем, а ячейка показывает значение

Scenario: Прочие поля строки сохраняются

• WHEN приходит обновление одного поля строки
• THEN остальные поля строки сохраняют прежние значения

Requirement: Очистка ячейки доходит до соавторов

Если в обновлении поле равно null, фронт SHALL записать null, и ячейка SHALL показываться пустой.

Scenario: Соавтор очищает ячейку

• WHEN у пользователя ячейка показывает значение, а соавтор очищает её
• THEN у пользователя ячейка становится пустой без перезагрузки листа

Requirement: Отсутствующее значение показывается как null

Если ключа нет в data, редактируемая таблица, свод 1 и свод 2 SHALL показывать и обрабатывать значение так же, как явный null. Отображение: пустая ячейка в листе, «—» в сводах. Правила подсветки ошибок валидации не срабатывают. Поиск и фильтр по колонке не находят такую ячейку по непустому запросу. При входе в редактирование поле ввода пустое. Правка, которую фронт отправляет по WebSocket, SHALL всегда содержать ключ value; пустое значение передаётся как null, а не опускается.

Scenario: Выход из пустой ячейки без ввода

• WHEN пользователь входит в редактирование ячейки, ключа которой нет в строке, и выходит без ввода
• THEN сообщение cell_updated содержит "value": null, как и для ячейки с явным null, а пользователь не получает ошибку

Scenario: Пустая ячейка свода 2

• WHEN свод 2 загружен без ключа data.q1.<поле> у строки
• THEN ячейка показывает «—», как и для null

Scenario: Валидация не срабатывает

• WHEN у строки листа отсутствует ключ поля, к которому привязано правило валидации (например, остаток бронирования)
• THEN ячейка не подсвечивается как ошибочная