cleanup phases 6
This commit is contained in:
hamid
@@ -0,0 +1,122 @@
|
||||
# Frontend Phase 8 (f8-b9) — Booking detail, sessions & nurse EVV — report
|
||||
|
||||
**Date:** 2026-07-10 · **Lane:** frontend · **Consumes:** [bookings-evv.md](../../contracts/domains/bookings-evv.md) (b9)
|
||||
· **Unlocks:** f9 (checkout/pay), f13 (reviews & patient records)
|
||||
|
||||
## What was built
|
||||
|
||||
The post-payment engagement — the hinge between "I asked for a nurse" and "a nurse is delivering care."
|
||||
|
||||
### Data layer — a **new** `services/bookings` domain
|
||||
The **sibling** of `services/bookingRequests` (b8), **not** a rename — a distinct b9 contract, distinct
|
||||
routes (`/api/v1/bookings/*` + `/api/v1/booking_sessions/*`), distinct shapes. Same `services/{domain}`
|
||||
shape as every other domain:
|
||||
- `types.ts` — derived 1:1 from the b9 swagger (camelCase): `BookingDetailDto`, `BookingSessionDto`
|
||||
(`BookingSessionSummaryDto`), `VisitVerificationDto`, `CareInstructionsDto`, `BookingListItemDto`,
|
||||
`BookingSessionListItemDto`, `CheckInVisitInput`/`CheckOutVisitInput`, the `BookingsApi` seam, the three
|
||||
enum unions (`BookingStatus`/`BookingSessionStatus`/`VisitVerificationStatus`), and pure helpers
|
||||
(`isBookingConfirmedOrBeyond`, `isBookingTerminalBranch`, `bookingTimelineActiveIndex`, `BOOKING_TIMELINE_ORDER`).
|
||||
- `keys.ts` — `bookingDetail(id)`, `bookingSessions(id)` (alias of `bookingDetail` — sessions are embedded),
|
||||
`today(params)`, `sessionEvv(id)`, `careInstructions(id)`, `list(params)`.
|
||||
- `apis/` — real `clientApi` (maps the routes 1:1), `mockApi` (the seeded state machine, **primary**),
|
||||
`serverApi.getBookingDetail` (the RSC-prefetch seam for the real path), and a config-selecting `index`.
|
||||
- `evv/locationProvider.ts` — the **`ILocationProvider`** GPS seam (real `navigator.geolocation` vs a canned
|
||||
mock; `getCurrentPosition()` resolves `null` on denial, never rejects).
|
||||
- `hooks/` (one per file): `useBookingDetail`, `useBookingSessions` (a `select` over the detail query, no
|
||||
second fetch), `useBookingList`, `useTodaySessions`, `useSessionEvv`, `useCareInstructions` (**enabled-gated**),
|
||||
`useCheckInVisit`, `useCheckOutVisit` (both invalidate detail+sessionEvv+today+list on success).
|
||||
|
||||
### Shared composites — `src/components/booking/` (each with a co-located `*.test.tsx`)
|
||||
- `BookingDetailView` — the both-roles smart container (role-conditioned EVV + gated care).
|
||||
- `BookingStatusTimeline` — the server-truth 7-status timeline over the f0 `StepperHeader` + status chip.
|
||||
- `SessionList` → `SessionCard` — per-session Shamsi schedule, status chip, EVV CTA, elapsed/payout.
|
||||
- `EvvStatusBanner` — advisory banner (in-range success / out-of-range warning / no-gps neutral).
|
||||
- `CareInstructionsCard` — the decrypted clinical read (conditions/meds/allergies/instructions/emergency).
|
||||
- `BookingMoneySummary` — gross / commission (کارمزد) / payout, display-only via the money util.
|
||||
- `useEvvController` — GPS-capture + check-in/out orchestration (one instance per surface, per-session busy).
|
||||
- `format.ts` (clock/duration) + `statusKind.ts` (status → StatusChip kind) helpers.
|
||||
|
||||
### Screens
|
||||
- **Customer:** `/bookings` (رزروها list) → `/bookings/[id]` (detail, customer view: timeline + sessions +
|
||||
money; the care record shows the "visible to your nurse only" affordance and the query never fires).
|
||||
- **Nurse:** `/nurse/visits` (ویزیت امروز — today's sessions with inline EVV check-in/out) →
|
||||
`/nurse/visits/[id]` (detail, nurse view: EVV controls + the gated care card).
|
||||
|
||||
### Cross-cutting
|
||||
- i18n `booking` namespace **extended** (both locales, key-synced): `bstatus_*`, `sstatus_*`, `evv_*`
|
||||
(banner variants + CTAs + GPS copy), `care_*` (+ the customer lock copy), `money_*`, `list_*`, dispute note.
|
||||
- 8 new registry icons (`check_in`/`check_out`/`gps`/`schedule`/`clinical`/`medication`/`emergency`/`lock`)
|
||||
and one new token `--bal-secondary-soft` (the نمای پرستار chip / EVV affordance), both schemes.
|
||||
|
||||
## What is now testable, and exactly how
|
||||
|
||||
Run `npm run dev` (mock is primary — no backend needed). The b9 endpoints are also live if you flip the flag.
|
||||
1. **Confirmed booking (customer):** open the رزروها tab → the list shows the two seeded bookings; open one
|
||||
→ **status timeline** at `confirmed`, the **session schedule** (booking #5002 shows exactly **one**
|
||||
session; #5001 shows **3**), and the **money summary** in Toman. Toggle `/en`↔`/fa` → strings + `dir`
|
||||
flip; the timeline reads RTL.
|
||||
2. **Care gate:** open a booking **as the nurse** (`/nurse/visits` → a session → view booking) → the
|
||||
**care-instructions card** is visible (conditions/meds/allergies/instructions/emergency). As the
|
||||
**customer**, the card is absent and the Network tab shows the care request **was never made** (proven by
|
||||
the `BookingDetailView` test too).
|
||||
3. **Nurse check-in:** on `/nurse/visits` (or in the nurse booking detail), tap **«ثبت ورود (EVV)»** →
|
||||
"در حال دریافت موقعیت…" → the **«ورود ثبت شد … موقعیت تایید شد (EVV)»** banner; the session chip →
|
||||
`in_progress`; the timeline → `in_progress`. Set `NEXT_PUBLIC_EVV_MOCK_GPS=out_of_range` → the **advisory**
|
||||
«موقعیت خارج از محدوده (در حال بررسی)» banner and the check-in **still succeeds**. `=denied` → the nurse
|
||||
still checks in (no block; advisory toast + no-gps banner).
|
||||
4. **Nurse check-out:** tap **«ثبت خروج (EVV)»** → the session chip → `completed` with elapsed duration; for
|
||||
the single-visit booking (#5002) the timeline advances to `completed` + the dispute-window note appears —
|
||||
all from the server response, no client-side step jump.
|
||||
5. **Caching:** in React Query Devtools, an EVV mutation invalidates `bookingDetail`/`sessionEvv`/`today`/
|
||||
`list` and the UI re-renders from the refetch; revisiting within `staleTime` does not refetch.
|
||||
6. `npm run check` green · `npm run test:ci` green (195 tests, +22).
|
||||
|
||||
## What is mocked / waiting on a real service
|
||||
|
||||
- **`services/bookings` — mock-primary** (`USE_BOOKINGS_MOCK=true`). A booking only exists after
|
||||
`bookings/convert` runs on a **paid** request, and both upstreams (`bookingRequests` mock, card capture
|
||||
b10) aren't real client-side yet, so a real `bookings/list` returns nothing. The mock seeds confirmed
|
||||
bookings + sessions + care + the EVV state machine. Real `bookingsClientApi` maps the routes 1:1; the swap
|
||||
is one flag (see mocks-registry). `serverApi.getBookingDetail` is ready for the RSC prefetch on the real path.
|
||||
- **`ILocationProvider`** (`NEXT_PUBLIC_EVV_MOCK_GPS`) — GPS capture seam; the real path is
|
||||
`navigator.geolocation`. Server-side address-match math stays behind the backend geocoding seam.
|
||||
- Both are recorded in [mocks-registry.md](./mocks-registry.md).
|
||||
|
||||
## Contract consumed + gaps filed
|
||||
|
||||
- **Consumed:** [bookings-evv.md](../../contracts/domains/bookings-evv.md) + the b9 swagger shapes — types
|
||||
derive 1:1. No shape was guessed.
|
||||
- **Filed:** **REQ-015** — confirm the booking/session/EVV enum **string codes** (bare `string` in swagger)
|
||||
match the client unions, and the **`checkInAddressMatch` tri-state** (`true`/`false`/`null`) so the banner
|
||||
can distinguish an advisory mismatch from "no GPS captured." Low-risk (mock-primary now); worth locking
|
||||
before f9/f13 reuse the shapes.
|
||||
|
||||
## Deliberate design decisions (non-obvious)
|
||||
|
||||
- **Two-stage disclosure is a UI gate, not just a server check.** `useCareInstructions` is `enabled` only for
|
||||
the assigned-nurse view on a `confirmed`+ booking; the customer/unassigned viewer **never fires** the
|
||||
request (a 403/404 is treated as a defect path). The `BookingDetailView` test asserts the customer never
|
||||
calls `getCareInstructions` and the nurse does.
|
||||
- **EVV mismatch/denial is advisory, never a block.** Out-of-range check-in succeeds with a **warning**-tokened
|
||||
banner (never the error token); GPS denial still submits. Check-out is never gated on the match.
|
||||
- **Server-truth timeline + display-only money.** The timeline renders `BookingDetailDto.status` exactly (no
|
||||
client step advance); money is rendered as-sent (no sum/derive/re-split); `payoutEligibleAt` is never
|
||||
recomputed. Sessions are **embedded** in the detail (no standalone list endpoint) — `useBookingSessions`
|
||||
is a `select` over the one detail query, so invalidating `bookingDetail(id)` refreshes both.
|
||||
- **`ILocationProvider`** is the single new client seam; the `NEXT_PUBLIC_EVV_MOCK_GPS` default is `in_range`
|
||||
while mock-primary so the happy path is demoable without a device (real GPS would never fall near the
|
||||
seeded Tehran address).
|
||||
|
||||
## Follow-ups for later phases
|
||||
|
||||
- **f9 (checkout/pay):** the money summary here shows the confirmed **split only**; the **tax (مالیات) line**,
|
||||
escrow notice, and invoice are the checkout surface — b9's `BookingDetailDto` has **no tax field** (flagged;
|
||||
f9 owns it). The C5 accept CTA still lands on `/bookings/checkout?request_id=…` (f7 stub).
|
||||
- **f13 (reviews & records):** the E3 **visit-note authoring** (bottom half) and the full **E2 patient-record
|
||||
viewer** are deferred here; the booking-detail/EVV/care pattern (timeline + sessions + gated care + EVV
|
||||
banner) is the template they extend. The customer-side **care-details authoring** (`submit_care_instructions`)
|
||||
write form is also f13 — f8 only reads the gated record.
|
||||
- **f15 (admin):** the EVV-review queue (mismatch / no-show worklist) is the admin console; f8 raises no
|
||||
alerts client-side (no-show detection is a server job).
|
||||
- **Swap to real:** flip `USE_BOOKINGS_MOCK=false` once `bookings/convert` is reachable client-side (b10
|
||||
card capture) — `bookingsClientApi` + `bookingsServerApi` are wired; no hook/component change.
|
||||
Reference in New Issue
Block a user