415 lines
17 KiB
Markdown
415 lines
17 KiB
Markdown
# История проекта Contracts (Сверка договоров)
|
||
|
||
## 2026-06-13 — Сессия #1: Инициация и развёртывание
|
||
|
||
### Участники
|
||
- Сергей Мищук — постановщик задачи
|
||
- Владимир Крупский — тех. консультация
|
||
- Наиль Тазетдинов — разработка
|
||
- GitHub Copilot (DeepSeek V4 Pro) — AI-ассистент
|
||
|
||
---
|
||
|
||
## Задача (из fromTelega.md)
|
||
|
||
**Сверка договоров** — автоматизированная обработка договоров и допников:
|
||
|
||
1. Разобрать спецификации (docx/pdf) до структурированного вида
|
||
2. Собрать кумулятивный статус договора по цепочке допников (во времени)
|
||
3. (опционально) Сопоставить артикулы с каталогом услуг через LLM
|
||
|
||
**Ограничения:**
|
||
- Данные строго конфиденциальны
|
||
- LLM — только своя модель
|
||
- Исключения не фантазировать, отмечать как нерешаемые
|
||
|
||
---
|
||
|
||
## Решения по технологиям
|
||
|
||
| Компонент | Выбор | Причина |
|
||
|---|---|---|
|
||
| Язык | Python 3.12 | python-docx, psycopg2, requests — лучшая экосистема для docx + БД + LLM |
|
||
| Фреймворк | Flask | Платформа поддерживает, шаблон Baldurs-Gate-test |
|
||
| БД | PostgreSQL | Существующий кластер postgresqlk8s |
|
||
| LLM | aillm.ru (120B) | Ключ sk-ucI5YvOticoOQK9ujK5m9Q, резервный DeepSeek Flash |
|
||
| Деплой | pythonk8s.services.ngcloud.ru | Платформа Flask-сервисов |
|
||
| Репозиторий | gitea.services.ngcloud.ru/Nail/contracts-app.git | Публичный, мастер-ветка |
|
||
|
||
**Отклонённые варианты:**
|
||
- Node.js — слабый парсинг docx (mammoth → HTML)
|
||
- Lucee/CFML — нет инструментов для docx/LLM
|
||
- SQLite — не подходит для облачного сервиса
|
||
- 3060 (личный сервер) — это личное, не для сервиса
|
||
|
||
---
|
||
|
||
## Архитектура
|
||
|
||
**Принцип: НЕ МОНОЛИТИТЬ. Независимые слои = отдельные API.**
|
||
|
||
```
|
||
contracts-app/
|
||
├── Dockerfile
|
||
├── requirements.txt
|
||
├── .env.example
|
||
└── site/
|
||
├── app.py ← главный, собирает слои (класс ContractsApp)
|
||
├── db.py ← слой БД (connect, query)
|
||
├── test_routes.py ← слой /test (Blueprint) — мост к БД извне
|
||
├── static/css/
|
||
└── templates/
|
||
```
|
||
|
||
### Слои (текущие)
|
||
|
||
| Слой | Файл | Что делает |
|
||
|---|---|---|
|
||
| Ядро | `app.py` | Класс ContractsApp, регистрирует Blueprint'ы |
|
||
| БД | `db.py` | `connect()` и `query(sql, params)` |
|
||
| Тест | `test_routes.py` | Blueprint `/test` — статус БД, список таблиц, SQL |
|
||
|
||
---
|
||
|
||
## Конфигурация (production)
|
||
|
||
```json
|
||
// startupConfiguration
|
||
{ "resourceRealm": "k8s-4-ext-nubes-ru" }
|
||
|
||
// clusterConfiguration
|
||
{ "cpu": "500", "memory": "1024", "replicas": "1" }
|
||
|
||
// accessConfiguration
|
||
{ "domain": "contractor" }
|
||
|
||
// appConfiguration
|
||
{
|
||
"gitPath": "https://gitea.services.ngcloud.ru/Nail/contracts-app.git",
|
||
"version": "3.12",
|
||
"healthPath": "/health"
|
||
}
|
||
|
||
// jsonEnv
|
||
{
|
||
"DB_HOST": "postgresqlk8s-master.xxx.svc.cluster.local",
|
||
"DB_NAME": "contracts",
|
||
"DB_PASS": "xnm9KHLibBvT5lYuQzaBVFPYJQHfTxbS4YeEWMcFvtXuXfLaXvgogqJ6uW0nbBUB",
|
||
"DB_PORT": "5432",
|
||
"DB_USER": "constracts",
|
||
"DB_SSLMODE": "disable"
|
||
}
|
||
```
|
||
|
||
⚠️ **DB_HOST** всё ещё `xxx` — нужно заменить на реальный:
|
||
`postgresqlk8s-master.60bdf3e3-5087-41ff-b760-fe6ea544a80e.svc.cluster.local`
|
||
|
||
⚠️ **DB_USER** написано `constracts` (опечатка) — должно быть `contracts`
|
||
|
||
---
|
||
|
||
## Хронология деплоев
|
||
|
||
### Попытка #1 — 11:34, Таймаут health check (478 сек)
|
||
- **Причина:** `debug=True` в app.run(), жёсткие версии в requirements.txt
|
||
- **Решение:** убрал debug, смягчил версии, health → plain text
|
||
|
||
### Попытка #2 — 12:12, Под(ы) не работают (ImportError)
|
||
- **Причина:** `from . import db` — относительные импорты не работают при `python app.py` из папки site/
|
||
- **Ошибка:** `ImportError: attempted relative import with no known parent package`
|
||
- **Решение:** заменил на абсолютные: `import db`, `from test_routes import test_bp`
|
||
|
||
### Попытка #3 — 12:18, Успех ✅
|
||
- Health: OK
|
||
- DB: fail (переменные не заданы)
|
||
|
||
### Попытка #4 — 12:??, (ожидается)
|
||
- Добавлены переменные БД
|
||
|
||
---
|
||
|
||
## Платформа: требования Flask-сервиса
|
||
|
||
Из `flask_manual.md`:
|
||
- `requirements.txt` в корне
|
||
- Код в `site/`
|
||
- Запуск: `python app.py`
|
||
- Python: 3.12-slim
|
||
- HealthCheck: задаётся параметром
|
||
- Git: публичный доступ
|
||
|
||
---
|
||
|
||
## API эндпоинты
|
||
|
||
| Метод | Путь | Что |
|
||
|---|---|---|
|
||
| GET | `/` | Главная (HTML, статус БД) |
|
||
| GET | `/health` | Health check → "OK" |
|
||
| GET | `/test` | Статус БД + список команд |
|
||
| POST | `/test` `{"action":"tables"}` | Список таблиц |
|
||
| POST | `/test` `{"action":"sql","sql":"..."}` | Произвольный SQL |
|
||
|
||
---
|
||
|
||
## План дальнейших работ
|
||
|
||
1. ✅ Flask-заготовка деплоится
|
||
2. ✅ Слои db.py + test_routes
|
||
3. ✅ Подключить БД (переменные заданы)
|
||
4. ✅ Создать базу contracts (через /test createdb)
|
||
5. ✅ Парсер docx/pdf/doc/zip — parser.py
|
||
6. ⬜ Загрузка документов в БД (contract_docs)
|
||
7. ⬜ LLM-нормализация строк
|
||
8. ⬜ Схема таблиц (contracts, spec_rows, spec_history)
|
||
9. ⬜ DIFF допников, кумулятивная история
|
||
10. ⬜ Fuzzy-match с каталогом услуг
|
||
|
||
---
|
||
|
||
## Хронология деплоев (полная)
|
||
|
||
### Попытка #1 — 11:34, Таймаут health check (478 сек)
|
||
- **Причина:** `debug=True` в app.run(), жёсткие версии в requirements.txt
|
||
- **Решение:** убрал debug, смягчил версии, health → plain text
|
||
|
||
### Попытка #2 — 12:12, Под(ы) не работают (ImportError)
|
||
- **Причина:** `from . import db` — относительные импорты не работают при `python app.py` из папки site/
|
||
- **Ошибка:** `ImportError: attempted relative import with no known parent package`
|
||
- **Решение:** заменил на абсолютные: `import db`, `from test_routes import test_bp`
|
||
|
||
### Попытка #3 — 12:18, Успех, но БД fail
|
||
- Health: OK
|
||
- DB: fail — переменные не заданы
|
||
|
||
### Попытка #4 — ~12:31, БД fail — password auth failed
|
||
- Хост резолвится (10.102.125.70), порт доступен
|
||
- Ошибка: `password authentication failed for user "contracts"`
|
||
- Пароль от ipwhitelist не подходит для пользователя contracts
|
||
|
||
### Попытка #5 — 12:35, db.connect() возвращает ошибки
|
||
- Улучшена диагностика — теперь /test показывает точную ошибку
|
||
|
||
### Попытка #6 — ~12:38, БД fail — database "contracts" does not exist
|
||
- Аутентификация прошла (пароль исправлен)
|
||
- База не существует
|
||
|
||
### Попытка #7 — 12:41, добавлен /test createdb
|
||
- Создан endpoint для создания БД через API
|
||
|
||
### Попытка #8 — 12:49, БАЗА СОЗДАНА ✅
|
||
- `POST /test {"action":"createdb"}` → `DB 'contracts' created`
|
||
- `/test` → `db: "ok"`
|
||
- Таблицы: только pg_stat_* (служебные)
|
||
|
||
---
|
||
|
||
## Решения по хранению (принято)
|
||
|
||
- ❌ S3 / приватная репа / файловая система — данные уходят за пределы облака
|
||
- ❌ SQLite — не подходит для облачного сервиса
|
||
- ✅ **PostgreSQL BYTEA + JSONB** — всё внутри кластера, без внешних зависимостей
|
||
- `contract_docs` — исходные файлы (original_bytes BYTEA) + сырой парсинг (parsed_json JSONB)
|
||
|
||
---
|
||
|
||
## Парсер (parser.py)
|
||
|
||
Принцип: **ничего не фильтровать, не терять ни символа**.
|
||
|
||
```
|
||
docx ──▶ python-docx ──▶ elements: [{paragraph, style, text}, {table, rows}, ...]
|
||
.doc ──▶ libreoffice ──▶ docx ──▶ python-docx
|
||
pdf ──▶ pdfplumber ──▶ страницы → текст + таблицы
|
||
zip ──▶ zipfile ──▶ рекурсивно parse() каждый файл
|
||
```
|
||
|
||
Результат: полный слепок документа → в БД → дальше LLM разбирает.
|
||
|
||
Протестирован на реальном примере (спецификация-XXX001-03700.docx):
|
||
- 12 элементов (4 таблицы + 8 параграфов)
|
||
- Все стили сохранены
|
||
- Ничего не потеряно
|
||
|
||
---
|
||
|
||
## Текущая структура проекта
|
||
|
||
```
|
||
contracts-app/
|
||
├── Dockerfile
|
||
├── requirements.txt ← flask, gunicorn, python-docx, requests, psycopg2-binary, python-dotenv, pdfplumber
|
||
├── .env.example
|
||
├── README.md
|
||
└── site/
|
||
├── __init__.py
|
||
├── app.py ← класс ContractsApp, сборка слоёв
|
||
├── db.py ← слой БД: connect(), query(), _pg_connect(), ensure_db()
|
||
├── test_routes.py ← слой /test: статус, tables, sql, createdb
|
||
├── parser.py ← слой парсера: parse() для docx/pdf/doc/zip
|
||
├── static/css/
|
||
└── templates/
|
||
```
|
||
|
||
---
|
||
|
||
## Конфигурация (актуальная)
|
||
|
||
```json
|
||
// clusterConfiguration
|
||
{ "cpu": "500", "memory": "1024", "replicas": "1" }
|
||
|
||
// accessConfiguration
|
||
{ "domain": "contractor" }
|
||
// URL: https://contractor.pythonk8s.services.ngcloud.ru
|
||
|
||
// appConfiguration
|
||
{
|
||
"gitPath": "https://gitea.services.ngcloud.ru/Nail/contracts-app.git",
|
||
"version": "3.12",
|
||
"healthPath": "/health"
|
||
}
|
||
|
||
// jsonEnv
|
||
{
|
||
"DB_HOST": "postgresqlk8s-master.60bdf3e3-5087-41ff-b760-fe6ea544a80e.svc.cluster.local",
|
||
"DB_NAME": "contracts",
|
||
"DB_PASS": "****",
|
||
"DB_PORT": "5432",
|
||
"DB_USER": "contracts",
|
||
"DB_SSLMODE": "disable",
|
||
"LLM_API_KEY": "sk-ucI...",
|
||
"LLM_API_URL": "https://api.aillm.ru/v1/chat/completions"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Сага с LLM (aillm.ru + HTTP/2)
|
||
|
||
### Проблема
|
||
Python-библиотеки (`requests`, `httpx`) не держат HTTP/2 из коробки.
|
||
`api.aillm.ru` за ddos-guard, который **требует HTTP/2 от облачных IP**.
|
||
С локальной машины (81.200.23.210) даже HTTP/1.1 работает — для этого IP ddos-guard делает исключение.
|
||
|
||
### Хронология попыток
|
||
|
||
| # | Подход | Результат |
|
||
|---|---|---|
|
||
| 1 | `requests` (HTTP/1.1) | ❌ 401 token_not_found_in_db (ложная ошибка от ddos-guard) |
|
||
| 2 | `httpx` с `http2=True` | ❌ то же самое — `h2` пакет не установился в контейнере |
|
||
| 3 | `httpx[http2]` + `h2` в requirements | ❌ `h2` не ставится через pip в slim-контейнере |
|
||
| 4 | `subprocess.run(['curl', '-s', '--http2', ...])` | ⬜ ждёт редеплоя |
|
||
|
||
### Ключевые находки
|
||
|
||
1. **Хеш ключа не совпадал:** локально `5fad79ba...`, в облаке `c772c3e5...`.
|
||
Оказалось — не разные ключи, а `ddos-guard` возвращает ложный 401 при HTTP/1.1,
|
||
хешируя какой-то внутренний токен, а не наш ключ.
|
||
|
||
2. **Node.js `fetch()` работает** (проект `say`) — потому что undici (нативный fetch в Node)
|
||
поддерживает HTTP/2 из коробки. Python — нет.
|
||
|
||
3. **`curl --http2`** — единственный гарантированный способ получить HTTP/2 в Python-контейнере,
|
||
без дополнительных пакетов.
|
||
|
||
4. **Доступные модели:** `gpt-oss-120b`, `qwen3.6-27b-fp8`, `qwen3-6-27b-fp8-opt`, `whisper-large-v3-turbo`.
|
||
|
||
### Решение
|
||
`llm_client.py` использует `subprocess.run(['curl', '-s', '--http2', ...])` вместо Python HTTP-библиотек.
|
||
|
||
---
|
||
|
||
## Хронология коммитов (14.06.2026)
|
||
|
||
### DB слой
|
||
- `ba2e855` — `db.py`: `execute()` + `query_one()` для INSERT/UPDATE/DELETE и единичного SELECT
|
||
- `4635ed4` — `test_routes`: action `exec` через `db.execute()` (DDL без fetch)
|
||
- `9d01dba` — `schema.py`: `db.query → db.execute` для DDL
|
||
|
||
### Upload слой
|
||
- `8db35e3` — `upload.py`: Blueprint `/upload`, поток bytes→parser→textify→DB
|
||
- `db2f6cc` — fix MIME: приоритет расширения над content_type
|
||
|
||
### LLM слой
|
||
- `44e53ed` — `llm_client.py`: HTTP-клиент (сначала `requests`)
|
||
- `fe8a556` — `test_routes`: action `llm` для теста
|
||
- `c580c93` — fix: модель `gpt-oss-120b` (не `deepseek-chat`)
|
||
- `5904830` — fix: `httpx[http2]` вместо `requests`
|
||
- `c97f26d` — fix: `h2` явно в requirements
|
||
- `099edbc` — fix: `curl --http2` через `subprocess` вместо httpx
|
||
|
||
### Debug
|
||
- `cc3203a` — `test_routes`: action `debug` для просмотра env vars
|
||
- `0d0ba18` — debug показывает длину ключа
|
||
- `b457de4` — debug показывает `h2_available` и `httpx_version`
|
||
|
||
---
|
||
|
||
## Развязка саги с LLM: опечатка в ключе
|
||
|
||
После 2 часов попыток (HTTP/2, h2, curl, httpx) причина оказалась простой:
|
||
**в переменной `LLM_API_KEY` в платформе была опечатка**.
|
||
|
||
Сравнение хешей:
|
||
- Правильный ключ: `sk-ucI5YvOticoOQ9Kuj5K9mQ` → hash `5fad79ba`
|
||
- Ключ в облаке: `sk-ucI5YvOticoOQK9ujK5m9Q` → hash `c772c3e5` (ошибка 401)
|
||
|
||
Перепутаны местами `9K` → `K9` и `5K` → `K5`.
|
||
|
||
**Урок:** всегда первым делом проверять входные данные, а не гнаться за архитектурными гипотезами.
|
||
|
||
### Финальное решение LLM
|
||
`httpx` + `h2` (отдельно в requirements) + `http2=True`. Работает.
|
||
Модель: `gpt-oss-120b` (120B, reasoning).
|
||
|
||
---
|
||
|
||
## Extractor (extractor.py) — 14.06.2026
|
||
|
||
LLM-извлечение строк спецификации из распарсенного текста.
|
||
|
||
**Поток:** `parsed_text → промпт → LLM → JSON → [{row_num, name, price, qty, sum, date}]`
|
||
|
||
**Результат на реальном документе:** 14 строк из двух таблиц спецификации.
|
||
LLM корректно определила изменение цены (213 905 → 250 000) и разные даты (01.04 → 25.04).
|
||
|
||
Промпт: строгий формат JSON, поддержка `unresolved` для нераспознанных значений.
|
||
|
||
---
|
||
|
||
## Differ (differ.py) — 14.06.2026
|
||
|
||
Сравнение строк спецификаций между допниками. Чистая функция без зависимостей.
|
||
|
||
**Вход:** `rows_old`, `rows_new` (списки dict)
|
||
**Выход:** `{changes: [{row_num, change_type, old_values, new_values, changed_fields}], summary}`
|
||
|
||
**change_type:** `added` | `deleted` | `changed` | `unchanged`
|
||
|
||
**Тест:** row 1 (changed: price, date), row 2 (unchanged), row 3 (added) ✅
|
||
|
||
---
|
||
|
||
## Текущий статус (14.06.2026 08:15)
|
||
|
||
### Готовые слои (11 файлов)
|
||
```
|
||
site/
|
||
├── app.py — сборка (ensure_schema + Blueprints)
|
||
├── db.py — транспорт БД (connect, query, execute, query_one)
|
||
├── schema.py — DDL 5 таблиц
|
||
├── parser.py — bytes → elements (docx/pdf/doc/zip)
|
||
├── textify.py — elements → текст
|
||
├── upload.py — POST /upload (file → parse → textify → DB)
|
||
├── llm_client.py — HTTP/2 к aillm.ru (httpx+h2)
|
||
├── extractor.py — текст → LLM → строки спецификации
|
||
├── differ.py — сравнение строк между версиями
|
||
├── test_routes.py — /test (status, tables, sql, exec, llm, extract, debug, createdb)
|
||
└── templates/
|
||
```
|
||
|
||
### Осталось
|
||
- `api.py` — Blueprint для договоров/допников/истории
|
||
- Интеграция цепочки: upload → extract → save spec_rows → diff → spec_history
|