283 lines
11 KiB
Markdown
283 lines
11 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"
|
|
}
|
|
```
|