docs: архитектура contracts-flask — компоненты, пайплайн, вход/выход

2026-06-28 08:38:52 +04:00
parent f10506b262
commit c339da818c
1 changed files with 74 additions and 0 deletions
@@ -0,0 +1,74 @@
+# Архитектура contracts-flask
+
+## Компоненты
+
+```
+Браузер
+    │
+    ▼
+check.kube5s.ru (nginx)
+    │
+    ├── /, /static/*, /templates/*
+    │       → Managed Flask (contractor.pythonk8s.services.ngcloud.ru)
+    │         Отдаёт HTML + JS. JS в браузере делает API-запросы.
+    │
+    └── /api/*, /upload, /llm-ops, /process-v2, /convert-doc, /unzip-upload
+            → ВМ :8777 (convert_server.py)
+              Python http.server → PostgreSQL (contracts_check)
+                                  → LLM (api.aillm.ru, gpt-oss-120b)
+```
+
+## Пайплайн
+
+```
+1. Загрузка
+   JS (FormData) → /upload → parse.py (pdfplumber/python-docx)
+   → elements_json → documents (БД)
+
+2. Классификация
+   JS → /api/classify-batch → classify.py (LLM)
+   → doc_type, own_number, parent_number, counterparty, doc_date
+
+3. Группировка
+   JS → /api/groups → grouping.py (детерминированная)
+   → группы по контрактам (нормализация номеров)
+
+4. Сравнение
+   JS → /process-v2 (SSE) → process.py → llm.py (LLM)
+   → ops (ADD/UPDATE/DELETE/UNRESOLVED)
+   → spec_events + spec_current (event sourcing)
+
+5. Чат
+   JS → /chat → Flask → /api/spec-current (ВМ)
+   → контекст строк → LLM → ответ
+```
+
+## Вход/Выход
+
+| Этап | Вход | Выход |
+|------|------|-------|
+| Загрузка | .docx/.pdf/.doc/.zip (FormData) | elements_json в БД |
+| Классификация | elements_json | doc_type, номер, дата, контрагент |
+| Группировка | classified documents | группы по contract_number |
+| Сравнение | группа документов + spec_current | ops: ADD/UPDATE/DELETE/UNRESOLVED |
+| Чат | вопрос + spec_current | текст ответа |
+
+## БД
+
+- PostgreSQL `contracts_check` (изолирована от прода `baza`)
+- Таблицы: documents, contracts, supplements, spec_current, spec_events, prompts, upload_chunks
+
+## LLM
+
+- gpt-oss-120b через api.aillm.ru (бесплатно)
+- Используется: классификация, извлечение, сравнение, чат
+
+## Изоляция от прода
+
+| | Lucee (прод) | Flask (тест) |
+|---|---|---|
+| Домен | contracts.kube5s.ru | check.kube5s.ru |
+| ВМ порт | 8766 | 8777 |
+| БД | baza | contracts_check |
+| Код ВМ | ~/contracts/ | ~/contracts-check/ |
+| Репо ВМ | contractor/deploy/ | contracts-flask/deploy/ |