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

Роль и задача

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

Контекст (что уже было)

Ранее ты выдал код-ревью с 10 находками (вместо описания). Все 10 уже исправлены (v2.0.15): критичный баг target_id vs target_hash (частичная сверка), Dockerfile, prompts CRUD, LLM-конфиг, XSS в compare.js, мелочи. Учти это — читай код после правок, описывай текущее состояние.

Сервис в двух словах

«Сверка договоров» — веб-приложение на Flask + vanilla JS (без фреймворков на фронте), на managed-кластере Nubes. Пользователь загружает договоры/допсоглашения (docx/pdf/zip), сервис: разбирает их в спецификации → классифицирует документы через LLM → группирует по договорам → по цепочке допников сравнивает изменения (ADD/UPDATE/DELETE) через LLM → показывает историю + чат по итоговой спецификации. Данные конфиденциальны, LLM — только своя (api.aillm.ru, gpt-oss-120b). Большие файлы грузятся через «ВМ-буфер» (браузер PUT на WebDAV → бэк тянет egress GET), т.к. шлюз кластера рвёт тела >~64 КБ.

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

Ядро бэкенда

site/app.py — точка входа, фабрика приложения, sys.path
site/config.py — конфигурация (версия, LLM, конвертер .doc, VM_UPLOAD_*)
site/llm_prompt.py — формирование промптов LLM (extract/diff/classify + fallback)
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) + трансляция target_id→hash
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 документов
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/, contracts-vm/, convert-service/, loadtest/, testgen/, sim/, dogovora/, hz/, FILES/, DOC/, deploy/ (устаревший VM-слой), site/services/drhider.py, site/templates/drhider.html|architect.html|pipeline.html|ci-cd.html.

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

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

Дополнительно: точечная проверка фикса #1

Отдельно, коротко (3–5 строк): в site/services/process.py глянь блок трансляции target_id ("r1","r2"…) → target_hash (через current_spec[_idx]["hash"]). Подтверди: корректно ли он маппит rN (1-based) на индекс current_spec, и что при невалидном id операция уходит в UNRESOLVED, а не падает. Если видишь ошибку — укажи, но НЕ правь.

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

Чётко, структурно, без воды и лирики.
Без излишней заумности — понятно не только девопсу, но и обычному разработчику/аналитику.
Ничего не менять в коде. Только текстовый документ.

7.7 KiB Raw Blame History Unescape Escape