md

2026-06-23 09:07:26 +04:00
parent c4861e17c1
commit e49a094121
7 changed files with 569 additions and 0 deletions
@@ -0,0 +1,71 @@
+# Сверка договоров — описание сервиса
+
+## Что делает
+
+Сервис автоматически сравнивает договоры и дополнительные документы облачного провайдера (colocation, ЦОД). Юрист загружает файлы (.docx/.doc/.pdf), система извлекает спецификации услуг и при помощи LLM находит изменения: что добавилось, изменилось, удалилось.
+
+## Как устроен пайплайн
+
+```
+Загрузка → Парсинг → Порядок → LLM-сравнение → Результаты
+```
+
+1. **Загрузка** — файлы принимаются через веб-интерфейс. Поддерживаются .docx, .doc (старый Word), .pdf, а также .zip с несколькими файлами.
+
+2. **Парсинг** — каждый файл автоматически разбирается: извлекаются таблицы и текст. Используется Apache POI (Java) для Word-документов и PDFBox для PDF. Результат — структурированный JSON (elements_json) и текстовое представление.
+
+3. **Порядок** — файлы можно переставить стрелками ↕. Первый в списке считается базовым договором, остальные — дополнительные документы к нему.
+
+4. **LLM-сравнение** — каждый дополнительный документ последовательно сравнивается с текущей спецификацией. Модель (gpt-oss-120b) получает промпт с текущим списком услуг, текстом дополнительного документа и возвращает операции:
+   - **ADD** — новая услуга
+   - **UPDATE** — изменение цены, количества, названия
+   - **DELETE** — услуга исключена
+   - **UNRESOLVED** — не удалось однозначно сопоставить
+
+5. **Результаты** — накапливаются по цепочке дополнительных документов (Event Sourcing). Каждый следующий дополнительный документ учитывает изменения из предыдущих. Итоговая спецификация — сумма всех применённых операций.
+
+## Архитектура
+
+```
+Браузер (index.cfm + JS)
+    │
+    ├── загрузка файлов ──→ VM (Python, convert_server.py)
+    │                           │
+    │                           ├── /convert-doc ──→ Lucee (parser.cfm)
+    │                           ├── /process-v2 ───→ Lucee (apply_events.cfm)
+    │                           └── LLM (api.aillm.ru, gpt-oss-120b)
+    │
+    └── API ──→ Lucee (CFML на k8s)
+                    │
+                    └── PostgreSQL 15 (документы, спецификации, события, промпты)
+```
+
+| Компонент | Где | Технология |
+|-----------|-----|------------|
+| Веб-интерфейс | Lucee 6.0 (k8s) | CFML + JavaScript |
+| База данных | Внутренний PostgreSQL 15 | JSONB, UUID, advisory locks |
+| Парсинг документов | Lucee | Apache POI (HWPF/XWPF), PDFBox |
+| LLM-анализ | Внешняя VM (5.172.178.213) | Python 3, httpx, SSE-стриминг |
+| Модель | api.aillm.ru | gpt-oss-120b (бесплатно, 8000 токенов) |
+
+## Event Sourcing
+
+Изменения не перезаписывают спецификацию — каждая операция сохраняется как событие в `spec_events`. Текущее состояние (`spec_current`) — материализованное представление всех событий.
+
+Это даёт:
+- **Аудит** — кто/when/откуда каждая строка
+- **Откат** — можно пересобрать состояние на любой момент
+- **Provenance** — ссылка на документ-источник, версию промпта, полный ответ LLM
+
+## Промпты
+
+Промпты для LLM хранятся в БД и версионируются. Есть два: для первого документа (извлечение) и для сравнения дополнительных документов. Встроенный редактор с историей версий позволяет улучшать промпты без правки кода: сохранил новую версию → она сразу используется LLM. Старые версии остаются в истории, можно откатиться.
+
+## Стек
+
+- **Backend**: Lucee 6.0 (CFML) на Kubernetes
+- **База**: PostgreSQL 15 (JSONB, UUID, window functions)
+- **Парсинг**: Apache POI (Java, встроен в Lucee)
+- **LLM-прокси**: Python 3 + httpx + threading (SSE)
+- **Модель**: gpt-oss-120b (OpenAI-совместимый API)
+- **Фронтенд**: ванильный JS + Lucide иконки