105 lines
9.2 KiB
Markdown
105 lines
9.2 KiB
Markdown
# Задание для Sonnet: описание архитектуры сервиса «Сверка договоров»
|
||
|
||
## Роль и задача
|
||
|
||
Ты — технический аналитик. Твоя задача — **только прочитать указанные файлы** и написать
|
||
подробное, структурированное описание сервиса «Сверка договоров»: что это за сервис, как
|
||
устроен, как работает каждый этап, какими методами и технологиями. **Ничего не менять и
|
||
не создавать в коде.** Результат — один текстовый документ (markdown).
|
||
|
||
## Короткий контекст (чтобы ты понимал, о чём речь)
|
||
|
||
Сервис «Сверка договоров» — веб-приложение на **Flask + vanilla JS** (без фреймворков
|
||
на фронте), развёрнутое на managed-кластере Nubes (Штурвал). Пользователь загружает
|
||
договоры и допсоглашения (docx/pdf/zip), сервис:
|
||
1. разбирает их на структурированные спецификации;
|
||
2. автоматически классифицирует документы (тип/номер/дата/контрагент) через LLM;
|
||
3. группирует документы по договорам;
|
||
4. по цепочке допников сравнивает изменения спецификации (ADD/UPDATE/DELETE) через LLM;
|
||
5. показывает историю изменений и даёт возможность задать вопрос чату по итоговой спецификации.
|
||
|
||
Ключевое ограничение: данные конфиденциальны, 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` — не ядро сверки
|
||
|
||
## Что должно быть в ответе (структура)
|
||
|
||
1. **Описание сервиса** — что делает, кому, какие входы/выходы (2-4 абзаца, по-простому).
|
||
2. **Общая архитектура** — слои (фронт / бэк / БД / LLM / ВМ-буфер), как они связаны.
|
||
Лучше — схема потока: загрузка → парсинг → классификация → группировка → сравнение → чат.
|
||
3. **Структура проекта** — дерево `site/` (+ `upload/`) с назначением каждого файла.
|
||
4. **Как работает каждый этап** (по пунктам, «что делает / как / где в коде»):
|
||
- загрузка файлов (включая папки/архивы, ВМ-буфер, sink);
|
||
- парсинг PDF/DOCX/TXT → elements (таблицы + параграфы);
|
||
- классификация (garbage-фильтры, выжимка, LLM, параллельность);
|
||
- группировка (нормализация номеров, виртуальные группы, __unresolved__);
|
||
- сравнение (SSE-пайплайн, ops ADD/UPDATE/DELETE, event sourcing, spec_current);
|
||
- чат по итоговой спецификации.
|
||
5. **Технологии и методы** — коротко: SQLite (WAL, thread-local), SSE, ThreadPool, LLM-клиент,
|
||
промпты (из БД + fallback), event sourcing, метрики качества, ВМ-буфер загрузки.
|
||
6. **Модель данных** — таблицы БД и их назначение (documents, contracts, supplements,
|
||
spec_events, spec_current, prompts).
|
||
|
||
## Требования к стилю
|
||
|
||
- Чётко, структурно, без воды и лирики.
|
||
- Без излишней заумности — понятно не только девопсу, но и обычному разработчику/аналитику.
|
||
- Каждый этап: «что делает → как → каким методом → где в коде (файл/функция)».
|
||
- Ничего не менять в коде. Только текстовый документ.
|