# ADR-002: Batch mode и config

**Статус**: Принято
**Дата**: 2026-03-18

## Контекст

После завершения MVP (шаги 1–7) пользователям не хватает:
- Обработки нескольких файлов за один вызов (batch mode)
- Конфигурационного файла для хранения дефолтов (модель, язык, устройство)

## Решения

### 1. Prescan-first: валидация до загрузки модели

Модель загружается **только если есть файлы для обработки**. Перед загрузкой модели выполняется полный prescan: валидация всех файлов и проверка существующих транскриптов.

**Почему**: загрузка модели (large-v3) занимает ~10 секунд и ~3 GB RAM/VRAM. Повторный запуск по уже обработанным файлам должен быть дешёвым no-op.

### 2. TranscribeFileResult: возврат обновлённого состояния модели

При mid-stream CUDA fallback `_transcribe_file()` перезагружает модель на CPU внутри себя. Чтобы следующие файлы в батче не грузили модель повторно, результат включает обновлённые `model` и `actual_device`.

```python
@dataclass
class TranscribeFileResult:
    result: TranscribeResult
    model: WhisperModel      # может измениться при fallback
    actual_device: str        # может измениться при fallback
```

**Альтернатива**: передавать модель по ссылке через mutable контейнер — менее явно и сложнее тестировать.

### 3. Конфиг: CWD → глобальный, без мержа

Порядок поиска:
1. `.transcriber.toml` в текущей директории (проектный конфиг)
2. `~/.config/transcriber/config.toml` (глобальный конфиг)

Первый найденный побеждает, мержа между файлами нет.

**Почему**: CWD-конфиг удобен для per-project дефолтов (`language = "ru"` для русскоязычного проекта), глобальный — для машинных дефолтов (`device = "cpu"` на ноутбуке без GPU). Мерж усложняет предсказуемость.

**Приоритет значений**: CLI > конфиг > хардкод.

### 4. `_transcribe_file()` — внутренний helper

Публичный API (`transcribe()`) сохранён без изменений. Новая функция `_transcribe_file()` — внутренний helper с префиксом `_`, не часть публичного контракта.

`transcribe()` стала тонкой обёрткой: `load_model()` + `_transcribe_file()` → `TranscribeResult`.

## Последствия

- Обратная совместимость CLI: `transcribe file.mp4` работает как раньше
- Все существующие тесты проходят без изменений сигнатур
- Batch mode: модель загружается один раз для всех файлов
- `--force` флаг для перезаписи существующих транскриптов в батч-режиме