Salon/docs/frontend-spec-requirements.md

# Frontend Technical Specs and Requirements (MVP)

## Purpose
Define the implementation contract for the React frontend against the current backend REST API so the customer flows (auth, search, booking, payment, profile) can ship reliably for KSA.

## Scope
In scope:
- Customer web app (React + Vite) for Phase 1 flows.
- API integration contracts for current backend endpoints.
- UX/error/loading behavior and test requirements.
- i18n/RTL and KSA timezone handling.

Out of scope (Phase 2+):
- Manager/staff admin dashboards.
- Advanced reporting/reviews moderation tools.
- Full observability product dashboards.

## Product and Platform Constraints
- Market default: KSA first.
- Default locale: `ar-sa`; fallback: `en`.
- Timezone baseline: `Asia/Riyadh` (`+03:00`).
- API error contract: HTTP status + `detail` where applicable.
- Booking/payment operations must avoid duplicate side effects.

## UX Priorities (Primary Contract)
- First screen for authenticated and guest users MUST be a feed of nearby/available salons.
- The feed is the default home experience and primary entry to booking.
- Main customer navigation MUST be bottom tabs (mobile-first), not header-first navigation.
- Bottom tabs MUST include at minimum:
  - Home/Feed
  - Bookings
  - Profile
- Optional tabs (when implemented) may include Search/Explore and Payments, but must not displace Home/Feed as default.

## Frontend Architecture Requirements

## Runtime and Stack
- React 18 + Vite.
- React Router (`BrowserRouter`) for route navigation.
- `i18next` + `react-i18next` for translations and direction switching.
- `fetch` wrapper in `src/api/client.js` as single API boundary.
- Auth/session state in `AuthContext`.

## Route Map (Customer)
- `/` home feed (nearby/available salons) + search/filter.
- `/salon/:id` salon detail.
- `/login` phone OTP login.
- `/book?salon=<id>` booking creation.
- `/pay?booking=<id>` payment initiation.
- `/pay/return` payment callback/return surface.
- `/bookings` customer booking history.
- `/profile` customer profile summary.

## Module Boundaries
- `src/api/`: all HTTP logic, standardized errors.
- `src/contexts/`: auth/session lifecycle only.
- `src/hooks/`: domain-side UI logic (`useSalonSearch`, `usePaymentForm`).
- `src/pages/`: route-level composition.
- `src/components/`: reusable presentation and guarded wrappers.
- `src/i18n/`: locale dictionaries and locale/direction state.

## Functional Requirements

### FR-1 Phone-First Authentication
- Login MUST use:
  - `POST /api/auth/phone/request/`
  - `POST /api/auth/phone/verify/`
- Password auth endpoint (`/api/auth/token/`) MUST NOT be used (returns 410).
- Login request form MUST collect:
  - `phone_number` (accept KSA local or E.164 input)
  - `channel` (`sms` or `whatsapp`)
  - optional: `device_id` (recommended for abuse controls)
- Verify step MUST submit `request_id` + 6-digit `code`.
- On success, frontend MUST persist `access` and `refresh` tokens and user payload.

### FR-2 Session Restore and Token Refresh
- On app boot, if `access` exists:
  - call `GET /api/auth/me/`.
- If `401`/token invalid:
  - call `POST /api/auth/token/refresh/` once.
  - retry `GET /api/auth/me/` with new access token.
- If refresh fails, frontend MUST clear tokens and require re-login.

### FR-3 Salon Discovery
- Home MUST render a salon feed by default on first load.
- Feed data MUST come from `GET /api/salons/` and support query params for discovery.
- Home search MUST call `GET /api/salons/?q=<query>`.
- Search SHOULD support additional filters when UI is added:
  - `city`
  - `service`
- Nearby/available ranking can be client-side initially, but server response MUST remain source of truth.
- Result cards MUST link to `/salon/:id`.

### FR-4 Salon Detail
- Detail page MUST call `GET /api/salons/:id/`.
- UI MUST render:
  - salon base info
  - services (duration, amount, currency)
  - staff list
  - optional reviews/photos if present
- CTA MUST deep-link to booking flow with salon id.

### FR-5 Booking Creation
- Booking page MUST require authenticated user.
- Create booking with `POST /api/bookings/` using:
  - `service`
  - `staff` (required)
  - `start_time`
  - `end_time`
  - optional `notes`
- `end_time` MUST match service duration exactly.
- Datetime submitted to backend MUST include explicit offset (`+03:00` for KSA baseline).
- On success (`201`), frontend MUST navigate to payment flow with booking id.

### FR-6 Booking History
- `/bookings` MUST call authenticated `GET /api/bookings/`.
- List MUST show booking id, status, salon/service labels, datetime, and price.
- Datetime rendering MUST use active locale formatting.

### FR-7 Payment Initiation (Idempotent)
- Payment submission MUST call `POST /api/payments/`.
- Payload requirements:
  - `booking_id` (number)
  - `provider` = `moyasar`
  - `idempotency_key` (UUID)
  - `source` object with supported type (`stcpay`, `token`, `applepay`, `samsungpay`)
  - `callback_url` required for `source.type=token`
- Frontend MUST disable duplicate submits while request is in-flight.
- Same payment attempt retry MUST reuse the same `idempotency_key`.
- New attempt MUST generate a new key.
- If response includes `redirect_url`, frontend MUST redirect.

### FR-8 Payment Return Handling
- `/pay/return` MUST parse query params:
  - `status`
  - `id`
- Success statuses shown as success UX: `paid`, `captured`, `authorized`.
- Non-success statuses MUST show neutral/pending/failure guidance and link to profile/bookings.

### FR-9 Locale and Direction
- App MUST allow switching between `ar-sa` and `en`.
- Locale switch MUST:
  - persist preference in local storage
  - set `<html lang>`
  - set `<html dir>` (`rtl` for `ar-sa`, `ltr` for `en`)
- API calls MUST include `Accept-Language` header with active locale.

## API Contract Requirements

| Endpoint | Auth | Request | Success | Error handling |
|---|---|---|---|---|
| `POST /api/auth/phone/request/` | No | `phone_number`, `channel`, optional profile fields | `201` with `request_id`, `expires_at` | `429` may include `retry_after_seconds`; show wait message |
| `POST /api/auth/phone/verify/` | No | `request_id`, `code` | `200` with `access`, `refresh`, `user` | `400` invalid/expired code |
| `POST /api/auth/token/refresh/` | No | `refresh` | `200` with new `access` | logout on failure |
| `GET /api/auth/me/` | Bearer | - | `200` user payload | `401` triggers refresh flow |
| `GET /api/salons/` | No | `q`, optional `city`, `service` | `200` list | show localized generic fetch error |
| `GET /api/salons/:id/` | No | - | `200` detail object | show detail/fallback |
| `POST /api/bookings/` | Bearer | booking payload | `201` booking | `400` field validation errors |
| `GET /api/bookings/` | Bearer | - | `200` list | auth + generic errors |
| `POST /api/payments/` | Bearer | payment payload | `201` created or `200` reused idempotent record | `400/403` with details; never auto-retry with new key |

## Error and State Handling Requirements
- API wrapper MUST throw structured errors with:
  - HTTP status
  - parsed response body
  - best message (`detail` first, fallback to response text)
- For validation objects (`{field: [msg]}`), UI SHOULD render first field message near form and keep raw object in debug logs.
- For `429` with `retry_after_seconds`, UI MUST display server-provided cooldown.
- All mutating forms MUST expose:
  - idle/loading/error/success states
  - submit button disabled while loading

## Security and Abuse-Resistance Requirements
- Use Bearer access token for authenticated endpoints only.
- Include optional `device_id` during phone auth request to strengthen backend abuse controls.
- Never send raw card PAN/CVV data to backend; use tokenized sources only.
- On logout, clear user and both tokens from memory + storage.

## Accessibility and UX Requirements
- All interactive controls MUST have accessible labels.
- Auth/booking/payment forms MUST be keyboard usable.
- Error text MUST be visible and associated with active form context.
- Layout MUST remain usable on mobile widths (`>=320px`) and desktop.

## Non-Functional Requirements
- Reliability: no duplicate payment submission side effects for one attempt.
- Consistency: API errors surfaced predictably and localized where available.
- Maintainability: domain behavior in hooks/services, not route components.
- Extensibility: route/module structure must support manager/staff pages later without rewrite.

## Test Requirements (Frontend)
- Test stack: `vitest` + Testing Library.
- Required coverage for release:
  - phone login request + verify success/failure + 429 cooldown message
  - auth restore and refresh-token fallback
  - protected route redirect behavior
  - salon search loading/empty/results/error
  - booking form validation + API error mapping + success redirect
  - payment form source validation + idempotency key reuse on retry + redirect behavior
  - locale switching persists and sets `lang`/`dir`
  - bookings list rendering and localized datetime output

Run:
- `cd frontend && npm run test`

## Definition of Done (Frontend)
- All FR requirements implemented for in-scope routes.
- API integrations match endpoint/payload contract above.
- No use of deprecated password login API.
- All listed frontend tests pass.
- `ar-sa` and `en` UX verified on mobile + desktop.

## Known Dependencies and Open Decisions
- OAuth/social-linking policy is not finalized; keep social login UI hidden for now.
- Cancellation and refund policies are not finalized; do not ship irreversible customer actions until policy finalization.
- Detailed business-hours/timezone policy beyond current backend validation remains open; keep KSA-offset submission and avoid client-side assumptions that override server validation.