Krow-workspace/docs/DATACONNECT_GUIDES/backend_cloud_run_functions.md

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: <TBD> }
• 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.