Refactor code structure for improved readability and maintainability

FACEAI_INTEGRATION_PLAN.md

@@ -61,6 +61,7 @@ Use three deployable parts:
 
 - Read the handoff token or FaceAI session cookie.
 - Show the legacy-like header and navigation.
+- Check whether the mounted FaceAI dataset exists for the selected race before enabling uploads.
 - Let the user upload a selfie.
 - Create a race-scoped search request.
 - Poll job status or show queued state.
@@ -72,7 +73,7 @@ Use three deployable parts:
 
 - Receive a race-scoped search job.
 - Queue requests and process them one by one.
-- Run the external face-recognition program.
+- Resolve `year/monthFolder/raceFolder` inside the mounted dataset root, take the first `.pkl` file in that race directory, and run the external face-recognition program against it.
 - Return match results with confidence and photo ids or file identifiers.
 - Return a completed result set usable by the legacy filter handoff.
 
@@ -95,6 +96,10 @@ Instead:
    - access flags for FaceAI
    - race id
    - race slug or descriptor
+   - race storage metadata needed to resolve the mounted FaceAI dataset:
+     - `year`
+     - `monthFolder` like `04.APRILE`
+     - `raceFolder` like `LIVORNO` or `PISA`
    - current page URL as `returnUrl`
    - expiry time, ideally 1 to 5 minutes
 3. Browser is redirected to `https://faceai.regalamiunsorriso.it/auth/callback?token=...`
@@ -138,7 +143,7 @@ The lowest-risk way to do that is to update `www/_js/rus-ecom-240621.js` so that
 - removes that select from the rendered UI
 - inserts a `Face ID` button in the same area
 - builds the launch URL using the current race context and current page URL
-- carries `raceId`, race description or slug, language, and exact `returnUrl`
+- carries `raceId`, race description or slug, `raceYear`, `raceMonthFolder`, `raceFolder`, language, and exact `returnUrl`
 
 This avoids fragile JSP layout edits and keeps the change deployable as a single JS asset update.
 
@@ -172,7 +177,7 @@ This is preferable to putting the matched ids directly in the browser URL, becau
 
 ## FaceAI App Structure
 
-The requested target folder is `faceai/`. It does not currently exist in this workspace, so this plan assumes it will be created as a new app.
+The target folder is `faceai/`, and this workspace now contains an implemented scaffold there.
 
 Suggested structure:
 
@@ -198,10 +203,11 @@ faceai/
 5. FaceAI shows a page styled like the old site, including a matching header and a clear `Back to race page` action.
 6. User uploads a selfie.
 7. FaceAI creates a search job with `userId`, `raceId`, `requestId`, and selfie file reference.
-8. FaceAI polls until the processing job completes.
-9. Once the result is ready, FaceAI redirects the browser back to the original race page on `www`.
-10. The legacy site resolves the matched photo ids and renders the race page filtered to those photos only, similar in spirit to the existing pettorale-based flow.
-11. User opens and downloads photos exactly as they do today, through the legacy site.
+8. FaceAI checks the mounted race directory immediately and, if no `.pkl` is present for that race, disables processing and offers only the return path.
+9. FaceAI polls until the processing job completes.
+10. Once the result is ready, FaceAI redirects the browser back to the original race page on `www`.
+11. The legacy site resolves the matched photo ids and renders the race page filtered to those photos only, similar in spirit to the existing pettorale-based flow.
+12. User opens and downloads photos exactly as they do today, through the legacy site.
 
 ## Result And Download Strategy
 
@@ -255,6 +261,20 @@ For v1, `photoId` is the most important field. If the legacy page is the final r
 
 Race scope is mandatory. The service must never search globally by default.
 
+The mounted dataset layout is now assumed to be:
+
+```text
+/mounted-pkl-root/
+  2026/
+    04.APRILE/
+      PISA/
+        any-file-name.pkl
+      LIVORNO/
+        any-file-name.pkl
+```
+
+The `.pkl` filename does not matter. The first `.pkl` found at the race root is the one passed to the matcher.
+
 ## Async Processing Design
 
 Use an API plus worker model.
@@ -275,6 +295,7 @@ Input job:
 
 - request id
 - race id
+- race storage metadata: `year`, `monthFolder`, `raceFolder`
 - selfie storage path
 - user id
 - email
@@ -370,7 +391,7 @@ This is safer than trying to embed the old JSP header directly into a Node app.
 
 - Update `www/_js/rus-ecom-240621.js` to remove the dropdown from the UI and insert the FaceAI button.
 - Add the legacy auth bridge endpoint.
-- Pass `raceId`, `lang`, and `returnUrl` into the FaceAI launch.
+- Pass `raceId`, `lang`, `returnUrl`, `raceYear`, `raceMonthFolder`, and `raceFolder` into the FaceAI launch.
 - Add the legacy return endpoint or result-aware race filter path.
 
 ### Phase 3: FaceAI app shell