# История проекта 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"
}
```