# OCR Deployment Guide (Mac + Linux Server)

Bu sənəd layihədə local OCR (`pdftotext` + `pdftoppm` + `tesseract`) quruluşunu həm Mac development, həm də Linux server üçün standartlaşdırır.

## 1) OCR necə işləyir

- Əsas fayl upload olunur (`documents/main-upload`).
- Fayl `documents` cədvəlində `kind=main` və `ocr_status=pending` kimi yazılır.
- Queue job (`ProcessDocumentOcr`) OCR prosesini arxa planda icra edir.
- OCR mətni `documents.ocr_text` sahəsinə yazılır.
- Sonra `documents/search?q=...` ilə həmin mətn üzrə axtarış etmək olur.

## 2) Environment variables

`.env`-də bunlar olmalıdır:

```env
OCR_ENABLED=true
OCR_PDFTOTEXT_BINARY=pdftotext
OCR_PDFTOPPM_BINARY=pdftoppm
OCR_TESSERACT_BINARY=tesseract
OCR_LANGUAGE=aze+eng
OCR_FALLBACK_LANGUAGES=eng
OCR_TIMEOUT_SECONDS=240
OCR_PDF_RENDER_DPI=300
OCR_PDF_MAX_PAGES=30
```

Əgər shared host və ya serverdə PATH fərqlidirsə, binariləri absolute path ver:

```env
OCR_PDFTOTEXT_BINARY=/usr/bin/pdftotext
OCR_PDFTOPPM_BINARY=/usr/bin/pdftoppm
OCR_TESSERACT_BINARY=/usr/bin/tesseract
```

## 3) Mac setup (development)

Homebrew ilə:

```bash
brew install tesseract poppler
```

Azeri dil paketi yoxdursa:

```bash
brew install tesseract-lang
```

Yoxla:

```bash
which tesseract
which pdftotext
which pdftoppm
tesseract --list-langs
php artisan ocr:check
```

## 4) Linux server setup (Ubuntu/Debian)

Paketlər:

```bash
sudo apt update
sudo apt install -y tesseract-ocr tesseract-ocr-aze tesseract-ocr-eng poppler-utils
```

Yoxla:

```bash
which tesseract
which pdftotext
which pdftoppm
tesseract --list-langs
php artisan ocr:check
```

## 5) Laravel runtime requirements

- `QUEUE_CONNECTION=database` (və ya redis)
- Queue worker daimi işləməlidir
- `storage/app/private/appeals/main` writable olmalıdır

Migration:

```bash
php artisan migrate --force
```

Queue worker (manual):

```bash
php artisan queue:work --tries=3 --timeout=240
```

## 6) Supervisor nümunəsi (production)

`/etc/supervisor/conf.d/arxiv-worker.conf`:

```ini
[program:arxiv-worker]
process_name=%(program_name)s_%(process_num)02d
command=/usr/bin/php /var/www/arxiv/artisan queue:work --sleep=2 --tries=3 --timeout=240
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
numprocs=1
redirect_stderr=true
stdout_logfile=/var/www/arxiv/storage/logs/worker.log
user=www-data
```

Aktivləşdir:

```bash
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start arxiv-worker:*
```

## 7) Quick smoke test

1. UI-dan əsas fayl upload et.
2. `documents.ocr_status` ardıcıllığını yoxla: `pending -> processing -> completed`.
3. `documents/search?q=<word>` ilə OCR mətndə axtar.

## 8) Accuracy benchmark (CER/WER)

Layihədə accuracy %-ni ölçmək üçün:

- `storage/app/private/ocr-benchmark` qovluğu yarat.
- Hər sample üçün eyni adda cüt fayl yerləşdir:
  - source: `sample-001.pdf` (və ya `jpg/png/...`)
  - ground-truth: `sample-001.txt`

Komanda:

```bash
php artisan ocr:benchmark
```

Opsiyalar:

```bash
php artisan ocr:benchmark --dataset=/full/path/to/storage/app/private/ocr-benchmark --limit=50 --show=50
```

Nəticədə per-file `CER%`/`WER%` və yekun `Character accuracy`/`Word accuracy` çıxır.

## 9) Tipik problemlər

- `pdftotext tapılmadı`:
  - `poppler-utils` qurulmayıb və ya PATH-də deyil.
- Scan PDF boş çıxır:
  - `pdftotext` bu PDF-də mətn tapa bilməyib; fallback üçün `pdftoppm` olmalıdır.
- `tesseract tapılmadı`:
  - `tesseract-ocr` qurulmayıb və ya PATH-də deyil.
- `failed loading language`:
  - `tesseract-ocr-aze` paketini qur.
- Job işləmirsə:
  - queue worker dayanıbdır və ya `QUEUE_CONNECTION` yanlışdır.