237 lines
12 KiB
Markdown
237 lines
12 KiB
Markdown
# Архитектура contracts-flask — срез 2026-07-14
|
||
|
||
## Общая схема
|
||
|
||
```
|
||
Браузер (index.html)
|
||
│
|
||
│ JS-модули (6 файлов, грузятся как статика Flask)
|
||
│ XHR POST /upload, /convert-doc, /unzip-upload
|
||
│ EventSource GET /process-v2 (SSE)
|
||
│ fetch /api/* (классификация, группы, документы, промпты)
|
||
▼
|
||
Flask (site/app.py) — ~90 строк, ТОЛЬКО ПРОКСИ
|
||
│ GET / → render_template("index.html")
|
||
│ POST /chat → прокси на ВМ
|
||
│ GET /api/prompts → прокси на ВМ
|
||
│ Весь HTML/JS/CSS → статика /static/*
|
||
▼
|
||
ВМ (deploy/convert_server.py) — ВСЯ бизнес-логика
|
||
│ POST /upload → compare/upload.py
|
||
│ POST /convert-doc → convert_doc.py (libreoffice)
|
||
│ POST /unzip-upload → compare/unzip.py
|
||
│ GET /process-v2 → compare/process.py (SSE)
|
||
│ POST /api/classify-batch → classify_worker.py
|
||
│ GET /api/groups → db/groups
|
||
│ GET /api/documents/:id → db/documents
|
||
│ GET /api/supplements → db/supplements
|
||
│ POST /api/sync → db/sync
|
||
│ POST /api/apply-groups → db/supplements
|
||
│ GET /api/spec-current → db/spec_current
|
||
│ GET /api/batch-progress → db/classify-progress
|
||
│ GET /api/prompts → db/prompts
|
||
│ GET /api/prompts/list → db/prompts
|
||
│ POST /api/prompts/save → db/prompts
|
||
│ POST /api/prompts/activate → db/prompts
|
||
│ POST /api/cleanup → db/cleanup
|
||
▼
|
||
PostgreSQL (таблицы: documents, supplements, spec_current, prompts, contracts)
|
||
```
|
||
|
||
## JS-фронтенд — 6 модулей
|
||
|
||
Все лежат в `contracts-flask/deploy/`, грузятся в HTML в этом порядке:
|
||
|
||
```html
|
||
<script src="/static/state.js"></script>
|
||
<script src="/static/app_utils.js"></script>
|
||
<script src="/static/files.js"></script>
|
||
<script src="/static/groups.js"></script>
|
||
<script src="/static/compare.js"></script>
|
||
<script src="/static/app.js"></script>
|
||
```
|
||
|
||
### 1. `state.js` — Центральное состояние
|
||
|
||
```javascript
|
||
var state = {
|
||
files: [], // [{ name, size, lastModified, doc_id, uploaded, parsed, parseInfo, supp_id, supp_type, status, zip_source }]
|
||
contractId: null, // ID контракта (приходит с бэкенда после первого upload)
|
||
batchId: crypto.randomUUID(), // Уникальный ID сессии
|
||
groups: null, // [{ contract_number, counterparty, documents[], compare }]
|
||
_activeCompare: { es: null, timer: null }, // Одно активное SSE-сравнение
|
||
ui: {
|
||
steps: { upload: '○', classify: '○', groups: '○', compare: '○' }
|
||
}
|
||
};
|
||
```
|
||
|
||
**ПАТТЕРН**: `action → mutate state → render(state)`. DOM — проекция state, никогда не читаем из DOM.
|
||
|
||
### 2. `app_utils.js` — Утилиты
|
||
|
||
| Функция | Назначение |
|
||
|---------|-----------|
|
||
| `formatSize(bytes)` | Байты → "1.5 MB" |
|
||
| `formatDate(ts)` | Timestamp → российская дата+время |
|
||
| `escHtml(s)` | Экранирование HTML |
|
||
| `removeFile(i)` | Удалить файл из state.files → render → syncDB |
|
||
| `moveUp(i)` / `moveDown(i)` | Переместить файл (не используется) |
|
||
| `openAbout()` / `closeAbout()` | Модальное окно "О сервисе" |
|
||
|
||
### 3. `files.js` — Загрузка и таблица файлов
|
||
|
||
| Функция | Назначение |
|
||
|---------|-----------|
|
||
| `statusToHTML(st)` | Чистая: структура → HTML-статус |
|
||
| `renderFiles(state)` | Рендер таблицы файлов (группировка по zip_source) |
|
||
| `syncDB()` | Синхронизация БД с текущим составом |
|
||
| `toggleClassifyDetail(i)` | Раскрыть результат классификации |
|
||
| `uploadFile(file, onProgress, zipSource)` | **XHR-загрузка** одного файла |
|
||
| `refreshSupps()` | Обновить supp_id/supp_type |
|
||
| `reconcileSelection(files, newFiles)` | Чистая: согласование состава |
|
||
| `applyParseResult(entry, parsed, elapsed)` | Чистая: применить результат парсинга |
|
||
| `addZipFile(file)` | Обработка ZIP (unzip → for each → addRegularFile) |
|
||
| `addRegularFile(file, zipSource)` | Обработка обычного файла (upload → parse → status) |
|
||
| `finalizeUpload()` | Завершение цикла загрузки |
|
||
| `onFilesSelected(newFiles)` | **Оркестратор** загрузки |
|
||
|
||
**Критичные детали `uploadFile`**:
|
||
- `.doc` → конвертация в `.docx` через `CONVERT_URL` перед загрузкой
|
||
- XHR с `timeout = 180000` (3 минуты для больших PDF)
|
||
- `onProgress(pct)` — callback с процентом
|
||
- Дедупликация по ключу `(zip_source, name)`
|
||
- При совпадении имён: `confirm()` — перезаписать/пропустить
|
||
|
||
### 4. `groups.js` — Карточки групп
|
||
|
||
| Функция | Назначение |
|
||
|---------|-----------|
|
||
| `loadGroupsAction()` | fetch `/api/groups` → state.groups → renderGroups |
|
||
| `renderGroups(state)` | Пересобрать ВСЕ карточки в #diffBody |
|
||
| `renderGroupCard(g, gi)` | HTML карточки необработанной группы |
|
||
| `renderGroupCardDone(g, gi)` | HTML карточки обработанной группы |
|
||
| `renderUnresolvedCard(g)` | HTML карточки нераспознанных |
|
||
|
||
### 5. `compare.js` — SSE-сравнение
|
||
|
||
| Функция | Назначение |
|
||
|---------|-----------|
|
||
| `applyCompareEvent(sections, event)` | Чистая: SSE-событие → мутация sections |
|
||
| `renderCompareSectionHeader(sec)` | Чистая: заголовок секции |
|
||
| `renderCompareOpsTable(ops)` | Чистая: таблица ADD/UPDATE/DELETE |
|
||
| `renderCompareSectionBody(sec)` | Чистая: тело секции |
|
||
| `startCompareSSE(url, container, statusEl, callbacks)` | **Унифицированный** жизненный цикл SSE |
|
||
|
||
**Критичные детали SSE**:
|
||
- `EventSource` → события: `extract_start`, `llm_done`, `applied`, `extract_error`, `apply_error`
|
||
- Только ОДНО сравнение одновременно (`state._activeCompare`)
|
||
- Все кнопки блокируются на время сравнения
|
||
- Таймер обновляет statusEl каждые 200мс
|
||
|
||
### 6. `app.js` — Оркестратор
|
||
|
||
| Функция | Назначение |
|
||
|---------|-----------|
|
||
| `render(state)` | Главная функция рендеринга → `renderFiles` + `renderStepper` |
|
||
| `renderStepper(state)` | Рендер степпера из `state.ui.steps` |
|
||
| `stepDone(id)` / `stepActive(id)` | Мутация шагов |
|
||
| `resetStepper(fromId)` | Сброс шагов |
|
||
| `showClassifyBtn()` | Создать/показать кнопку классификации |
|
||
| `runClassify()` | Классификация (sync/async + poll каждые 2с) |
|
||
| `runCompareForGroup(gi, btn)` | Сравнение группы (apply-groups → SSE) |
|
||
| `llmBtn` handler | Общее сравнение через SSE |
|
||
|
||
## HTML-структура (site/templates/index.html)
|
||
|
||
```html
|
||
<!-- Верхняя панель: логотип + заголовок + степпер + кнопка "О сервисе" -->
|
||
<div class="topbar">...</div>
|
||
|
||
<!-- Контент -->
|
||
<div class="content">
|
||
<!-- Карточка 1: Загрузка -->
|
||
<div class="card">
|
||
<input type="file" id="fileInput" accept=".docx,.doc,.pdf,.zip" multiple>
|
||
<table><tbody id="fileTable"></tbody></table>
|
||
<button id="llmBtn">Общее сравнение</button>
|
||
<!-- Промпты LLM -->
|
||
</div>
|
||
|
||
<!-- Карточка 2: Классификация и группы (скрыта до classify) -->
|
||
<div class="card" id="diffCard" style="display:none;">
|
||
<div id="diffBody"></div>
|
||
</div>
|
||
|
||
<!-- Карточка 3: Результаты сравнения (скрыта до compare) -->
|
||
<div class="card" id="compareCard" style="display:none;">
|
||
<div id="compareBody"></div>
|
||
</div>
|
||
|
||
<!-- Карточка 4: Чат с LLM (скрыта) -->
|
||
<div class="card" id="chatCard" style="display:none;">...</div>
|
||
</div>
|
||
|
||
<!-- Модалки: инфо о файле, промпты, о сервисе -->
|
||
```
|
||
|
||
## Flask (site/app.py)
|
||
|
||
```python
|
||
# Тонкий прокси, ~90 строк
|
||
@app.route("/") → render_template("index.html")
|
||
@app.route("/chat") → прокси на ВМ (LLM API)
|
||
@app.route("/api/prompts") → прокси на ВМ
|
||
@app.route("/api/prompts/list") → прокси на ВМ
|
||
@app.route("/api/prompts/save") → прокси на ВМ
|
||
@app.route("/api/prompts/activate") → прокси на ВМ
|
||
@app.route("/architect") → render_template("architect.html")
|
||
|
||
VM_API = "https://contracts.kube5s.ru"
|
||
LLM_URL = "https://api.aillm.ru/v1/chat/completions"
|
||
```
|
||
|
||
## ВМ (deploy/convert_server.py)
|
||
|
||
Python HTTP-сервер (не Flask!) на `http.server` + `ThreadingMixIn`. Все эндпоинты перечислены в общей схеме выше.
|
||
|
||
**Критичные модули ВМ**:
|
||
- `deploy/db/` — PostgreSQL (connection.py, documents.py, supplements.py, spec_current.py, prompts.py)
|
||
- `deploy/compare/` — upload.py, unzip.py, process.py (SSE)
|
||
- `deploy/convert_doc.py` — libreoffice .doc → .docx (stdin → stdout)
|
||
- `deploy/classify_worker.py` — асинхронная классификация
|
||
- `deploy/llm_prompt.py` — построение промптов
|
||
|
||
## Pipeline (степпер)
|
||
|
||
```
|
||
○ Загрузка ──→ ⏳ Загрузка ──→ ✓ Загрузка
|
||
└─→ ⏳ Классификация ──→ ✓ Классификация
|
||
└─→ ⏳ Группировка ──→ ✓ Группировка
|
||
└─→ ⏳ Сравнение ──→ ✓ Сравнение
|
||
```
|
||
|
||
Сброс: при добавлении новых файлов → `resetStepper('stepUpload')` сбрасывает всё начиная с загрузки.
|
||
|
||
## Что нужно перенести с ВМ на Flask
|
||
|
||
Все API-эндпоинты, которые сейчас на `deploy/convert_server.py`, должны стать Flask-роутами в `site/app.py`:
|
||
|
||
| Эндпоинт | Метод | Назначение |
|
||
|----------|-------|-----------|
|
||
| `/upload` | POST | Загрузка файла → парсинг → БД |
|
||
| `/convert-doc` | POST | .doc → .docx (libreoffice) |
|
||
| `/unzip-upload` | POST | Распаковка ZIP |
|
||
| `/process-v2` | GET | SSE сравнения |
|
||
| `/api/classify-batch` | POST | Классификация батча |
|
||
| `/api/batch-progress` | GET | Прогресс классификации |
|
||
| `/api/groups` | GET | Группы по batch_id |
|
||
| `/api/documents/:id` | GET | Инфо о документе |
|
||
| `/api/supplements` | GET | Список supplement'ов |
|
||
| `/api/sync` | POST | Синхронизация БД |
|
||
| `/api/apply-groups` | POST | Применить группы |
|
||
| `/api/spec-current` | GET | Текущая спецификация |
|
||
| `/api/cleanup` | POST | Очистка старых записей |
|
||
|
||
Плюс перенос БД-логики из `deploy/db/` во Flask-приложение и конвертера `convert_doc.py`.
|