# Устройство ВМ contracts.kube5s.ru

> **ВАЖНО**: Это актуальная документация. Старый `architecture.md` описывает мёртвый Flask `contracts-app/site/` — к ВМ отношения не имеет.

---

## Где что лежит

```
РЕПОЗИТОРИЙ (локально)                   ВМ (5.172.178.213)
/home/naeel/nubes/contracts/             /home/naeel/contracts/
│                                        │
├── contractor/                          │
│   └── deploy/          ◀─── sync.sh ───▶  ВСЁ содержимое deploy/
│       ├── app.js                           ├── app.js
│       ├── app_utils.js                     ├── app_utils.js
│       ├── compare.js                       ├── compare.js
│       ├── files.js                         ├── files.js
│       ├── groups.js                        ├── groups.js
│       ├── state.js                         ├── state.js
│       ├── tests.js                         ├── (нет на ВМ)
│       ├── classify_worker.py               ├── classify_worker.py
│       ├── convert_doc.py                   ├── convert_doc.py
│       ├── convert_server.py  ◀── ГЛАВНЫЙ ──▶ convert_server.py (порт 8766)
│       ├── llm_prompt.py                    ├── llm_prompt.py
│       ├── nginx-contracts.conf             ├── nginx-contracts.conf
│       ├── db/                              ├── db/
│       │   ├── __init__.py                  │   ├── __init__.py
│       │   ├── connection.py                │   ├── connection.py
│       │   ├── contracts.py                 │   ├── contracts.py
│       │   ├── documents.py                 │   ├── documents.py
│       │   ├── prompts.py                   │   ├── prompts.py
│       │   ├── spec_current.py              │   ├── spec_current.py
│       │   ├── spec_events.py               │   ├── spec_events.py
│       │   └── supplements.py               │   └── supplements.py
│       ├── services/                        ├── services/
│       │   ├── __init__.py                  │   ├── __init__.py
│       │   ├── classify.py                  │   ├── classify.py
│       │   ├── grouping.py                  │   ├── grouping.py
│       │   ├── llm.py                       │   ├── llm.py
│       │   ├── parse.py                     │   ├── parse.py
│       │   ├── process.py                   │   ├── process.py
│       │   ├── unzip.py                     │   ├── unzip.py
│       │   └── upload.py                    │   └── upload.py
│       └── sync.sh                          │
│                                            ├── site/          ← Flask UI (НЕ из deploy)
│                                            ├── .env           ← VM-специфично
│                                            ├── gunicorn.conf.py
│                                            ├── start.sh
│                                            ├── logs/
│                                            │
│                                            ├── classify.py    ← ⛔ МУСОР (не юзается)
│                                            ├── grouping.py    ← ⛔ МУСОР (не юзается)
│                                            ├── prompts.py     ← ⛔ МУСОР (не юзается)
│                                            └── unzip.py       ← ⛔ МУСОР (не юзается)
│
├── contracts-app/        ← ⛔ МЁРТВЫЙ Flask v1, к ВМ отношения НЕ ИМЕЕТ
│
├── contractor/           ← ColdFusion/Lucee (старый бекенд, не на ВМ)
│
└── contracts-vm/         ← ?
```

---

## ⛔ КОРНЕВЫЕ .py НА ВМ — МУСОР

На ВМ в `~/contracts/` лежат файлы:
- `classify.py`
- `grouping.py`
- `prompts.py`
- `unzip.py`

**Эти файлы НЕ ИМПОРТИРУЮТСЯ и НЕ ИСПОЛЬЗУЮТСЯ.** Они остались от старой плоской структуры.

Реально используемые версии лежат в подпапках:
- `services/classify.py` ✅
- `services/grouping.py` ✅
- `db/prompts.py` ✅
- `services/unzip.py` ✅

`convert_server.py` импортирует ТОЛЬКО из `db/` и `services/`:
```python
from db import prompts as db_prompts
from db.connection import DB_CONFIG, execute
from db import supplements as db_supplements
from db import documents as db_documents
from db import spec_current as db_spec_current
from services.upload import handle_upload
from services.unzip import handle_unzip
from services.process import run_pipeline
from llm_prompt import build_prompt
```

---

## Архитектура на ВМ

```
Браузер
    │
    ▼
Nginx :443 (nginx-contracts.conf)
    │
    ├── / → 127.0.0.1:5001 (Flask, gunicorn)
    │       site/app.py — отдаёт HTML (index.html, upload.html)
    │       Статика: templates/, static/
    │
    └── /upload, /convert-doc, /unzip-upload,
        /llm-ops, /process-v2, /parse-pdf, /static/
            → 127.0.0.1:8766 (convert_server.py)
                  │
                  ├── db/         — PostgreSQL через psycopg2
                  ├── services/   — бизнес-логика
                  └── llm_prompt.py — сборка промптов
```

### Три процесса

| Процесс | Порт | Что | Запуск |
|---|---|---|---|
| gunicorn | 5001 | Flask UI | `start.sh` |
| convert_server.py | 8766 | **Главный API-сервер** | `sync.sh` (после деплоя) |
| nginx | 443 | Прокси + SSL | systemd |

### JS-файлы — клиентские

`app.js`, `files.js`, `groups.js`, `state.js`, `compare.js`, `app_utils.js` — это **клиентский JavaScript**. Они не запускаются на ВМ как процесс. Их отдаёт Flask через HTML-шаблоны, и они выполняются в браузере.

---

## Деплой (sync.sh)

```bash
# Запускать из contractor/
bash deploy/sync.sh
```

**Сейчас деплоит только 2 файла:**
- `convert_server.py`
- `convert_doc.py`

**Должен деплоить ВСЁ из `deploy/`** (кроме `sync.sh` и `__pycache__`).

После деплоя — `pkill -f convert_server.py && nohup python3 convert_server.py &`

### Что НЕ деплоить

- `site/` — Flask UI, живёт своей жизнью
- `.env` — переменные окружения ВМ
- `gunicorn.conf.py`, `start.sh` — конфиги ВМ
- `logs/` — рантайм

---

## Как проверять соответствие

```bash
# md5 всех файлов в db/ и services/ на ВМ
ssh naeel@5.172.178.213 'md5sum ~/contracts/db/*.py ~/contracts/services/*.py'

# Сравнить с локальными
md5sum contractor/deploy/db/*.py contractor/deploy/services/*.py
```

Корневые `classify.py`, `grouping.py`, `prompts.py`, `unzip.py` — **НЕ проверять**, это мусор.

---

## Версия

Актуально на 2026-06-27. При изменениях — обновлять.