Задание для Sonnet: описание архитектуры сервиса «Сверка договоров»

Роль и задача

Ты — технический аналитик. Твоя задача — только прочитать указанные файлы и написать подробное, структурированное описание сервиса «Сверка договоров»: что это за сервис, как устроен, как работает каждый этап, какими методами и технологиями. Ничего не менять и не создавать в коде. Результат — один текстовый документ (markdown).

Короткий контекст (чтобы ты понимал, о чём речь)

Сервис «Сверка договоров» — веб-приложение на Flask + vanilla JS (без фреймворков на фронте), развёрнутое на managed-кластере Nubes (Штурвал). Пользователь загружает договоры и допсоглашения (docx/pdf/zip), сервис:

разбирает их на структурированные спецификации;
автоматически классифицирует документы (тип/номер/дата/контрагент) через LLM;
группирует документы по договорам;
по цепочке допников сравнивает изменения спецификации (ADD/UPDATE/DELETE) через LLM;
показывает историю изменений и даёт возможность задать вопрос чату по итоговой спецификации.

Ключевое ограничение: данные конфиденциальны, LLM — только своя (api.aillm.ru, модель gpt-oss-120b). Большие файлы не грузятся напрямую в кластер (шлюз рвёт тела >~64 КБ) — используется «ВМ-буфер»: браузер кладёт файл на ВМ (WebDAV), а бэк сам тянет его исходящим запросом (egress не ограничен).

Что прочитать — ТОЛЬКО эти файлы (корень проекта: contracts-flask/)

Ядро бэкенда (обязательно, читать все)

site/app.py — точка входа, фабрика приложения, sys.path
site/config.py — конфигурация (версия, LLM_URL/KEY/MODEL, CONVERT_SERVICE_URL, VM_UPLOAD_*)
site/llm_prompt.py — формирование промптов LLM (извлечение/сравнение/классификация)
site/routes/__init__.py — регистрация всех blueprint'ов
site/routes/upload_bp.py — загрузка файлов (multipart + sink закачки через ВМ)
site/routes/pipeline_bp.py — классификация + SSE-сравнение (/process-v2, /api/classify-batch)
site/routes/api_bp.py — API (groups, documents, supplements, sync, cleanup, spec-current, chat)
site/routes/pages_bp.py — HTML-страницы + раздача ES-модулей upload/
site/routes/prompts_bp.py — CRUD и версионирование промптов
site/routes/health_bp.py — healthcheck
site/services/parse.py — парсинг PDF (pdfplumber), DOCX (python-docx), TXT
site/services/classify.py — LLM-классификация документов (garbage-фильтры, выжимка, ThreadPool)
site/services/grouping.py — нормализация номеров и группировка по договорам
site/services/process.py — SSE-пайплайн сравнения (run_pipeline)
site/services/llm.py — вызов LLM для сравнения (call_llm)
site/services/llm_client.py — LLM-клиент (HttpxLLMClient, FakeLLMClient для тестов)
site/services/metrics.py — проверка арифметики (sum == price*qty), метрики качества
site/db/connection.py — SQLite: схема всех таблиц, WAL, thread-local соединения
site/db/documents.py — CRUD документов (статусы, классификация, elements_json)
site/db/contracts.py — договоры
site/db/supplements.py — допники (связь contract↔document)
site/db/spec_events.py — event sourcing: apply_ops (ADD/UPDATE/DELETE), reset
site/db/spec_current.py — текущее состояние спецификации договора
site/db/prompts.py — версии промптов по ролям

Фронтенд (для понимания потока на стороне браузера)

site/static/state.js — центральное состояние приложения
site/static/app.js — инициализация, обработчики загрузки/классификации/сравнения
site/static/files.js — выбор файлов/папок/архивов, загрузка через ВМ-буфер
site/static/groups.js — классификация и группы на фронте
site/static/compare.js — сравнение (SSE) и рендер результатов
site/templates/index.html — разметка UI

Переиспользуемый модуль загрузки через ВМ (модуль upload/)

upload/README.md — описание модуля и паттерна «ВМ-буфер + pull»
upload/backend/upload_refs/blueprint.py — blueprint POST /api/upload_refs с параметром sink
upload/backend/upload_refs/safe_name.py, pull_file.py, config.py — транспортные примитивы
upload/backend/session/__init__.py — in-memory сессия (используется drhider; сверка его не использует)

Инфраструктура

Dockerfile — сборка образа
requirements.txt — зависимости

Что НЕ читать и не трогать

History/ — вся история сессий, ревью, старые планы (НЕ нужно)
contractor-legacy/ — замороженный Lucee-прод (не актуален)
contracts-vm/, convert-service/, loadtest/, testgen/, sim/, dogovora/, hz/, FILES/, DOC/ — смежные/вспомогательные, НЕ ядро сервиса
deploy/ — устаревший VM-слой (convert_server.py и т.п.), не входит в текущий managed-сервис
site/services/drhider.py — совместимость с DrHider (побочное, не ядро сверки)
site/templates/drhider.html, architect.html, pipeline.html, ci-cd.html — не ядро сверки

Что должно быть в ответе (структура)

Описание сервиса — что делает, кому, какие входы/выходы (2-4 абзаца, по-простому).
Общая архитектура — слои (фронт / бэк / БД / LLM / ВМ-буфер), как они связаны. Лучше — схема потока: загрузка → парсинг → классификация → группировка → сравнение → чат.
Структура проекта — дерево site/ (+ upload/) с назначением каждого файла.
Как работает каждый этап (по пунктам, «что делает / как / где в коде»):
- загрузка файлов (включая папки/архивы, ВМ-буфер, sink);
- парсинг PDF/DOCX/TXT → elements (таблицы + параграфы);
- классификация (garbage-фильтры, выжимка, LLM, параллельность);
- группировка (нормализация номеров, виртуальные группы, unresolved);
- сравнение (SSE-пайплайн, ops ADD/UPDATE/DELETE, event sourcing, spec_current);
- чат по итоговой спецификации.
Технологии и методы — коротко: SQLite (WAL, thread-local), SSE, ThreadPool, LLM-клиент, промпты (из БД + fallback), event sourcing, метрики качества, ВМ-буфер загрузки.
Модель данных — таблицы БД и их назначение (documents, contracts, supplements, spec_events, spec_current, prompts).

Требования к стилю

Чётко, структурно, без воды и лирики.
Без излишней заумности — понятно не только девопсу, но и обычному разработчику/аналитику.
Каждый этап: «что делает → как → каким методом → где в коде (файл/функция)».
Ничего не менять в коде. Только текстовый документ.

9.2 KiB Raw Permalink Blame History Unescape Escape