Skinbase Enhance
================

Operational notes for the Enhance v1/v1.1 module.

For full setup, enablement, worker configuration, verification, and production rollout guidance, see [docs/enhance-setup.md](docs/enhance-setup.md).

Configuration
-------------

- `ENHANCE_ENGINE=stub` keeps Enhance in preview mode for local and workflow testing.
- `ENHANCE_ENGINE=external_worker` uses the prepared external worker adapter boundary.
- `ENHANCE_QUEUE=default` is the current safe default.
- `ENHANCE_QUEUE=enhance` is supported when you want a dedicated queue later.
- If you switch to `ENHANCE_QUEUE=enhance`, Horizon or any worker process must explicitly consume the `enhance` queue in production.

Helpful commands
----------------

```bash
php artisan enhance:health
php artisan enhance:health --json
php artisan enhance:cleanup --dry-run
php artisan enhance:cleanup --force
php artisan queue:work --queue=enhance,default
```

Cleanup behavior
----------------

- Enhance cleanup only removes files under the configured Enhance prefixes:
  - `enhance/sources`
  - `enhance/outputs`
  - `enhance/previews`
- Cleanup never deletes artwork originals, thumbnails, avatars, or other non-Enhance paths.
- Completed jobs can expire automatically via `ENHANCE_COMPLETED_EXPIRES_AFTER_DAYS`.
- Failed jobs can have stale files pruned via `ENHANCE_FAILED_EXPIRES_AFTER_DAYS`.
- Soft-deleted jobs respect `ENHANCE_DELETED_FILE_GRACE_DAYS` before file cleanup.

Scheduler
---------

- The app schedules `php artisan enhance:cleanup --force` daily from `routes/console.php`.
- If you disable Laravel's scheduler in an environment, run cleanup manually or through external cron.

Queue and Horizon reminder
--------------------------

- Stub mode still dispatches queued Enhance jobs and exercises the same lifecycle.
- If workers only consume `default` and you later move Enhance to a dedicated queue, completed jobs will stall in `queued` until `enhance` is added to the worker queue list.

External Worker v1
------------------

- Set `ENHANCE_ENGINE=external_worker` to switch Laravel from the stub processor to the HTTP worker integration.
- Recommended local Laravel env:

```env
ENHANCE_ENGINE=external_worker
ENHANCE_WORKER_URL=http://127.0.0.1:8095
ENHANCE_WORKER_TIMEOUT=600
ENHANCE_WORKER_TOKEN=change-this-token
ENHANCE_WORKER_MAX_DOWNLOAD_MB=60
ENHANCE_QUEUE=enhance
```

- Keep the worker bound to `127.0.0.1` or a private container network. Do not expose it publicly.
- Laravel sends the worker a short-lived source URL. If the storage disk cannot issue temporary URLs, Laravel falls back to a temporary signed internal route that serves only the copied Enhance source file.
- Laravel remains the source of truth: the worker only returns a temporary result, Laravel downloads it, validates it, stores it on the Enhance disk, and then asks the worker to delete the temporary file.
- Useful commands after enabling the worker:

```bash
php artisan config:clear
php artisan enhance:health
php artisan queue:work --queue=enhance,default
php artisan test --filter=EnhanceExternalWorker
```

Real-ESRGAN Runtime
-------------------

- Laravel still uses `ENHANCE_ENGINE=external_worker`. It does not need to know whether the worker uses Pillow or Real-ESRGAN internally.
- Use `WORKER_ENGINE=pillow` for local development, CI, and fallback operation.
- Use `WORKER_ENGINE=realesrgan-ncnn` for the real ncnn-vulkan runtime path.
- If worker health reports `status: degraded`, keep Laravel on the stub processor or a Pillow worker until the Real-ESRGAN runtime is verified.
- Do not expose the worker port publicly.
- Move to the `enhance` Horizon queue only after the worker is healthy and verified in your environment.
- Real-ESRGAN runtime files are not committed. Install them locally or in deployment with the worker scripts:

```bash
cd services/enhance-worker
bash scripts/download-realesrgan-ncnn.sh
bash scripts/verify-realesrgan.sh
```

- Recommended Laravel env when using the real worker:

```env
ENHANCE_ENGINE=external_worker
ENHANCE_QUEUE=enhance
ENHANCE_WORKER_URL=http://127.0.0.1:8095
ENHANCE_WORKER_TIMEOUT=900
ENHANCE_WORKER_TOKEN=change-this-token
ENHANCE_WORKER_MAX_DOWNLOAD_MB=60
```