contracts-flask/History/sonnet-review-comparison-only-2026-08-27.md

Промпт для Соннета: code review только собственно сверки

Нужно провести строгий code review только той части системы, которая выполняет собственно сверку документов после формирования группы.

Не анализируй и не ревьюируй upload, WebDAV/VM upload, ZIP-распаковку, выбор папки, дедупликацию файлов, парсинг DOC/DOCX, garbage-фильтры, классификацию документов, определение типа документа, matching/grouping документов и UI загрузки. Эти части находятся вне области данного ревью.

Контекст

Система получает уже сформированную группу договора и связанных документов. Затем она должна:

1. определить порядок документов группы;
2. получить текущую спецификацию;
3. передать текущую спецификацию и текст очередного документа в LLM;
4. получить операции ADD, UPDATE, DELETE, UNRESOLVED или режим full_replace;
5. корректно транслировать ссылки LLM на строки текущей спецификации;
6. применить операции к БД и сохранить историю событий;
7. отдать прогресс и результат через SSE;
8. показать пользователю фактический итог сверки.

Особенно проверь, что система не выдаёт успешный результат, если часть операций или документов фактически не обработана.

Файлы для обязательного изучения

Изучи только эти файлы и их прямые зависимости, необходимые для понимания сверки:

1. contracts-flask/site/services/process.py

   • основной pipeline сверки;
   • порядок документов;
   • получение текущей спецификации;
   • подготовка текста документа;
   • вызов LLM;
   • трансляция target_id в target_hash;
   • обработка full_replace;
   • применение операций;
   • арифметическая проверка;
   • SSE-события логического pipeline.

2. contracts-flask/site/routes/pipeline_bp.py

   • endpoint GET /process-v2;
   • генерация SSE;
   • heartbeat;
   • закрытие/обрыв соединения;
   • преобразование исключений в SSE-события;
   • различие HTTP-ошибки до начала стрима и ошибки внутри стрима.

3. contracts-flask/site/static/compare.js

   • startCompareSSE();
   • обработка extract_start, llm_done, applied, extract_error, apply_error, done, error;
   • обработка EventSource.onerror;
   • закрытие EventSource;
   • соответствие frontend-событий backend-событиям.

4. contracts-flask/site/static/app.js

   • функции запуска сверки группы;
   • вызов /api/apply-groups;
   • получение contract_id;
   • запуск /process-v2;
   • обработка success/error/connection error;
   • изменение состояния группы после завершения.

5. contracts-flask/site/services/llm.py

   • фактический вызов LLM для сверки;
   • формат prompt и ответа;
   • timeout/retry;
   • обработка невалидного ответа;
   • возможная потеря или искажение операций.

6. contracts-flask/site/llm_prompt.py

   • prompt сверки;
   • формат текущей спецификации;
   • формат ожидаемых операций;
   • ограничения для ADD, UPDATE, DELETE, UNRESOLVED, full_replace.

7. contracts-flask/site/db/spec_events.py

   • reset();
   • clear_current();
   • apply_ops();
   • транзакции и атомарность;
   • сохранение истории;
   • статусы применённых и неразрешённых операций;
   • поведение при частичной ошибке.

8. contracts-flask/site/db/spec_current.py

   • получение текущих строк спецификации;
   • идентификаторы и name_hash;
   • получение elements_json;
   • согласованность данных между текущим состоянием и историей.

9. contracts-flask/site/db/supplements.py

   • только функции, используемые process.py для получения документов уже сформированной группы;
   • порядок и фильтрация документов;
   • отсутствие/дублирование документов.

10. contracts-flask/site/services/metrics.py

    • check_arithmetic();
    • что именно проверяется;
    • может ли ошибка арифметики повлиять на результат;
    • почему проверка не должна маскировать ошибку применения.

Тесты для обязательного изучения

1. contracts-flask/tests/test_process_pipeline.py

   • какие сценарии реально покрыты;
   • корректность full_replace;
   • корректность трансляции target_id;
   • отсутствие тестов на реальные SSE и ошибки LLM.

2. contracts-flask/tests/test_grouping.py

   • только часть, необходимая для понимания структуры группы, передаваемой в apply_groups.

3. contracts-flask/tests/test_metrics.py

   • только тесты арифметической проверки, относящиеся к операциям сверки.

4. Найди все остальные тесты, которые напрямую вызывают run_pipeline, apply_ops, process-v2 или startCompareSSE, и включи их в анализ только если они действительно относятся к собственно сверке.

Что проверять

1. Корректность алгоритма сверки

• Не теряется ли первая спецификация или базовое состояние.
• Правильно ли строится current_spec перед каждым следующим документом.
• Гарантирован ли правильный порядок обработки документов.
• Не зависит ли порядок от нестабильного created_at или формата даты.
• Корректно ли работает переход между несколькими документами группы.
• Не дублируются ли строки при повторном запуске.
• Корректно ли работает full_replace при уже существующих строках.
• Может ли full_replace удалить корректные данные при ошибочном/неполном ответе LLM.

2. Операции LLM

• Как target_id переводится в фактический идентификатор строки.
• Что происходит при r0, r999, rX, отсутствующем target_id, неверном target_hash.
• Не может ли LLM обновить не ту строку из-за изменения порядка строк.
• Что происходит с неизвестными действиями.
• Что происходит с отсутствующими полями name, price, qty, sum, date_start.
• Не приводит ли частично валидная операция к тихой потере данных.
• Сохраняется ли исходный ответ LLM и prompt для аудита.
• Как обрабатываются пустой, обрезанный, markdown-обёрнутый или частично повреждённый JSON-ответ.

3. БД, транзакции и атомарность

• Атомарно ли применяются операции одного документа.
• Что происходит, если пятая операция из десяти падает.
• Может ли current state измениться, а event history не сохраниться, или наоборот.
• Не приводит ли reset() к потере истории при повторном запуске.
• Различаются ли applied, unresolved, failed и действительно ли эти статусы отражают результат.
• Безопасен ли параллельный запуск двух сравнений одного договора.
• Безопасен ли одновременный запуск сравнений разных групп.
• Есть ли race condition между apply-groups, /process-v2 и frontend state.

4. SSE и сетевые ошибки

• Совпадает ли событие завершения backend (complete или done) с событием, которое ожидает frontend.
• Может ли frontend навсегда оставить сравнение в состоянии ⏳.
• Что происходит при disconnect после applied, но до события завершения.
• Что происходит при heartbeat без данных.
• Может ли EventSource.onerror ошибочно объявить ошибку после нормального закрытия.
• Показывает ли UI частичный результат как полный.
• Есть ли таймаут на клиенте и сервере.
• Возвращается ли пользователю причина ошибки LLM/API, а не только «Ошибка соединения».
• Не теряются ли последние SSE-события из-за proxy buffering.

5. Числовая и предметная корректность

• Проверяется ли арифметика price * qty = sum до применения и после применения.
• Как обрабатываются None, строки с запятой, целые/дробные числа, отрицательные значения и большие числа.
• Не изменяет ли арифметическая проверка данные или только логирует ошибку.
• Может ли LLM вернуть арифметически неверную операцию, которая всё равно попадёт в current state.
• Сохраняется ли точность Decimal/float.
• Как обрабатываются даты и отсутствие даты.

6. Повторяемость и идемпотентность

• Что произойдёт при повторном нажатии «Сравнить эту группу».
• Можно ли безопасно повторить сравнение после сетевого обрыва.
• Будут ли повторно добавлены те же строки.
• Как отделяется новый запуск от предыдущей истории.
• Есть ли идентификатор запуска и защита от повторного применения одного ответа.

Обязательные вопросы от ревьюера

Ответь отдельно на следующие вопросы, даже если для ответа придётся изучить прямую зависимость:

1. Почему в реальном тесте один допник смог попасть в группу без базового договора, и может ли собственно pipeline сверки безопасно обработать такую неполную группу?
2. При каком именно условии run_pipeline() считает сверку успешной?
3. Может ли pipeline отправить complete, если один документ дал extract_error или часть операций не применилась?
4. Почему backend использует событие complete, а frontend-код может ожидать done? Это реальный баг или только устаревший комментарий/другая ветка?
5. Если LLM вернул full_replace с пустым ops, будет ли текущая спецификация очищена? Должно ли так происходить?
6. Если apply_ops() применил только часть операций, как это отражается в SSE и UI?
7. Есть ли транзакция, гарантирующая согласованность spec_current и spec_events?
8. Можно ли повторно запустить /process-v2 для того же contract_id без дублирования или повреждения результата?
9. Что происходит при одновременном сравнении двух групп, относящихся к одному договору?
10. Как система отличает «LLM вернул корректный пустой результат» от «LLM вернул повреждённый/неполный ответ»?
11. Какие операции считаются UNRESOLVED, где они сохраняются и видит ли их пользователь?
12. Может ли check_arithmetic() обнаружить ошибку, но pipeline всё равно завершиться успешно?
13. Какой минимальный набор интеграционных тестов нужен для доказательства корректности реальной сверки?
14. Какие риски остаются именно в собственно сверке после исключения upload/classify/grouping из области анализа?

Формат отчёта

Пиши отчёт в формате code review.

Сначала findings, отсортированные по серьёзности:

• BLOCKER — возможна потеря/порча данных или ложный успешный результат сверки;
• HIGH — неверное применение операций, нарушение атомарности, повторное применение или потеря результата;
• MEDIUM — ошибочное отображение статуса, частичный результат, нестабильность или отсутствие важной защиты;
• LOW — локальная проблема качества, диагностики или сопровождаемости.

Для каждого finding укажи:

• severity;
• файл и конкретный символ/участок кода;
• точную последовательность, которая приводит к проблеме;
• воспроизводимый сценарий;
• фактический ущерб;
• минимальное исправление;
• обязательный тест.

Не предлагай изменения вне области собственно сверки. Не исправляй код самостоятельно. Не делай общий обзор всего проекта. Если findings нет, напиши это явно и перечисли оставшиеся пробелы тестирования.

Жёсткое ограничение по стоимости

Не пиши код, патчи, diff и готовые реализации. Не изменяй файлы и не выполняй команды. Твоя задача — только code review: факты, findings, доказательства, вопросы и минимальные рекомендации словами. Любые предлагаемые исправления описывай концептуально, без реализации.

В конце добавь:

1. ответы на 14 обязательных вопросов;
2. таблицу покрытия тестами;
3. минимальный план исправлений, если они нужны;
4. список файлов, которые действительно были изучены.