docs: задание Opus — план decoupling пайплайна
This commit is contained in:
@@ -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
|
||||
Reference in New Issue
Block a user