DFiP_Budget_planing/openspec/changes/aurora-1850-upd-form-cells-subtree/proposal.md

Proposal

Why

Правка ячейки на сервере стоит столько же, сколько сборка всего листа. На стенде профилирования (perf/REPORT.md, М3; perf/report-data/20261026-s1/sql/coauthor/sql_top.json) правка на FORM_2/AHR в 1154 строки занимает 630 мс: v3.upd_form_cells дважды собирает лист через v3.v_form_view, по 310 мс на сборку. На листе в 2092 строки (после grow) правка занимает 1,46 с. WebSocket-соединение обрабатывает сообщения последовательно, поэтому потолок — около 1,6 правки/с (на 2092 строках около 0,7). Пользователь, который быстро вводит значения, видит, что подтверждения его правок отстают всё сильнее.

AURORA-1844 (PR #231, база этой ветки) убрала снимок «до» и _jsonb_diff. Теперь на правку приходится одна полная сборка. Её вызов вынесен в шов v3._form_affected_rows. Но и одна сборка — это около 310 мс, и время по-прежнему растёт с размером листа. Задача AURORA-1850 (Gitea #235, эпик AURORA-1834) убирает и её: правка собирает только затронутое поддерево, то есть изменённые строки и агрегаты их предков.

Критерий из Jira: правка ячейки на сервере занимает ≤ 50 мс независимо от размера листа, а суммы совпадают с полной сборкой (подтверждается тестом).

What Changes

• v3._form_affected_rows для FORM_1 и FORM_2 больше не вызывает v3.v_form_view и не собирает лист целиком. Касается листов AHR/CAP/OPER, сателлитов AHR_RENT/AHR_UTILITY/AHR_SECURITY, а также AHR_LIMIT и OTCH9F.
• В существующие построители листа (v3.v_form1_sheet_sections, v3.v_form2_sheet_sections и их вызывающие) добавляется параметр «фокус по строкам». Значение NULL означает прежнее поведение, то есть полный лист. Параллельной копии сборки нет: GET листа и ответ на правку считаются одним кодом.
• sort_order в ответе на правку остаётся глобальным: он совпадает с номером строки в полном GET того же листа с теми же параметрами.
• v3.get_form2_ahr_satellite_delta переводится на тот же механизм. Это фоновое обновление листа АХР после правки или добавления строки сателлита, и сейчас оно строит весь AHR. Правка миграции 0037 (сопоставление строк AHR_LIMIT со статьями глубины 4) сохраняется.
• FORM_4 остаётся на полной сборке, пока не слита AURORA-1846 (PR #232). Критерий производительности для FORM_4 переносится.
• Новая миграция 0051_upd_form_cells_subtree, номер — в стеке после 0050 из AURORA-1844. Номер может измениться при rebase (см. design.md).
• Новые интеграционные тесты эквивалентности сравнивают каждую строку ответа на правку с полным GET.

Не меняется:

• контракт HTTP (PATCH /form/{id}/sheet/{sheet}/cell(s)) и WebSocket (cell_updated): форма строк, состав строк, правила sections;
• содержимое GET листа. Исключение — детерминированный порядок строк при совпадении ключа сортировки (design.md, D6);
• проверки прав (v3.upd_form_cells с p_user_id, can_edit, computed_field), синхронизация сателлитов, v3._apply_form_cell;
• add_budget_line и del_budget_line: они по-прежнему отдают строки через полный v_form_view. Это задел на потом, не в этой задаче;
• фронт.

Capabilities

New Capabilities

• sheet-cell-edit: ответ на правку ячеек листа формы (HTTP и WebSocket), то есть состав строк, их содержимое и sort_order относительно полного GET; фоновое обновление АХР после правки сателлита; время правки на сервере. Каталог openspec/specs/ пока пуст, поэтому в спецификацию вместе с новыми требованиями попадает и контракт, установленный AURORA-1844.

Modified Capabilities

Нет.

Impact

• SQL (api/alembic/versions/): новая миграция 0051_*.py и sql/0051_*.sql. Пересоздаются v3.v_form2_sheet_sections, v3.v_form2_sheet_jsonb, v3.v_form2_view, v3.v_form1_sheet_sections и v3.v_form1_sheet_jsonb: у них меняется сигнатура, поэтому нужен DROP и CREATE. Появляется новая v3.v_form1_view. Переписываются v3.v_form_view (ветка FORM_1), v3._form_affected_rows и v3.get_form2_ahr_satellite_delta. Тело v_form2_view и get_form2_ahr_satellite_delta берётся из БД после миграции 0037.
• Python (api/src) не меняется: сигнатуры upd_form_cell(s) и get_form2_ahr_satellite_delta прежние.
• Тесты: api/tests/integration/ — эквивалентность на базе sheet_contract.py.
• ARCHITECTURE.md: абзац о _form_affected_rows дополняется описанием фокусной сборки.
• Связанные задачи:
  • AURORA-1844 — шов и контракт полных строк, обязательная предпосылка.
  • AURORA-1846 — FORM_4. После её слияния — отдельная задача на фокус FORM_4 по разделу, программе и проекту.
  • AURORA-1845 — сужена до кэша пользователя и формы на соединение. Пакетная обработка — отдельная неприоритетная задача. После 1850 ручной ввод не должен создавать очередь, это проверяется замером.
  • AURORA-1838 и AURORA-1848 — фронт ищет строку по (row_type, depth, sort_order), поэтому sort_order обязан быть точным. Явные null в строках ответа нужны для очистки ячеек.
  • AURORA-1831 и AURORA-1846 занимают номер миграции 0050 в параллельных PR.