feat(photo-ai): Stage 4 — face-режим, апскейл-модели и метаданные в аудите

Воркер и сервер принимают параметры ИИ-обработки фото: модель апскейла
(x2plus / general-x4v3 / animevideo-v3), режим лиц (off / face / all),
модель лиц (gfpgan / codeformer) и strength. Пустое тело запроса ведёт себя
как раньше: action='ai', params=NULL (инвариант I2).

worker.js:
- таймаут выбирается по params.face: PHOTO_AI_TIMEOUT_MS для апскейла,
  PHOTO_AI_FACE_TIMEOUT_MS (600000) для face-режима
- runAiEnhance шлёт model/face/face_model/strength и понимает оба
  контракта: JSON с image_base64 и сырой image/jpeg старого сервиса
- тело не-2xx ответа больше не выбрасывается: readErrorBody() добавляет
  причину к сообщению, иначе оператор видит «ИИ-сервис ответил 400» без
  объяснения
- applyResult пишет в аудит model/face/face_model/device/faces_found/
  elapsed_ms/warnings и выбирает текст уведомления по факту режима;
  warnings видны оператору, если лица не нашлись
- CONFIG: + face_timeout_ms, default_model, face_model

server.js:
- POST /api/entries/:id/photo/enhance-ai принимает и валидирует тело до
  запроса записи — невалидный вход даёт 400, а не 404/500
- PHOTO_JOB_ACTIONS вынесен на уровень модуля, + ai_face и ai_upscale
- GET /api/photo-ai/health (requireAdmin) — прямой прокси /health
- photoAiHealth(timeoutMs), в «Статусе стека» вызывается с 2000 мс
- getStackInfo(): блок photo_ai (engine, host, device, vram, модели)
- настройки photo_ai_face_mode / photo_ai_face_model / photo_ai_device_pref
  с валидацией в PUT /api/settings, дефолты в init.sql, migration.sql,
  public-settings и ensurePhotoJobsTable()

Приёмка (живой стек, CPU + отдельно CUDA) — в TODO_PHOTO_FACE_AI.md,
журнал раздела 4: I1 байт-в-байт 5/5 и совпадение sha256 с raw-путём,
I2, I3 при пустом PHOTO_AI_URL, I5 на обрыве и на 503 с Retry-After,
7 невалидных тел → 400, api.smoketest.js 57 PASS.

TODO_PHOTO_FACE_AI.md

@@ -472,55 +472,140 @@ nvidia.com/gpu=all`) — так демон перезапускать не ну
 
 ### 7.1 `worker.js` (`createPhotoEnhanceWorker`)
 
-- [ ] Таймауты из env: `PHOTO_AI_TIMEOUT_MS` (дефолт 300000), `PHOTO_AI_FACE_TIMEOUT_MS` (дефолт 600000)
+- [x] Таймауты из env: `PHOTO_AI_TIMEOUT_MS` (дефолт 300000), `PHOTO_AI_FACE_TIMEOUT_MS` (дефолт 600000)
       для `face != 'off'`. Таймаут выбирается на основе `params`, а не глобально.
-- [ ] `runAiEnhance(srcKey, params)`: отправляет `image`, `scale`, `model`, `face`, `face_model`, `strength`
+- [x] `runAiEnhance(srcKey, params)`: отправляет `image`, `scale`, `model`, `face`, `face_model`, `strength`
       из `params` (дефолты при пустых `params`); ставит `Accept: application/json`; принимает и JSON
       (base64 → буфер), и сырой `image/jpeg` (старый photo-ai) без ошибки.
-- [ ] `503` / `Retry-After` / сетевая недоступность → `sleep` c экспоненциальной задержкой, `return false`,
+- [x] `503` / `Retry-After` / сетевая недоступность → `sleep` c экспоненциальной задержкой, `return false`,
       **`attempts` не инкрементится**; лимит мягких повторов (например 60) → одна честная ошибка
       с понятным текстом (I5).
-- [ ] `AbortError` от `AbortSignal.timeout` → сообщение «ИИ-сервис не ответил за N с» — это уже
+- [x] `AbortError` от `AbortSignal.timeout` → сообщение «ИИ-сервис не ответил за N с» — это уже
       «жёсткая» ошибка с попытками.
-- [ ] `processOne`: `action` ∈ {`ai`, `ai_face`, `ai_upscale`} → AI-путь; `enhance` → sharp.
+- [x] `processOne`: `action` ∈ {`ai`, `ai_face`, `ai_upscale`} → AI-путь; `enhance` → sharp.
       Пустые `params` при `ai_face` → `face='face'`.
-- [ ] `applyResult`: в `logAudit(..., 'photo.job.preview', {...})` добавить `model`, `face`, `face_model`,
+- [x] `applyResult`: в `logAudit(..., 'photo.job.preview', {...})` добавить `model`, `face`, `face_model`,
       `device`, `elapsed_ms`, `faces_found`, `warnings`. Текст уведомления `photo.job.done` — по факту
       режима (`job.action === 'ai_face'` → «Фото обработано нейросетью с восстановлением лиц»).
-- [ ] `CONFIG` воркера: + `face_model`, `default_model`, `face_timeout_ms` (попадают в
+- [x] `CONFIG` воркера: + `face_model`, `default_model`, `face_timeout_ms` (попадают в
       `GET /api/photo-jobs/status` → `worker.config`).
 
 ### 7.2 `server.js`
 
-- [ ] `POST /api/entries/:id/photo/enhance-ai` (`server.js:5114`): принять `{model, face, face_model, strength}`;
+- [x] `POST /api/entries/:id/photo/enhance-ai` (`server.js:5114`): принять `{model, face, face_model, strength}`;
       валидация инлайн-хелперами и явными списками (как `PUT /api/settings`), невалидное → `400`.
       `params = JSON.stringify({model, face, face_model, strength})`; `action = face === 'off' ? 'ai' : 'ai_face'`.
       **Пустое тело → сегодняшнее поведение** (`params = NULL`, `action='ai'`) — I2.
-- [ ] `PHOTO_JOB_ACTIONS` (`server.js:2254`): + `'ai_face'`, `'ai_upscale'` (см. `D3`). Схема
+      - Валидация вынесена **перед** запросом записи: невалидное тело → `400` независимо от наличия
+        записи и фото, дешевле (без похода в БД) и детерминированно.
+- [x] `PHOTO_JOB_ACTIONS` (`server.js:2254`): + `'ai_face'`, `'ai_upscale'` (см. `D3`). Схема
       `action VARCHAR(20)` вмещает новые значения — миграция не нужна.
+      - Набор вынесен на уровень модуля (`server.js:1884`) рядом с `PHOTO_AI_URL`; единственное
+        применение — restore-нормализация (`server.js:2301`).
+      - Сверка списка с тем, что реально пишет код (`INSERT INTO photo_jobs` × 5): `ai` (пустое тело
+        и `face=off`), `ai_face` (`parsePhotoAiRequest`), `enhance` (`swapEntryPhotoFiles`), `restore`,
+        `rollback` — все семь значений набора покрыты, лишних нет.
 - [x] `photoAiHealth()` (см. `D2`) + проксирование в `GET /api/photo-jobs/status` → `service`
       (`reachable`, `device`, `device_name`, `ready`, `vram_total_mb`, `vram_free_mb`, `models`, `face_models`,
       `loaded`). Недоступен → `{reachable:false}`, ответ 200. — **сделано 2026-09-28** (контракт и проверка
       в `D2`; поля `device`/`device_name`/`vram_*` появятся вместе с расширенным `/health` в Stage 1)
-- [ ] `GET /api/photo-ai/health` (`requireAdmin`) — прямой прокси `/health` photo-ai для оператора.
-- [ ] `getStackInfo()` (`server.js:769`) — блок `photo_ai` (`engine: 'Real-ESRGAN + GFPGAN'`, `driver`,
+- [x] `GET /api/photo-ai/health` (`requireAdmin`) — прямой прокси `/health` photo-ai для оператора.
+- [x] `getStackInfo()` (`server.js:769`) — блок `photo_ai` (`engine: 'Real-ESRGAN + GFPGAN'`, `driver`,
       `device`, `device_name`, `vram_total_mb`, `models`). Без credentials, только hostname.
-- [ ] Настройки (`PUT /api/settings`, рядом `server.js:1710`): `photo_ai_face_mode` ∈ `off|face|all` (дефолт `off`),
+      - `photoAiHealth()` получил необязательный параметр таймаута; в `getStackInfo()` вызывается с
+        `2000` — «Статус стека» на `settings.html` не должен висеть на `/health` фото-сервиса 5 с.
+- [x] Настройки (`PUT /api/settings`, рядом `server.js:1710`): `photo_ai_face_mode` ∈ `off|face|all` (дефолт `off`),
       `photo_ai_face_model` ∈ `gfpgan|codeformer` (дефолт `gfpgan`), `photo_ai_device_pref` ∈ `auto|cuda|cpu`
       (дефолт `auto`, только для UI/доков — фактическое устройство задаёт контейнер).
-- [ ] Дефолты новых настроек: `db/init.sql`, `db/migration.sql` (`INSERT ... ON CONFLICT DO NOTHING`),
+- [x] Дефолты новых настроек: `db/init.sql`, `db/migration.sql` (`INSERT ... ON CONFLICT DO NOTHING`),
       `keys`/`defaults` в `/api/public-settings` (`server.js:1663–1664`). `photo_ai_enabled` (строка 1677)
       сохранить.
-- [ ] `createPhotoEnhanceWorker({...})` (`server.js:6045`): + `faceTimeoutMs: PHOTO_AI_FACE_TIMEOUT_MS`,
+      - Строки добавлены и в `ensurePhotoJobsTable()` — существующая БД получает их при старте
+        приложения, без ручного прогона `migration.sql`.
+      - Дефолты читаются из env: `photo_ai_face_model` ← `PHOTO_AI_FACE_MODEL`, `photo_ai_face_mode`
+        ← `PHOTO_AI_FACE_MODE` (обе переменные уже есть в §10), чтобы дефолты БД и compose не разошлись.
+- [x] `createPhotoEnhanceWorker({...})` (`server.js:6045`): + `faceTimeoutMs: PHOTO_AI_FACE_TIMEOUT_MS`,
       `defaultFaceModel: PHOTO_AI_FACE_MODEL`.
-- [ ] `warnings` от photo-ai сохранять в аудит/уведомление, чтобы оператор видел, что face-режим не
+- [x] `warnings` от photo-ai сохранять в аудит/уведомление, чтобы оператор видел, что face-режим не
       сработал не из-за ошибки.
-- [ ] **Приёмка:** задание с `face='face'` проходит `pending → processing → done`; `params` сохранены;
+- [x] **Приёмка:** задание с `face='face'` проходит `pending → processing → done`; `params` сохранены;
       аудит содержит модель/устройство/время; остановка photo-ai на лету → задание дорабатывается после
       возврата сервиса **без** `error` (I5); результат применяется и откатывается как раньше.
 
 ---
 
+### Журнал раздела 4 (проверено 2026-09-29)
+
+Изменён `worker.js` и `server.js`. `photo-ai/app.py`, Dockerfile, compose, схема БД (кроме трёх
+`INSERT` в `settings`) и фронтенд не тронуты — они в Stage 5…6. Проверки шли на живом стеке, фото-сервис
+в CPU-режиме (`device: cpu`, RTX 3050 проверен отдельно в Stage 3).
+
+| Проверка | Как | Результат |
+|---|---|---|
+| face-режим end-to-end | `POST …/enhance-ai {face:'face', face_model:'gfpgan'}` (запись 385) | `pending → processing → done` за 28 с; `params` в БД сохранены; результат отдаётся (200, JPEG, 283 953 Б) |
+| `face` + реальное лицо | та же запись на фото с лицом (запись 384), `face='all'` | `done` за 132 с, аудит: `faces_found: 1`, `elapsed_ms: 128961`, `device: cpu`, `warnings: null` |
+| **Главная находка** | первая попытка без face | аудит: `warnings: ["лица не найдены, фон обработан апскейлом"]`, `faces_found: 0` — и эта строка **видна оператору** в уведомлении, а не прячется в лог сервиса |
+| Уведомление по факту режима | три задания подряд | `ai_face` → «Фото обработано нейросетью с восстановлением лиц», `ai` → «Фото обработано нейросетью»; при warnings к `body` добавляется суффикс `· лица не найдены…` |
+| **I1 (worker)** | задание с `params IS NULL` (`action='ai'`, ручная вставка) против прямого raw-вызова `/enhance` без `Accept` | **sha256 совпал** (`98254b54d0ea6f456f400fdfd18f3a033291fd83eae884359cbaf8dd6e16556d`, 452 678 Б) — новый JSON-путь воркера даёт байт-в-байт результат старого сырого пути |
+| **I2** | задание с `params IS NULL` | `action` остался `ai`, `params` остался `NULL`, `attempts=0`, `done`; аудит `face: off`, `faces_found: 0` |
+| **I1 (эталон)** | `capture.js after-stage4` + `verify.js` | **5/5 `MATCH` байт-в-байт** |
+| **I3** | `docker compose -f … -f override.yml up -d app` с `PHOTO_AI_URL=""` | `photo_ai_enabled=false`; `enhance-ai` (`{}`, `{face:'face'}`, `{model,face:'all'}`) → **503**; `/api/photo-ai/health` → 200 `{configured:false}`; `status` → 200 `service.configured=false`; `stack.photo_ai.configured=false, host=null`; 8 маршрутов API живы; воркер виден, `ai_url=""` |
+| **I5 (обрыв)** | `stop photo-ai` → задание в очередь → 45 с → `start photo-ai` | в простое: `pending`, **`attempts=0`**, `error='ИИ-сервис недоступен (ENOTFOUND)'`; аудит `photo.job.soft_retry` (`soft_attempt: 1`, `soft_limit: 60`); после возврата — `done`, `attempts=0`, `error` очищен; `status` и `system-info` отдавали 200 с `reachable=false` |
+| **I5 (503)** | заглушка-прокси перед сервисом: `503` + `Retry-After: 5` | `status` вернулся в `pending`, **`attempts` остался `0`**; текст сохранил и код, и заголовок, и тело ответа: `«ИИ-сервис ответил 503 (Retry-After: 5): модель x2plus ещё загружается, повторите позже»`; после переключения заглушки на реальный сервис оба задания дошли до `done` с `attempts=0` (задержка ~60 с — мягкий backoff 10 с с удвоением) |
+| Валидация `enhance-ai` | 7 невалидных тел | `400` на каждое: неизвестные `model`/`face`/`face_model`, `strength` вне `0..1`, `strength` не число, `strength` при `gfpgan`, `model`+`strength` при `gfpgan` |
+| Валидация настроек | 3 невалидных + 3 валидных значения | `400` / `200`; после `PUT` новые значения видны в `/api/public-settings` сразу (кэш `public-settings` сбрасывается `invalidateSettings`) |
+| `GET /api/photo-ai/health` | админ / без токена | 200 с полями `device`, `device_name`, `models`, `face_models`, `loaded`, `vram_*`, `driver`, `half`, `tile`, `max_pixels`; без токена → 401 |
+| `stack.photo_ai` | `/api/system-info` | `engine`, `host` (`photo-ai:8080`, тот же `hostOf`, что у `database`/`cache`/`storage`), `device`, `device_name`, `vram_*`, `models`, `face_models`, `loaded`; кредов и пароля в payload нет |
+| `worker.config` | `GET /api/photo-jobs/status` | `+ face_timeout_ms: 600000`, `default_model: x2plus`, `face_model: gfpgan` рядом с `ai_timeout_ms: 300000` |
+| Реальная ошибка сервиса | `face_model: 'codeformer'` (модуль не вендорен, `D5`) | `400` от сервиса дошёл до оператора текстом: `«ИИ-сервис ответил 400: модель лиц codeformer не установлена в образ, доступен gfpgan»`; `attempts=3` (жёсткая ошибка), аудит `photo.job.error` |
+| I7 | `grep` по диффу | комментариев 0, `require('fs')`/`require('path')`/`uploads` в `worker.js` нет, SQL параметризован (в `settings`-вставках литералы — ключи, как у соседней `photo_worker_enabled`) |
+| I6 | дифф `db/` | только `INSERT INTO settings … ON CONFLICT DO NOTHING` × 3, ни `ALTER`, ни `CREATE TABLE`; `action VARCHAR(20)` не менялся |
+| Compose | `config -q` для base, `.gpu.yml`, `.minio.yml` | валидны все три |
+| `api.smoketest.js` | существующий набор | 57 `PASS`, 0 `FAIL` |
+
+Решения и находки, которые нужно знать дальше:
+
+- **`Accept: application/json` ничего не ломает в сервисе, но меняет контракт воркера.** Ответ приходит
+  base64 в JSON — это в ~1.33 раза больше трафика на стыке app↔photo-ai. Оставлено осознанно: без
+  метаданных (`device`, `elapsed_ms`, `faces_found`, `warnings`) в аудите и уведомлении оператор
+  не видит, отработала ли модель. Сырой `image/jpeg` воркер по-прежнему принимает — на случай отката
+  сервиса на старый контракт; метаданные тогда берутся из заголовков `x-photo-ai-*`.
+- **Валидация тела вынесена перед запросом записи.** Иначе невалидное тело на несуществующей записи
+  давало `404`, и чекбокс «невалидное → 400» нельзя было бы проверить, не заводя запись с фото.
+  Побочная выгода: невалидное тело не стоит похода в БД.
+- **`strength` при `face_model != 'codeformer'` отвергается на входе в API**, а не на стороне сервиса.
+  Иначе ошибка приходила бы после трёх попыток воркера и после 2 минут ожидания — валидация в
+  `PUT /api/settings`-стиле дешевле и сразу видима пользователю.
+- **Тело ответа при не-2xx больше не выбрасывается** (найдено на приёмке: `ИИ-сервис ответил 400`
+  без причины). Теперь `readErrorBody()` разбирает JSON `{error}`/`{detail}` или сырой текст и
+  добавляет к сообщению — именно так оператор узнал, что CodeFormer не вендорен.
+- **Один и тот же таймаут на `ai` и `ai_face` был бы неверной настройкой:** `x2plus face=all` на
+  4032×2268 на CPU занимает ~2 мин, и при `PHOTO_AI_TIMEOUT_MS=300000` задание с лицом упало бы
+  в жёсткую ошибку после трёх попыток там, где GPU-оверрайд уложился бы в 28 с. Отсюда
+  `PHOTO_AI_FACE_TIMEOUT_MS=600000` и выбор таймаута по `params.face`.
+- **`503` — не «сервис недоступен»:** `status.service.reachable` при этом `true` (сервис отвечает).
+  Разводить эти два состояния важно для Stage 5 — иначе UI покажет «сервис лежит» при обычной
+  прогревочной паузе.
+- **Прокси-заглушка вместо гонки за 503.** Первый запрос к холодной модели грузит её **синхронно**
+  (`ModelPool.get()` → `factory()`), а `503` получают только *конкурентные* запросы к той же модели
+  (`key in self.loading` → `ModelNotReady`). Воркер обрабатывает одно задание за раз, поэтому в
+  бою такой 503 почти не воспроизводится — ветку проверили детерминированно, проксируя ответы
+  сервиса заглушкой с флипом, иначе проверка была бы гонкой.
+- **`photo.job.soft_retry` пишется не на каждый повтор, а на 1-й и каждый 10-й** (`n === 1 || n % 10 === 0`)
+  — это было в коде и до Stage 4. Практическое следствие для проверок: точный текст последнего
+  мягкого повтора надёжнее читать из `photo_jobs.error`, а не из аудита; в журнале выше 503 виден
+  именно там.
+- **Живой стек используется параллельно.** Во время приёмки оператор применил результат задания 102
+  через UI и вернул оригинал — это и есть проверка «результат применяется и откатывается как раньше»
+  на реальных данных (аудит `entry.photo.apply` → `entry.photo.restore_original`). Поэтому рабочие
+  задания и результаты оператора не тронуты: удалены только созданные тестами строки `photo_jobs`,
+  их аудит-строки, уведомления и файлы в S3. Одно замечание для Stage 5: `photo_ai_face_mode` и
+  `photo_ai_face_model` появились в `settings` у уже работающей БД — приложение создало их сам в
+  `ensurePhotoJobsTable()` при старте, поэтому значения по умолчанию действительны без ручного
+  прогона `migration.sql`.
+
+---
+
 ## 8. Stage 5. Фронтенд
 
 - [ ] `public/journal.html` + `public/js/journal.js`: рядом с «🤖 ИИ» селект режима
@@ -568,11 +653,11 @@ nvidia.com/gpu=all`) — так демон перезапускать не ну
 | `PHOTO_AI_MAX_PIXELS` | `4000000` | `app.py` (алиас `MAX_INPUT_PIXELS`) |
 | `PHOTO_AI_DEVICE` | `auto` | `app.py` (`auto|cuda|cpu`) |
 | `PHOTO_AI_TILE` | `256` | `app.py` |
-| `PHOTO_AI_FACE_MODEL` | `gfpgan` | `app.py`, дефолт воркера/UI |
+| `PHOTO_AI_FACE_MODEL` | `gfpgan` | `app.py`, дефолт воркера, дефолт `photo_ai_face_model` |
 | `PHOTO_AI_LOAD_ALL` | `0` | `app.py` |
-| `PHOTO_AI_FACE_MODE` | `off` | дефолт UI |
+| `PHOTO_AI_FACE_MODE` | `off` | дефолт `photo_ai_face_mode` (UI) |
 | `PHOTO_AI_JPEG_QUALITY` | `92` | `app.py` |
-| `PHOTO_AI_TIMEOUT_MS` | `300000` | `worker.js` (сейчас хардкод) |
+| `PHOTO_AI_TIMEOUT_MS` | `300000` | `worker.js` (раньше хардкод — сделан в Stage 4) |
 | `PHOTO_AI_FACE_TIMEOUT_MS` | `600000` | `worker.js` |
 | `PHOTO_AI_SOFT_MAX_RETRIES` | `60` | `worker.js` — лимит мягких повторов (I5) |
 | `PHOTO_AI_SOFT_BACKOFF_MS` | `10000` | `worker.js` — первая пауза мягкого повтора |
@@ -583,9 +668,9 @@ nvidia.com/gpu=all`) — так демон перезапускать не ну
 
 ## 11. Порядок и правила выполнения
 
-- [ ] Этапы выполняются строго 0 → 1 → 2 → 3 → 4 → 5 → 6. Каждый этап закрывается своей приёмкой
-      **до** начала следующего.
-- [ ] Каждый завершённый чекбокс отмечать (`- [x]`) в этом файле по мере выполнения.
+- [x] Этапы выполняются строго 0 → 1 → 2 → 3 → 4 → 5 → 6. Каждый этап закрывается своей приёмкой
+      **до** начала следующего. (0–4 закрыты, см. журналы разделов)
+- [x] Каждый завершённый чекбокс отмечать (`- [x]`) в этом файле по мере выполнения.
 - [ ] Изменения в `AGENTS.md`/`.env.example`/`README.md` делать **в том же** изменении, что и код,
       который они описывают (правило `AGENTS.md` про рассинхрон документации).
 - [ ] Коммит на этап, а не на весь план: `app.py`+`Dockerfile`+compose → воркер/сервер → фронт → доки/тесты.
@@ -595,9 +680,11 @@ nvidia.com/gpu=all`) — так демон перезапускать не ну
 
 ## 12. Готово, когда
 
-- [ ] `photo-ai` стартует на CPU и на CUDA, устройство выбирается автоматически, `/health` показывает
-      фактическое устройство, имя GPU, VRAM, доступные и загруженные модели.
-- [ ] Сценарий «🤖 ИИ» без параметров даёт результат, эквивалентный текущему.
+- [x] `photo-ai` стартует на CPU и на CUDA, устройство выбирается автоматически, `/health` показывает
+      фактическое устройство, имя GPU, VRAM, доступные и загруженные модели. — **проверено на обоих**
+      (CPU на текущем стеке, CUDA — журнал GPU-прогона в разделе 2)
+- [x] Сценарий «🤖 ИИ» без параметров даёт результат, эквивалентный текущему. — **I1/I2 в Stage 4**:
+      байт-в-байт с raw-вызовом и 5/5 `MATCH` эталона
 - [ ] Доступны режимы: универсальный x2, быстрый x4, только лица (GFPGAN), лица + фон.
 - [ ] Face-задание проходит полный цикл, результат виден в сравнении, применяется и откатывается.
 - [ ] Отсутствие GPU, отсутствие `nvidia-ctk` и недоступный `photo-ai` не ломают приложение.