# RIP Help System — Help-файл декомпозитор и viewer

Обработва help-файлове (`.html`, `.htm`, `.docx`, `.doc`, `.pdf`, `.txt`), декомпозира ги на секции, извлича картинки, класифицира секциите с Claude API (заглавие + ключови думи), и записва всичко в SQL Server. После генерира интерактивен HTML viewer.

## Архитектура

```
Входни файлове  →  help_processor.py  →  SQL Server   →  generate_html.py  →  help_viewer.html
(.docx, .html,                          (RIP_help_*)                          (Home / Редактор /
 .pdf, .doc)                                                                   Търсене / Генератор)
                                              ↑
                                              │
                                       save_keywords.py  ←  keywords_changes.json
                                                          (от Редактора на viewer-а)
```

## Инсталация

```
pip install -r requirements.txt
```

За стар `.doc` формат — едно от:
- **LibreOffice** в PATH (кросплатформено)
- **MS Word** (Windows, чрез pywin32 COM — автоматичен fallback)

## Конфигурация

Копирай `.env.example` като `.env` и попълни:

```
ANTHROPIC_API_KEY=sk-ant-...
HELP_DB_CONN=DRIVER={ODBC Driver 18 for SQL Server};TrustServerCertificate=yes;SERVER=host,port;DATABASE=db;UID=user;PWD=password
```

`.env` е gitignore-нат. Bat файловете го зареждат автоматично през `_load_env.bat`.

## Употреба (Windows)

### Обработка на нов проект

Първо създай `<PROJECT>_load.bat` и `<PROJECT>_view.bat` (вж. `RIP_load.bat`, `RIP_view.bat` като образец).

| BAT | Какво прави |
|---|---|
| `RIP_load.bat` | Incremental — обработва само нови/променени файлове по SHA-256 hash |
| `RIP_load_force.bat` | `--force --purge-missing` — преобработва всичко, изтрива orphans |
| `RIP_view.bat` | Генерира `help_viewer.html` за prefix=RIP и го отваря в браузъра |

### Директно от CLI

```
python help_processor.py --prefix=<PREFIX> <input_dir> <output_dir>
python help_processor.py --prefix=<PREFIX> --force --purge-missing <input_dir> <output_dir>

python generate_html.py --prefix=<PREFIX>                  # без Home таб
python generate_html.py --prefix=<PREFIX> --home img.png   # с Home таб
```

## Prefix scoping

Всеки проект има свой `--prefix` (напр. `RIP`, `INEX_TM`). Прави следните неща изолирани между проектите:

- Кодовете на секциите: `RIP_0001_SEC_0001` vs `INEX_TM_0001_SEC_0001`
- skip-by-hash (incremental) — само в рамките на prefix-а
- `--purge-missing` — изтрива orphans само в текущия prefix
- `generate_html.py --prefix=X` — viewer-а филтрира по prefix

## Структура на базата

### `RIP_help_files`
| Поле | Тип | Описание |
|---|---|---|
| id | INT IDENTITY | PK |
| prefix | NVARCHAR(50) | Project scope |
| file_path | NVARCHAR(1000) | Пълен път до файла |
| file_hash | CHAR(64) | SHA-256 за incremental |
| processed_at | DATETIME2 | Последна обработка |
| section_count | INT | Брой секции |

UNIQUE constraint: `(prefix, file_path)`

### `RIP_help_sections`
| Поле | Тип | Описание |
|---|---|---|
| id | INT IDENTITY | PK |
| prefix | NVARCHAR(50) | Project scope |
| code | NVARCHAR(80) | `<PREFIX>_NNNN_SEC_NNNN` (UNIQUE) |
| source_file | NVARCHAR(1000) | Източник |
| title | NVARCHAR(500) | AI-генерирано заглавие |
| keywords | NVARCHAR(300) | До 5 ключови думи |
| char_count | INT | Размер на чистия текст |
| output_path | NVARCHAR(1000) | Път до `.txt` файла |
| images | NVARCHAR(MAX) | JSON масив с относителни пътища |
| html_text | NVARCHAR(MAX) | Rich HTML с форматиране (само за `.html` източници) |
| created_at, updated_at | DATETIME2 | |

## HTML Viewer — 3 / 4 таба

- **Home** (опционален, ако `--home <image>` е подаден) — началов екран с изображение
- **Редактор** — таблица със секции; inline редактиране на ключови думи; ✓ Save → JSON download → `save_keywords.py` → UPDATE в БД
- **Търсене** — карти със секции; multi-keyword (intervals = AND, "phrase" = literal); preview с картинки
- **Генератор** — drag & drop ordering → export като HTML (self-contained, всички картинки base64-embed-нати)

## Картинки

Извличат се по време на парсване:
- `.docx` — `<a:blip>` в paragraph drawings → bytes от related_parts
- `.html` — локални файлове и `data:` URLs; HTTP пропуска
- `.pdf` — `pdfplumber.page.crop(bbox).to_image()` като PNG
- `.doc` — след LibreOffice/MS Word конверсия до `.docx`

Филтър ≥ 50×50 px (PIL детектва), за да отрязва иконки/булети.

Записват се в `<output_dir>/images/<code>_img_NN.<ext>`. В текста placeholder `[IMG: images/...]`. В DB `images` колоната съдържа JSON масив с пътищата.

## Constants (в `help_processor.py`)

| Константа | Default | Описание |
|---|---|---|
| `MIN_SECTION_TOKENS` | 60 | Под този праг секцията се слива с предишната |
| `MAX_AI_CHARS` | 4000 | Символи, пращани към Claude |
| `AI_MODEL` | claude-haiku-4-5 | Модел за класификация |
| `MIN_IMAGE_PX` | 50 | Картинки под NxN px се пропускат |

---

## Webapp (FastAPI)

`webapp/` съдържа FastAPI app за server deploy (Coolify / Docker).

### Endpoint-и

| Метод | Път | Описание |
|---|---|---|
| GET | `/` | HTML viewer (Home/Editor/Search/Generator); query `?prefix=RIP&home=1` |
| GET | `/images/<file>` | Сервира картинка от `OUTPUT_DIR/images/` |
| GET | `/home-image` | Home image (от `HOME_IMAGE` env var или `Bairaci.png`) |
| GET | `/api/sections` | JSON списък със секции; query `?prefix=` |
| POST | `/api/keywords/<code>` | `{keywords: "..."}` → UPDATE в DB |
| GET | `/healthz` | Health check (DB ping) |

### Env vars

| Var | Default | Описание |
|---|---|---|
| `HELP_DB_CONN` | — | libpq формат за Postgres (задължително) |
| `OUTPUT_DIR` | `./data` | Директория с `images/` подпапка |
| `HOME_IMAGE` | — | Абсолютен път към home картинка (опционален) |

### Локален dev

```
pip install -r requirements-webapp.txt
$env:HELP_DB_CONN="host=192.168.88.18 port=5432 dbname=rip_help_system user=sa password=..."
$env:OUTPUT_DIR="q:\RIP_Help_Source\Output"
python -m uvicorn webapp.main:app --reload
# отвори http://127.0.0.1:8000/?prefix=RIP&home=1
```

### Coolify deploy

1. В Coolify: New Resource → Application → Public/Private Repository
2. URL: `https://git.inex-project.net/sabo/rip-help-system.git`
3. Build pack: **Dockerfile**
4. Environment variables (в Coolify UI, не в git):
   - `HELP_DB_CONN=host=... port=5432 dbname=rip_help_system user=... password=...`
   - `OUTPUT_DIR=/data/help_output`
   - `HOME_IMAGE=/data/help_output/Bairaci.png` (по избор)
5. Persistent storage (volume): `/data/help_output` (там качваш картинките с WinSCP/rsync)
6. Port: 8000
7. Custom domain → Coolify прави HTTPS (Let's Encrypt) автоматично

### Качване на картинки на сървъра

Локалният `help_processor.py` пише в `q:\RIP_Help_Source\Output\` (включително `images/` подпапка). За deploy:

```
# с WinSCP — sync на цялата директория
local:  q:\RIP_Help_Source\Output\
remote: /home/sabo/share/help_output/   ← Coolify volume mount
```

Базата (Postgres на 192.168.88.18) се ползва от webapp-а директно.