🏗️ Архитектура — сверка договоров

Пайплайн: загрузка → парсинг → классификация → группировка → сравнение → аудит

1. Загрузка файлов

Пользователь выбирает .docx / .pdf / .doc / .zip.

PDF: pdfplumber извлекает текст и таблицы с сохранением структуры колонок
DOCX: python-docx читает XML — извлекает параграфы и таблицы построчно
DOC: обрабатывается как DOCX (python-docx читает большинство .doc)
ZIP: архив распаковывается с лимитом 500 файлов и проверкой на сжатие (защита от ZIP-бомбы). Каждый файл внутри проходит тот же путь загрузки
Файлы не поддерживаемых форматов — отклоняются с пометкой unknown_format

Результат: elements_json — массив элементов двух типов:

{type: "paragraph", text: "...", style: "..."}
{type: "table", rows: [["колонка1", "колонка2"], ...]}

Документ сохраняется в БД, считается content_hash (SHA-256) — если в этом же батче уже есть файл с таким содержимым, он помечается как duplicate и не дублируется.

📋 Заказчик: «100+ файлов за раз. Файлы: .docx/.pdf, возможно ZIP.
Загрузка из локали (файловая шара / облачный диск), НЕ S3 (конфиденциальность).»

2. Классификация документов

Каждый загруженный файл проходит трёхэтапный фильтр.

📋 Заказчик: «Оставлять только: договоры, доп. соглашения, спецификации.
Игнорировать: акты сверки, счета/счета-фактуры/УПД, акты услуг, платёжки.»

Этап 1 — имя файла 0 токенов

Проверка имени файла на мусорные ключевые слова: «счёт», «акт», «платёж», «УПД», «сверка», «invoice» и др. Совпадение → garbage, дальше не идёт.

Этап 2 — заголовки в тексте 0 токенов

Проверка первых 2000 символов текста на заголовки: «СЧЕТ-ФАКТУРА», «АКТ СВЕРКИ», «АКТ ОКАЗАННЫХ УСЛУГ» и т.п. Совпадение → garbage.

📋 Заказчик: «Названия документов неинформативные. Есть лишние документы.
По всем контрагентам.»

Этап 3 — LLM LLM

Оставшиеся документы отправляются в LLM. Модель получает выжимку текста (первые 1500 символов + строки с маркерами «договор», «соглашение», «спецификация») и возвращает JSON:

doc_type — contract / supplement / specification / other
own_number — номер этого документа
parent_number — номер родительского договора (для допников и спецификаций)
doc_date — дата документа YYYY-MM-DD
counterparty — название контрагента

📋 Заказчик: «НУБЕС = Исполнитель во всех целевых договорах.»
→ counterparty = другая сторона (Заказчик).

3. Группировка по договорам

Детерминированная (без LLM). Документы группируются по номерам договоров.

📋 Заказчик: «Система сама должна разбираться, кто к кому.
зачем нам базовый договор? Вся информация есть в допниках и спеках.»
«Я не должен распознавать ничего. Система должна сделать всё.»

Номера нормализуются: uppercase, удаляются все символы кроме букв и цифр.
«МЭС-123/2024» → «МЭС1232024»
Допники и спецификации с одинаковым parent_number попадают в одну виртуальную группу — даже если сам договор не загружен
Неопознанные файлы → отдельная группа «Не распознано» с указанием причины

4. Сравнение — извлечение + дифф

Для каждой группы запускается последовательная обработка.

📋 Заказчик: «Важно. В произвольной, не повторяющейся.» (порядок допников)
«Главное — точность разбора, не UI. Сначала базовая функция → потом юзабельность.»

4a. Сортировка

Документы внутри группы сортируются по doc_date (из классификации), затем по времени загрузки.

4b. Базовый договор (первый в группе) LLM

Текст спецификации услуг → LLM с промптом extract
LLM получает текст и инструкцию «найди таблицу услуг, извлеки каждую строку как ADD»
Ответ: массив операций ADD — каждая услуга с полями: название, цена, количество, сумма, дата начала

4c. Дополнительные соглашения LLM

Текущая спецификация + текст допника → LLM с промптом diff
LLM определяет изменения:
- ADD — новая услуга
- UPDATE — изменение цены/количества/суммы
- DELETE — услуга исключена

4d. Режим «изложить в новой редакции»

Если допник говорит «изложить в новой редакции» — LLM возвращает полный новый список (full_replace). Все старые строки заменяются новыми.

5. Защита и валидация валидация

ADD без имени услуги → UNRESOLVED (не применяется, помечается для ручной проверки)
UPDATE/DELETE с пустым идентификатором → UNRESOLVED
Арифметика: sum = price × qty — расхождение → флаг
Дубликаты: content_hash — один и тот же файл дважды не обрабатывается
Даты: 01.03.2026 → 2026-03-01 (авто-нормализация)
Числа: 1 000,50 → 1000.50 (авто-нормализация)

📋 Заказчик: «кривых документов можно ожидать.
Если не может разобраться — пусть зовет на помощь юзера.»

6. Event Sourcing — аудит аудит

📋 Заказчик: «Наверно я захочу иметь возможность посмотреть любые промежуточные результаты.
Было бы хорошо пояснить или показать процесс, что в каком порядке происходит.»

spec_events: полный лог всех операций. Каждое событие содержит:
- тип (ADD/UPDATE/DELETE/UNRESOLVED)
- источник — какой документ
- версия промпта
- полный сырой ответ LLM
- временную метку
spec_current: материализованное представление = сумма всех событий
Промежуточные результаты: для каждого файла доступны:
- текст, отправленный в LLM
- сырой ответ LLM
- распарсенный JSON операций
- какие операции были применены

7. Промпты LLM

Три роли промптов, хранятся в БД с версионированием:

Роль	Назначение
`extract`	Извлечение строк спецификации из договора
`diff`	Сравнение допников с текущей спецификацией
`classify`	Определение типа/номера/даты/контрагента документа

Встроенный редактор с историей версий: сохранил новую версию → она сразу используется LLM. Старые версии остаются в истории — можно откатиться.

8. Стек технологий

Компонент	Где	Технология
Веб-интерфейс	Managed Python (Nubes)	Python 3.12, Jinja2, ванильный JS
Механизм обработки	Выделенная VM	Python 3.12, httpx, pdfplumber, python-docx
База данных	VM PostgreSQL 15	JSONB, UUID, advisory locks
LLM	api.aillm.ru	gpt-oss-120b (бесплатно, OpenAI API)
Деплой	Managed Python + VM	Dockerfile, Nginx + Let's Encrypt

9. Конечная цель будущее

📋 Заказчик: «Конечная цель: построчное сравнение CRM ↔ фискальная система.
Особый фокус: даты начала услуг.
PAYG (суффикс -m) — особый случай. Сверку с CRM тоже можно делегировать AI.»

Текущий пайплайн завершается на этапе извлечения спецификации из договоров и отслеживания изменений по допникам. Модуль сравнения с CRM — спроектирован как CanonicalRow адаптер, ожидает формата данных от заказчика.

10. Что дальше требует участия Заказчика

📋 Заказчик: «Это всё пока опыты и набивание шишек.
Не надеюсь с первого захода на идеальный результат.»

Золотой набор: 30–50 реальных документов с ручной разметкой — измерить точность LLM
Формат CRM: в каком виде данные из системы учёта клиентов — для модуля сверки
Приоритет: точность vs скорость обработки — влияет на выбор модели LLM (локальная vs облачная)