d579d0b142
Add frontend/modules/loyalty with types, API client, design system, feature pages and thin App Router routes under app/loyalty/. BFF proxy at app/api/loyalty/. Include loyalty frontend docs. Co-authored-by: Cursor <cursoragent@cursor.com>
100 lines
4.2 KiB
Markdown
100 lines
4.2 KiB
Markdown
# Beauty API Connection Report
|
|
|
|
**Date:** 2026-07-26
|
|
**Client:** `modules/beauty/services/beauty-business-api.ts`
|
|
**BFF:** `/api/beauty-business/*` → `:8011`
|
|
|
|
---
|
|
|
|
## Connection Architecture
|
|
|
|
```
|
|
Browser (beauty pages)
|
|
→ beautyBusinessApi (tenant + JWT)
|
|
→ Next.js BFF /api/beauty-business/[...path]
|
|
→ beauty-business-service :8011
|
|
```
|
|
|
|
No mock data. All list/create/mutation calls use `beautyBusinessApi` with `X-Tenant-ID` and Bearer token.
|
|
|
|
---
|
|
|
|
## API Resources — Frontend Coverage
|
|
|
|
| API Resource | Methods in Client | UI Surfaces |
|
|
|--------------|-------------------|-------------|
|
|
| `/health`, `/capabilities`, `/metrics` | GET | Hub, dashboards, monitoring |
|
|
| `organizations` | list, get, create, update, delete | Owner, admin |
|
|
| `branches` | list, get, create, update, delete | Owner, admin, booking forms |
|
|
| `customers` | list, get, create | Owner, admin, customer portal, booking |
|
|
| `staff` | list, get, create | Owner, admin, staff portal, schedules |
|
|
| `service-categories` | list, get, create | Owner catalog |
|
|
| `services` | list, get, create | Owner catalog, public site, booking |
|
|
| `staff-schedules` | list, get, create | Owner booking, staff portal |
|
|
| `waiting-list` | list, get, create | Owner, reception queue/walk-in |
|
|
| `treatment-rooms` | list, get, create | Owner salon |
|
|
| `stations` | list, get, create | Owner salon |
|
|
| `branch-policies` | list, get, create | Owner salon |
|
|
| `package-definitions` | list, get, create | Owner, customer, public |
|
|
| `membership-plans` | list, get, create | Owner, customer |
|
|
| `commission-rules` | list, get, create | Owner, staff commission page |
|
|
| `marketing-campaigns` | list, get, create | Owner, public campaigns |
|
|
| `loyalty-integrations` | list, get, create | Owner integrations tab |
|
|
| `communication-integrations` | list, get, create | Owner integrations tab |
|
|
| `integration-dispatches` | list, get, create | Owner integrations tab |
|
|
| `appointments` | list, get, create, update, confirm, check-in, complete, cancel, no-show, history | Owner, reception, customer, staff, public book |
|
|
| `settings` | list, upsert | Owner settings, admin settings |
|
|
| `permissions/catalog` | GET | Owner settings, admin permissions |
|
|
| `audit` | list | Workspace detail drawers |
|
|
| `external-providers` | list, get, create, update, delete | Owner integration pages |
|
|
|
|
---
|
|
|
|
## Workflow Actions Connected
|
|
|
|
| Action | API Endpoint | UI Trigger |
|
|
|--------|--------------|------------|
|
|
| Confirm appointment | `POST .../confirm` | Owner table, reception check-in |
|
|
| Check-in | `POST .../check-in` | Owner table, reception check-in |
|
|
| Complete | `POST .../complete` | Owner table, reception check-out |
|
|
| Cancel | `POST .../cancel` | Owner table, reception |
|
|
| No-show | `POST .../no-show` | Owner table, reception |
|
|
|
|
---
|
|
|
|
## Cross-Module Integrations (Real Links, Not Mocks)
|
|
|
|
| UI Surface | External Module | Behavior |
|
|
|------------|-----------------|----------|
|
|
| Customer invoices/payments | `/accounting/*` | Navigation + empty state |
|
|
| Customer loyalty | Loyalty API via beauty integrations list | Read from `loyaltyIntegrations` |
|
|
| Reception payments | `/accounting` | Explicit link |
|
|
| Owner CRM/accounting integration | `externalProviders` filtered by kind | Real list from API |
|
|
|
|
---
|
|
|
|
## API Methods Not in Backend (Documented)
|
|
|
|
These permissions exist in backend definitions but routes are create/list/get only — client has no update/delete stubs:
|
|
|
|
- customers, staff, service-categories, services, schedules, waiting-list, rooms, stations, policies, packages, memberships, commissions, marketing campaigns, integrations
|
|
|
|
When backend adds PATCH/`/delete`, add methods to `beauty-business-api.ts` and enable `updateFn`/`deleteFn` in resource configs.
|
|
|
|
---
|
|
|
|
## TanStack Query Keys
|
|
|
|
Pattern: `["beauty", tenantId, resource, ...params]`
|
|
Lookups: `["beauty", tenantId, "lookups", entity]`
|
|
Invalidation on mutation: resource queryKey + lookups
|
|
|
|
---
|
|
|
|
## Error Handling
|
|
|
|
- `BeautyBusinessApiError` → toast message + ErrorState retry
|
|
- 401 → session refresh via `getValidAccessToken` / `refreshSession`
|
|
- 403 → `PermissionDeniedState`
|
|
- Network failure → Persian connection error message
|