# 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.