diff --git a/docs/DATACONNECT_GUIDES/backend_cloud_run_functions.md b/docs/DATACONNECT_GUIDES/backend_cloud_run_functions.md new file mode 100644 index 00000000..a8214808 --- /dev/null +++ b/docs/DATACONNECT_GUIDES/backend_cloud_run_functions.md @@ -0,0 +1,183 @@ +# Backend Cloud Run / Functions Guide + +## 1) Validate Shift Acceptance (Worker) +**Best fit:** Cloud Run + +**Why backend logic is required** +- Shift acceptance must be enforced server‑side to prevent bypassing the client. +- It must be race‑condition safe (two accepts at the same time). +- It needs to be extensible for future eligibility rules. + +**Proposed backend solution** +Add a single command endpoint: +- `POST /shifts/:shiftId/accept` + +**Backend flow** +- Verify Firebase Auth token + permissions (worker identity). +- Run an extensible validation pipeline (pluggable rules): + - `NoOverlapRule` (M4) + - Future rules can be added without changing core logic. +- Apply acceptance in a DB transaction (atomic). +- Return a clear error payload on rejection: + - `409 CONFLICT` (overlap) with `{ code, message, conflictingShiftIds }` + +--- + +## 2) Validate Shift Creation by a Client (Minimum Hours — soft check) +**Best fit:** Cloud Run + +**Why backend logic is required** +- Creation rules must be enforced server‑side so clients can’t bypass validations by skipping the UI or calling APIs directly. +- We want a scalable rule system so new creation checks can be added without rewriting core logic. + +**Proposed backend solution** +Add/route creation through a backend validation layer (Cloud Run endpoint or a dedicated “create order” command). + +**On create** +- Compute shift duration and compare against vendor minimum (current: **5 hours**). +- Return a consistent validation response when below minimum, e.g.: + - `200 OK` with `{ valid: false, severity: "SOFT", code: "MIN_HOURS", message, minHours: 5 }` + - (or `400` only if we decide it should block creation; for now it’s a soft check) + +**FE note** +- Show the same message before submission (UX feedback), but backend remains the source of truth. + +--- + +## 3) Enforce Cancellation Policy (no cancellations within 24 hours) +**Best fit:** Cloud Run + +**Why backend logic is required** +- Cancellation restrictions must be enforced server‑side to prevent policy bypass. +- Ensures consistent behavior across web/mobile and future clients. + +**Proposed backend solution** +Add a backend command endpoint for cancel: +- `POST /shifts/:shiftId/cancel` (or `/orders/:id/cancel` depending on ownership model) + +**Backend checks** +- If `now >= shiftStart - 24h`, reject cancellation. + +**Error response** +- `403 FORBIDDEN` (or `409 CONFLICT`) with `{ code: "CANCEL_WINDOW_LOCKED", message, windowHours: 24, penalty: }` +- Once penalty is finalized, include it in the response and logs/audit trail. + +--- + +## 4) Implement Worker Documentation Upload Process +**Best fit:** Cloud Functions v2 + Cloud Storage + +**Why backend logic is required** +- Uploads must be stored securely and reliably linked to the correct worker profile. +- Requires server‑side auth and auditing. + +**Proposed backend solution** +- HTTP/Callable Function: `uploadInit(workerId, docType)` → returns signed upload URL + `documentId`. +- Client uploads directly to Cloud Storage. +- Storage trigger (`onFinalize`) or `uploadComplete(documentId)`: + - Validate uploader identity/ownership. + - Store metadata in DB (type, path, status, timestamps). + - Link document to worker profile. +- Enforce access control (worker/self, admins, authorized client reviewers). + +--- + +## 5) Parse Uploaded Documentation for Verification +**Best fit:** Cloud Functions (event‑driven) or Cloud Run worker (async) + +**Why backend logic is required** +- Parsing should run asynchronously. +- Store structured results for review while keeping manual verification as the final authority. + +**Proposed backend solution** +- Trigger on Storage upload finalize: + - OCR/AI extract key fields → store structured output (`parsedFields`, `confidence`, `aiStatus`). +- Keep manual review: + - Client can approve/override AI results. + - Persist reviewer decision + audit trail. + +--- + +## 6) Support Attire Upload for Workers +**Best fit:** Cloud Functions v2 + Cloud Storage + +**Why backend logic is required** +- Attire images must be securely stored and linked to the correct worker profile. +- Requires server‑side authorization. + +**Proposed backend solution** +- HTTP/Callable Function: `attireUploadInit(workerId)` → signed upload URL + `attireAssetId`. +- Client uploads to Cloud Storage. +- Storage trigger (`onFinalize`) or `attireUploadComplete(attireAssetId)`: + - Validate identity/ownership. + - Store metadata and link to worker profile. + +--- + +## 7) Verify Attire Images Against Shift Dress Code +**Best fit:** Cloud Functions (trigger) or Cloud Run worker (async) + +**Why backend logic is required** +- Verification must be enforced server‑side. +- Must remain reviewable/overrideable by the client even if AI passes. + +**Proposed backend solution** +- Async verification triggered after upload or when tied to a shift: + - Evaluate dress code rules (and optional AI). + - Store results `{ status, reasons, evidence, confidence }`. +- Client can manually approve/override; audit every decision. + +--- + +## 8) Support Shifts Requiring “Awaiting Confirmation” Status +**Best fit:** Cloud Run (domain state transitions) + +**Why backend logic is required** +- State transitions must be enforced server‑side. +- Prevent invalid bookings and support future workflow rules. + +**Proposed backend solution** +- Add status flow: `AWAITING_CONFIRMATION → BOOKED/ACTIVE` (per lifecycle). +- Command endpoint: `POST /shifts/:id/confirm`. + +**Backend validates** +- Caller is the assigned worker. +- Shift is still eligible (not started/canceled/overlapped, etc.). +- Persist transition + audit event. + +--- + +## 9) Enable NFC‑Based Clock‑In and Clock‑Out +**Best fit:** Cloud Run (secure API) + optional Cloud Functions for downstream events + +**Why backend logic is required** +- Clock‑in/out is security‑sensitive and must be validated server‑side. +- Requires strong auditing and anti‑fraud checks. + +**Proposed backend solution** +API endpoints: +- `POST /attendance/clock-in` +- `POST /attendance/clock-out` + +**Validate** +- Firebase identity. +- NFC tag legitimacy (mapped to hub/location). +- Time window rules + prevent duplicates/inconsistent sequences. + +**Persist** +- Store immutable events + derived attendance record. +- Emit audit logs/alerts if needed. + +--- + +## 10) Update Recurring & Permanent Orders (Backend) +**Best fit:** Cloud Run + +**Why backend logic is required** +Updating a recurring or permanent order is not a single update. It may affect **N shifts** and **M shift roles**, and requires extra validations, such as: +- Prevent editing shifts that already started. +- Prevent removing or reducing roles with assigned staff. +- Control whether changes apply to future only, from a given date, or all. +- Ensure data consistency (all‑or‑nothing updates). + +These operations can take time and must be enforced server‑side, even if the client is bypassed.