From c339da818c3b865d1551a12151c4385bed021120 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9CNaeel=E2=80=9D?= <tazet@narod.ru>
Date: Sun, 28 Jun 2026 08:38:52 +0400
Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B0=D1=80=D1=85=D0=B8=D1=82=D0=B5?=
 =?UTF-8?q?=D0=BA=D1=82=D1=83=D1=80=D0=B0=20contracts-flask=20=E2=80=94=20?=
 =?UTF-8?q?=D0=BA=D0=BE=D0=BC=D0=BF=D0=BE=D0=BD=D0=B5=D0=BD=D1=82=D1=8B,?=
 =?UTF-8?q?=20=D0=BF=D0=B0=D0=B9=D0=BF=D0=BB=D0=B0=D0=B9=D0=BD,=20=D0=B2?=
 =?UTF-8?q?=D1=85=D0=BE=D0=B4/=D0=B2=D1=8B=D1=85=D0=BE=D0=B4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 History/architecture.md | 74 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 History/architecture.md

diff --git a/History/architecture.md b/History/architecture.md
new file mode 100644
index 0000000..7c29c75
--- /dev/null
+++ b/History/architecture.md
@@ -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/ |