Regalamiunsorriso/faceai/README.md

# FaceAI Scaffold

This folder scaffolds the new FaceAI app described in the integration plan.

It includes:

- a Vue frontend for the FaceAI upload and polling flow
- a Node/Express backend for session exchange, mocked searches, and return handoff
- a local legacy simulator so the launch and return flow can be tested without the old Java site
- a Dockerized PHP Apache stack for exercising the real `www/faceai_handoff.php` and `www/faceai_return.php` bridge files

## Structure

```text
faceai/
  apps/
    backend/
    frontend/
  docker/
    Dockerfile
```

## What The Local Test Covers

The local simulator exercises the exact flow the plan is aiming for:

1. a legacy-like race page shows a `Face ID` button instead of `tipoPuntoFoto`
2. clicking it hits a mock legacy handoff endpoint
3. the backend signs a short-lived handoff token and redirects to the Vue app
4. the Vue app exchanges the token for its own FaceAI session cookie
5. the user uploads a selfie and starts a mocked race-scoped search
6. the frontend polls until the job completes
7. FaceAI requests a signed return URL
8. the browser is redirected back to a legacy-like filtered race page showing only the matched photos

## Local Run

From this folder:

```bash
npm install
npm run dev
```

Then open:

```text
http://localhost:3001/dev/legacy/race?raceId=101&lang=it
```

That page simulates the old site and launches the FaceAI app at `http://localhost:5173`.

## Docker Run With PHP Simulator

If you do not have PHP locally, use Docker instead:

```bash
npm install
npm run build
docker compose up --build
```

The Docker stack reuses the local FaceAI workspace and only containerizes the runtime services. That means PHP is fully containerized, while the Node service runs inside Docker against the already-installed local workspace dependencies and the already-built frontend assets.

This starts:

- FaceAI app on `http://localhost:3001`
- PHP Apache serving `www` on `http://localhost:8080`

For the end-to-end test through the PHP bridge, open:

```text
http://localhost:8080/faceai_simulator.php?raceId=101&lang=it
```

That page loads the original race-page JavaScript from `www/_js/rus-ecom-240621.js`, lets the script replace the visible `tipoPuntoFoto` selector with the new `Face ID` button, and launches the real PHP handoff bridge at `www/faceai_handoff.php`.

If you change frontend code and want Docker to serve the updated UI, rebuild first with:

```bash
npm run build
```

## Environment

Defaults are already set for local development, but these can be overridden:

```text
PORT=3001
FACEAI_FRONTEND_URL=http://localhost:5173
FACEAI_PUBLIC_BASE_URL=http://localhost:3001
FACEAI_LEGACY_RETURN_URL=http://localhost:3001/dev/legacy/return
FACEAI_SHARED_SECRET=change-me
FACEAI_SESSION_COOKIE=rus_faceai_session
```

If you want FaceAI to return through the new PHP bridge prepared under `www`, point `FACEAI_LEGACY_RETURN_URL` to that endpoint instead, for example `http://localhost/faceai_return.php` or the equivalent URL in your local PHP setup.

In the provided Docker Compose stack, that wiring is already done with:

```text
FACEAI_LEGACY_RETURN_URL=http://localhost:8080/faceai_return.php
```

## Notes

- The backend currently uses in-memory stores and mocked search results.
- No database or real queue is wired yet.
- The local legacy simulator is intentionally backend-driven so the handoff can be tested without compiling the existing Java application.
- `www/faceai_simulator.php` exists only for local testing. It does not replace the actual JSP race page.
- The final legacy integration still needs a real signed identity source and a real return-filter implementation on the old site.