feat: Add FaceAI integration with handoff and return functionality

- Introduced a new workspace for FaceAI in package.json.
- Implemented FaceAI handoff logic in faceai_handoff.php, including identity verification and token signing.
- Created faceai_return.php to handle return requests from FaceAI, validating tokens and forwarding results.
- Developed faceai_simulator.php and faceai_simulator_view.php for simulating the FaceAI interface with demo photos.
- Enhanced rus-ecom-240621.js to support new FaceAI features, including dynamic URL building and button integration.
- Added faceai_config.php for configuration management, including environment variable handling and utility functions.
- Updated HTML structure and styles in simulator view for better user experience.

faceai/README.md

@@ -0,0 +1,111 @@
+# 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.