# Задание Opus: Архитектурное исследование — Сверка договоров v2

Дата: 27.06.2026 | От: DeepSeek V4 Pro (через Крупского) | Кому: Opus

---

## ⛔ ЧЕГО НЕ ДЕЛАТЬ

- **НЕ пиши код.** Ни строчки Python, SQL, JS, ничего. Только концепции.
- **НЕ рисуй mermaid-диаграммы.** Только текст. Исполнитель (DeepSeek) сам нарисует если надо.
- **НЕ предлагай «переписать с нуля».** Продакшен надо эволюционировать.
- **НЕ лезь в файлы за пределами списка ниже.** Экономия токенов.

## 📋 ЗАЧЕМ ЭТОТ АНАЛИЗ

Ты — исследователь. Твой отчёт пойдёт **DeepSeek V4 Pro** (мне). Я буду по нему ПИСАТЬ КОД.

У нас нет промежуточных результатов — неизвестна точность LLM на реальных 100+ документах,
неизвестны типичные расхождения CRM↔фискальная. Нужна архитектура, которую можно
итеративно улучшать по мере данных.

Главное — **концептуальные решения**. Не реализации.

---

## ⛔ КАКИЕ ФАЙЛЫ СМОТРЕТЬ

### Код (18 + 18 + 7 = 43 файла):
```
contractor/index.cfm          — HTML/CSS скелет (v1.0.178)
contractor/upload.cfm         — приём файлов (form/JSON/multipart/iframe)
contractor/chunk.cfm          — чанковая загрузка
contractor/process.cfm        — SSE-пайплайн v1 (прямой LLM)
contractor/process_v2.cfm     — SSE-пайплайн v2 (→ ВМ, event sourcing)
contractor/apply_events.cfm   — ADD/UPDATE/DELETE → spec_current
contractor/extractor.cfm      — старый вариант извлечения spec_rows
contractor/parser.cfm         — парсинг docx/pdf (PDFBox + POI)
contractor/differ.cfm         — сравнение допников с базовым договором
contractor/chat.cfm           — Q&A (⚠ сломан: spec_rows вместо spec_current)
contractor/api.cfm            — создание схемы БД
contractor/Application.cfc    — конфигурация Lucee + datasource
contractor/db.cfc             — REST-обёртка БД
contractor/view.cfm           — просмотр текста документа
contractor/prompt.cfm         — версионирование промптов
contractor/reset_contract.cfm — сброс контракта
contractor/test.cfm           — тест
contractor/jars.cfm           — проверка Java-библиотек

contractor/deploy/convert_server.py     — HTTP-роутер (:8766)
contractor/deploy/llm_prompt.py         — промпты + fallback (⚠ зависит от Lucee)
contractor/deploy/classify_worker.py    — фоновый процесс (subprocess)
contractor/deploy/convert_doc.py        — парсинг docx/pdf
contractor/deploy/services/upload.py    — загрузка
contractor/deploy/services/unzip.py     — ZIP
contractor/deploy/services/classify.py  — классификация (LLM: тип/номер/контрагент)
contractor/deploy/services/process.py   — пайплайн сравнения
contractor/deploy/services/llm.py       — вызов LLM API (⚠ ВМ↔репо расходятся)
contractor/deploy/services/parse.py     — PDF (PyPDF2) / DOCX (python-docx)
contractor/deploy/services/grouping.py  — группировка (гибрид LLM→Python)
contractor/deploy/db/connection.py      — psycopg2
contractor/deploy/db/documents.py       — CRUD документов
contractor/deploy/db/supplements.py     — CRUD дополнений
contractor/deploy/db/spec_current.py    — CRUD текущей спецификации
contractor/deploy/db/spec_events.py     — event sourcing (seq, reset)
contractor/deploy/db/contracts.py       — CRUD контрактов
contractor/deploy/db/prompts.py         — CRUD промптов (seed defaults)

contractor/deploy/app.js        — фронтенд (VM_API, render, stepper)
contractor/deploy/app_utils.js  — утилиты
contractor/deploy/state.js      — центральный state
contractor/deploy/files.js      — загрузка/рендер файлов
contractor/deploy/groups.js     — карточки групп
contractor/deploy/compare.js    — SSE-сравнение
contractor/deploy/tests.js      — 131 юнит-тест
```

### Документы (6 штук):
```
History/topics/customer-qa-2026-06-26.md       — ответы заказчика (ОБЯЗАТЕЛЬНО)
History/architecture/vm-layout.md               — ⭐ раскладка ВМ (самый актуальный)
History/architecture/service-description.md     — описание сервиса
History/architecture/two-panel-architecture.md  — две панели просмотра
History/opus-plan-review-2026-06-27.md          — разбор предыдущего плана Opus
History/llm-analysis/decoupling-final-plan.md   — план размоноличивания JS
```

### ⛔ НЕ ЧИТАТЬ:
```
History/architecture/architecture.md    — ⛔ МЁРТВЫЙ Flask contracts-app/site/
History/architecture/block-diagram.md   — ⛔ МЁРТВЫЙ Flask
History/architecture/pipeline.md        — ⛔ МЁРТВЫЙ Flask
sim/ testgen/ dogovora/ FILES/ Files/ DOC/ contracts-flask/ contracts-vm/
README.md sonnet-v2-request.md
History/sessions/ History/features/ History/llm-analysis/*
  (КРОМЕ decoupling-final-plan.md)
```

---

## 📋 КОНТЕКСТ: что уже надумал DeepSeek

Я (DeepSeek) уже провёл предварительный анализ. Ниже — мои гипотезы.
**Твоя задача: подтвердить, опровергнуть или дополнить.** Не просто соглашаться.

### Гипотеза 1: Гибрид pipeline + агент
Pipeline для 95% стандартных случаев (дёшево, предсказуемо).
Лёгкий оркестратор-агент — только для краевых случаев (нестандартный формат, ошибка парсинга).
Pure agents — дорого: 100 файлов × 500 токенов оркестратора = 50K токенов только на планирование.

### Гипотеза 2: Трёхэтапный фильтр мусора
Этап 1 (0 токенов): regex по имени файла — «счёт», «акт», «платёж» → сразу garbage.
Этап 2 (0 токенов): ключевые слова в первых 2KB текста — «СЧЕТ-ФАКТУРА», «АКТ СВЕРКИ» → garbage.
Этап 3 (LLM): только оставшиеся → точный тип (contract/supplement/specification).
Экономия: ~50% LLM-вызовов при 50% мусора в пачке.

### Гипотеза 3: Перенос парсинга на ВМ
Сейчас: JS → ВМ → Lucee (Java PDFBox/POI) → обратно на ВМ.
Предложение: JS → ВМ → pdfplumber + python-docx (без Java, без Lucee).
Убирает latency сетевого вызова, упрощает деплой.

### Гипотеза 4: Трёхуровневый matching CRM↔фискальная
Уровень 1 (0 токенов): хеш нормализованного названия.
Уровень 2 (0 токенов): fuzzy string matching (difflib).
Уровень 3 (LLM): только для 10-20% несопоставленных.
80% строк матчатся без LLM.

### Гипотеза 5: MVP-границы
v1: извлечение спецификаций из договоров (без CRM-сверки). Доказать что LLM вообще справляется.
v2: сверка CRM↔фискальная (когда качество извлечения подтверждено).
v3: красивый UI, чат, автообучение на коррекциях.

### Гипотеза 6: PostgreSQL-очередь вместо RabbitMQ
Для 100+ файлов пару раз в неделю — хватит `documents.classify_status='pending'` + `FOR UPDATE SKIP LOCKED`. RabbitMQ — оверкилл.

---

## ❓ ВОПРОСЫ К OPUS (5 блоков)

### Блок 1: Насколько агрессивно использовать LLM?

**Контекст:** LLM заказчика — gpt-oss-120b через api.aillm.ru — **БЕСПЛАТНЫЙ**. Никаких затрат на токены.

Сейчас LLM используется 3 раза за прогон:
- Классификация (тип/номер/контрагент)
- Извлечение спецификации
- Сравнение ДС

**Вопросы:**
1.1. Имеет ли смысл использовать LLM **больше** раз на одном документе? Например:
- Два прохода извлечения (второй — верификация первого)?
- LLM-as-judge: проверять свой же результат и исправлять ошибки?
- LLM для принятия решений по ходу пайплайна (оркестратор)?

1.2. Где LLM **реально** добавляет ценность, а где детерминированный код справится лучше?
(С учётом что LLM медленный: 2-30 секунд на вызов.)

1.3. Если LLM бесплатный — может **вообще отказаться от детерминированного matching** (Гипотеза 4) и всё гонять через LLM? Плюсы/минусы.

### Блок 2: Архитектура — pipeline или агент?

2.1. Критика гибридного подхода (Гипотеза 1). Что я упустил? В каких сценариях чистый pipeline или чистые агенты были бы лучше?

2.2. Если гибрид — где конкретно проходят границы? Какие решения принимает оркестратор, какие — pipeline?

2.3. Есть ли смысл в нескольких специализированных агентах (parse-agent, classify-agent, compare-agent) вместо одного оркестратора? Плюсы/минусы.

### Блок 3: Обработка 100+ файлов и фильтрация

3.1. Критика трёхэтапного фильтра (Гипотеза 2). Какие документы он пропустит? Ложные срабатывания?

3.2. Парсинг на ВМ (Гипотеза 3) — правильно ли отказываться от Java PDFBox/POI в пользу pdfplumber/python-docx? Качество парсинга таблиц упадёт или вырастет?

3.3. Какие ещё узкие места будут при 100+ файлах, кроме классификации? Память? Сеть? Диск?

### Блок 4: Сверка CRM ↔ фискальная

4.1. Критика трёхуровневого matching (Гипотеза 4). В каких случаях fuzzy matching (difflib) даст ложные срабатывания? Примеры.

4.2. PAYG (суффикс `-m`, нет артикулов): как сопоставлять? Достаточно убирать `-m` и сравнивать названия, или нужна более сложная логика?

4.3. Если заказчик НЕ даст формат CRM в ближайшее время — как спроектировать модуль чтобы не простаивать? Что можно сделать уже сейчас (без CRM-данных)?

### Блок 5: Итеративность и метрики

5.1. Критика MVP-границ (Гипотеза 5). Может что-то из v2 нужно уже в v1? Или наоборот — что-то из v1 отложить?

5.2. Какие **конкретные метрики** внедрить с первого дня? Не «точность» вообще, а что именно измерять? Как измерять без эталонных данных?

5.3. Цикл обратной связи: заказчик проверяет → исправляет → система учитывает. Как это делать без дообучения модели (gpt-oss-120b — API, не наша)? Только few-shot в промпте? Или есть другие подходы?

5.4. **Главный вопрос:** мы не знаем точность LLM. С чего начать? Просто прогнать 100 реальных документов через текущий код и посмотреть? Или сначала улучшить фильтрацию/промпты, а потом прогонять?

---

## 📐 ФОРМАТ ОТВЕТА

1. **Executive Summary** — 3-5 абзацев, главные выводы
2. **По каждой гипотезе** — вердикт (✅ подтверждаю / ⚠ частично / ❌ отвергаю) + аргументация
3. **Ответы на вопросы** — по блокам, кратко
4. **Что я упустил** — твои собственные идеи, которых нет в моих гипотезах
5. **MVP-план** — что делать в ближайшие 2 недели (пункты, не код)
6. **Риски** — что может пойти не так

## ⚠️ ОГРАНИЧЕНИЯ

- Конфиденциальность: никаких S3, только локал / файловая шара
- Managed Lucee: не можем ставить pip-пакеты на нём
- ВМ: 5.172.178.213, Ubuntu, Python 3.12, PostgreSQL 15
- LLM: gpt-oss-120b, 8000 токенов, ~5-30s на вызов, БЕСПЛАТНО