102 lines
7.7 KiB
Markdown
102 lines
7.7 KiB
Markdown
# Задание для 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`.
|
||
|
||
## Что должно быть в ответе (структура)
|
||
|
||
1. **Описание сервиса** — что делает, входы/выходы (2–4 абзаца, по-простому).
|
||
2. **Общая архитектура** — слои (фронт/бэк/БД/LLM/ВМ-буфер) + схема потока:
|
||
загрузка → парсинг → классификация → группировка → сравнение → чат.
|
||
3. **Структура проекта** — дерево `site/` (+ `upload/`) с назначением каждого файла.
|
||
4. **Как работает каждый этап** — «что делает → как → каким методом → где в коде (файл/функция)».
|
||
5. **Технологии и методы** — SQLite (WAL, thread-local), SSE, ThreadPool, LLM-клиент,
|
||
промпты (БД + fallback), event sourcing, метрики качества, ВМ-буфер.
|
||
6. **Модель данных** — таблицы и назначение (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, а не падает. Если видишь ошибку — укажи, но НЕ правь.
|
||
|
||
## Требования к стилю
|
||
|
||
- Чётко, структурно, без воды и лирики.
|
||
- Без излишней заумности — понятно не только девопсу, но и обычному разработчику/аналитику.
|
||
- Ничего не менять в коде. Только текстовый документ.
|