docs: задание Opus — план decoupling пайплайна

History/opus-decoupling-plan-2026-06-28.md

@@ -0,0 +1,169 @@
+# Задание Opus 4.8: План decoupling пайплайна contracts-flask
+
+Дата: 28.06.2026 | Режим: **plan (интерактивный)**
+
+---
+
+## ⛔ ЧЕГО НЕ ДЕЛАТЬ
+
+- **НЕ пиши код.** Анализ и план. Исполнитель — DeepSeek V4 Pro.
+- **НЕ рисуй mermaid.** Только текст.
+- **НЕ предлагай «переписать всё с нуля».**
+
+## 📋 КОНТЕКСТ
+
+Проект **contracts-flask** — сверка договоров облачного провайдера (colocation, ЦОД) через LLM.
+
+### Текущая архитектура:
+
+```
+Браузер
+    │
+    ▼
+check.kube5s.ru (nginx)
+    │
+    ├── Страницы/статика → Managed Flask (contractor.pythonk8s...)
+    └── API → ВМ :8777 (convert_server.py)
+                 │
+                 ├── services/parse.py    — PDF (pdfplumber) / DOCX (python-docx)
+                 ├── services/upload.py   — multipart-загрузка → БД
+                 ├── services/classify.py — LLM-классификация (тип/номер/дата/контрагент)
+                 ├── services/grouping.py — группировка по контрактам
+                 ├── services/process.py  — сравнение (LLM + event sourcing)
+                 ├── services/llm.py      — вызов LLM API
+                 ├── services/metrics.py  — арифметика + JSON-фиксы
+                 ├── db/                  — PostgreSQL CRUD
+                 └── llm_prompt.py        — промпты (из БД, не Lucee)
+```
+
+### Пайплайн (последовательно):
+
+```
+1. Upload    → parse.py   → elements_json
+2. Classify  → classify.py → doc_type, own_number, parent_number, counterparty, doc_date
+3. Grouping  → grouping.py → группы по contract_number
+4. Compare   → process.py  → SSE: ops (ADD/UPDATE/DELETE/UNRESOLVED)
+5. Chat      → Flask /chat → контекст из spec_current → LLM → ответ
+```
+
+### Фронтенд:
+
+Managed Flask (Python 3.12, Dockerfile):
+- `site/app.py` — роуты: `/`, `/chat`, `/api/prompts/*`, `/health`
+- `site/templates/index.html` — Jinja2 UI
+- `site/static/*.js` — 6 JS-файлов, оркестрируют пайплайн
+- JS вызывает ВМ напрямую: `VM_API = 'https://check.kube5s.ru'`
+
+### БД: PostgreSQL `contracts_check`
+
+Таблицы: documents, contracts, supplements, spec_current, spec_events, prompts, upload_chunks.
+
+### LLM: gpt-oss-120b (api.aillm.ru, БЕСПЛАТНО)
+
+---
+
+## 📂 ЧТО ИЗУЧИТЬ
+
+### Основное (contracts-flask/):
+```
+deploy/convert_server.py       — HTTP-роутер, точка входа
+deploy/services/parse.py       — PDF/DOCX парсинг
+deploy/services/upload.py      — multipart-загрузка
+deploy/services/classify.py    — LLM-классификация + фильтр мусора
+deploy/services/grouping.py    — группировка
+deploy/services/process.py     — сравнение (SSE)
+deploy/services/llm.py         — LLM API
+deploy/services/metrics.py     — арифметика + JSON-фиксы
+deploy/db/*.py                 — PostgreSQL CRUD (7 файлов)
+deploy/llm_prompt.py           — промпты
+deploy/classify_worker.py      — фоновый процесс
+site/app.py                    — Flask-фронтенд
+site/static/app.js             — JS-оркестратор
+site/static/files.js           — загрузка/рендер файлов
+site/static/groups.js          — карточки групп
+site/static/compare.js         — SSE-сравнение
+site/static/state.js           — центральное состояние
+site/templates/index.html      — UI
+History/architecture.md        — архитектура Flask-стека
+History/session-01-init-2026-06-27.md — история создания
+```
+
+### Контекст из родительского проекта (contracts/History/):
+```
+History/topics/customer-qa-2026-06-26.md           — требования заказчика
+History/llm-analysis/decoupling-final-plan.md       — план размоноличивания JS
+History/architecture-research-v2-2026-06-27.md      — анализ DeepSeek
+History/opus-architecture-research-2026-06-27.md    — опросник Opus
+History/opus-architecture-research-2026-06-27-review.md — рецензия
+```
+ВНИМАНИЕ: эти файлы в основном описывают Lucee-морду (contractor/), которая сейчас заморожена.
+
+---
+
+## 🎯 ЗАДАЧА
+
+Разработать **подробный план decoupling пайплайна**:
+
+### 1. Модульность пайплайна
+
+Каждый шаг — независимый модуль с чёткими входом/выходом. Сейчас `services/` уже так устроены, но:
+- Модули вызываются напрямую из `convert_server.py`
+- Нет формального контракта (интерфейса)
+- Нельзя протестировать изолированно
+
+**Вопрос:** как оформить контракты? Dataclass? TypedDict? Proto-буферы? Просто документированные словари?
+
+### 2. Интеграционное тестирование (fixture-based)
+
+```
+Тест upload:   .docx → upload.py    → elements_json (fixture)
+Тест classify: fixture_elements     → classify.py  → doc_type/number (fixture)
+Тест grouping: fixture_classify     → grouping.py  → группы (fixture)
+Тест compare:  fixture_groups       → process.py   → ops
+```
+
+**Вопросы:**
+- Где хранить fixtures? `deploy/tests/fixtures/`?
+- Как мокать LLM? Monkey-patch `_call_llm_classify` / `call_llm`?
+- БД: отдельная `contracts_test` или in-memory SQLite?
+- Как очищать БД между тестами?
+
+### 3. Деплой и синхронизация
+
+Сейчас: локально правим → git push → вручную копируем на ВМ → рестарт.
+
+**Вопрос:** как улучшить? `rsync` из CI? `git pull` на ВМ? systemd + watchdog?
+
+### 4. Перспектива переезда на managed Flask
+
+Сейчас managed Flask не может принимать файлы (ограничение платформы). Когда починят — вся загрузка переедет с ВМ на managed.
+
+**Вопрос:** что уже сейчас сделать в коде, чтобы переезд был безболезненным? Абстракция над upload? Флаги `UPLOAD_BACKEND=vm|managed`?
+
+### 5. Вопросы к заказчику (блокируют развитие)
+
+Без ответов нельзя двигаться дальше:
+- Формат CRM-данных для сверки?
+- Есть ли примеры реальных расхождений?
+- Приоритет: точность vs скорость?
+- Готов ли дать 30-50 реальных документов для золотого набора?
+
+**Вопрос к Opus:** какие ещё вопросы НЕОБХОДИМО задать заказчику прямо сейчас?
+
+---
+
+## 🔄 ИНТЕРАКТИВНЫЙ РЕЖИМ
+
+Ты в режиме **plan**. Если тебе нужны уточнения по коду, архитектуре, или ты хочешь предложить альтернативный подход который требует моего мнения — **задай вопрос**. Я (DeepSeek) отвечу.
+
+Не пиши финальный план пока не закроем все неясности.
+
+---
+
+## ⚠️ ОГРАНИЧЕНИЯ
+
+- Managed Flask: Python 3.12, Dockerfile, `site/` — обязательная структура
+- ВМ: 5.172.178.213, Ubuntu, порт 8777
+- БД: PostgreSQL 15, `contracts_check`
+- LLM: gpt-oss-120b, 8000 токенов, бесплатно, ~5-30s/вызов
+- JS-фронтенд: 131 тест (puppeteer-моки), все PASS