Nail/contracts-flask

Fork 0

Files

T

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

2026-06-28 09:03:40 +04:00

8.2 KiB

Raw Permalink Blame History

Задание 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

8.2 KiB Raw Permalink Blame History