cleanup phases 6
This commit is contained in:
hamid
@@ -0,0 +1,286 @@
|
||||
# UI Phase 3 — Auth & first-run
|
||||
|
||||
> **Mission:** the login screen is the product's only front door — the middleware redirects every
|
||||
> unauthenticated hit to `/login` — and today it is a bare starter card fronted by a cartoon Twemoji
|
||||
> pencil, with no consent line, no trust content, and an OTP flow that never offers SMS autofill in an
|
||||
> OTP-first market. This phase rebuilds login → OTP → select-role → onboarding as a branded,
|
||||
> trust-forward, Persian-native entry: a login hero that states what Balinyaar verifies and escrows,
|
||||
> OTP ergonomics at Snapp/Digikala parity (WebOTP + `one-time-code`), terms/privacy consent, an
|
||||
> illustrated role fork, a chrome-free focused onboarding journey, and a `returnUrl` so deep links
|
||||
> survive login.
|
||||
>
|
||||
> **Track:** frontend · **Depends on:** [Phases 0–2](ui-phase-2-shells-and-navigation.md) ·
|
||||
> **Unlocks:** the first impression finally sells trust
|
||||
> **Before you start, read [../../phases/_shared/agent-operating-rules.md](../../phases/_shared/agent-operating-rules.md)
|
||||
> and invoke the frontend-designer skill — both are mandatory.**
|
||||
|
||||
## 1. Context — where this sits
|
||||
|
||||
Balinyaar is a trust-first home-nursing marketplace; there is no public landing page (that is
|
||||
[Phase 13](ui-phase-13-public-front-door.md)), so **login IS the product's first impression** — and in a
|
||||
phone-OTP market, login is also signup. Mechanically the flow is strong (see the audit's keep-list); the
|
||||
problems are presentation, ergonomics, and a handful of genuine defects, all verified in code:
|
||||
|
||||
1. **The login card carries zero trust evidence.** `client/src/components/auth/AuthCard.tsx:12-31` is an
|
||||
outlined `Paper` with a `BrandMark` and nothing else — no illustration, no mention of nurse
|
||||
verification or escrowed payment, on a product whose entire pitch is trust.
|
||||
2. **No OTP autofill.** A repo-wide grep for `autoComplete`, `one-time-code`, and `OTPCredential` over
|
||||
`client/src` returns **zero hits** — `OtpInput.tsx:121-128` sets `inputMode`/`maxLength`/`aria-label`
|
||||
but never `autoComplete`, and there is no WebOTP wiring. Every login feels worse than the apps users
|
||||
compare against.
|
||||
3. **No consent, no terms, no privacy.** `PhoneStep.tsx:56-102` renders title/field/CTA/role-switch only;
|
||||
`PUBLIC_PATHS = [ROUTES.LOGIN]` (`client/src/constants/routes.ts:169`) — no `/terms` or `/privacy`
|
||||
route exists anywhere. Entering a phone number creates an account with no disclosed terms.
|
||||
4. **The 429 state is the least visible one.** `PhoneStep.tsx:76` renders `rate_limited` as grey
|
||||
`helperText` while `error={invalid}` stays false — the one state where the user is blocked gets no
|
||||
error styling.
|
||||
5. **Bidi + digit defects on the OTP screen.** `OtpStep.tsx:100` interpolates the masked phone
|
||||
(`0912•••1234`) into an RTL sentence with no bidi isolation (the classic digits-around-neutrals
|
||||
reversal); `formatMmSs` (`OtpStep.tsx:24-28`) renders Latin `01:23` in a Persian sentence; backspace on
|
||||
an empty box (`OtpInput.tsx:89-93`) moves focus but never clears the previous digit.
|
||||
6. **Select-role is semantically confusing.** `SelectRole.tsx:21-24` gives the nurse option a **house**
|
||||
icon (`{ role: 'nurse', icon: 'home' }`); selection feedback is border-color only
|
||||
(`SelectRole.tsx:74-83`) — color is the sole signal.
|
||||
7. **Onboarding renders inside the full app shell.** `(customer)/onboarding/page.tsx` sits in the
|
||||
`(customer)` route group, so the A3→A4 wizard shows the 5-tab BottomBar, support icon, and bell — a
|
||||
user mid-setup can tab away. All four relation options share the same `'account'` icon
|
||||
(`onboarding/page.tsx:31`), and there is no welcome moment.
|
||||
8. **Deep links die at login.** `middleware.ts:29` redirects to `/{locale}/login` discarding the attempted
|
||||
path — an SMS booking link or shared nurse profile dumps the user on their role home after login.
|
||||
|
||||
**What already exists (do not rebuild):**
|
||||
|
||||
- **The real brand mark and de-startered theme** — [Phase 0](ui-phase-0-design-language.md) owns
|
||||
`theme/`, the logotype replacing the Twemoji pencil, the icon registry, and `AppButton` (including
|
||||
killing its `margin: 1` starter default). Consume the mark via `BrandMark`/`ICONS.logo`; do not design
|
||||
a second one.
|
||||
- **Shared primitives** — [Phase 1](ui-phase-1-primitives-and-states.md) owns `formatNumber` (the
|
||||
locale-digit helper), `StepperHeader`, and the state views. Consume them.
|
||||
- **The de-startered public shell** — [Phase 2](ui-phase-2-shells-and-navigation.md) owns `layout/`,
|
||||
including retiring `PublicLayout`'s "Unauthorized - Balinyaar" chrome. This phase styles the **content**
|
||||
of the auth routes, not the shell.
|
||||
- **The auth machinery** — `LoginFlow`/`PhoneStep`/`OtpStep`/`RoleRouter`/`AuthSplash`/`RoleGuard`/
|
||||
`SelectRole`/`useCountdown`, `services/auth` (real backend, `USE_AUTH_MOCK = false`), the middleware
|
||||
auth gate, and the resolved-vs-pending role hydration from refinement phase 2. This phase redesigns
|
||||
surfaces and adds ergonomics; the session/cookie/refresh/hydration logic is untouched.
|
||||
|
||||
## 2. Required reading (do this first)
|
||||
|
||||
- [audit/auth-first-run.md](audit/auth-first-run.md) — the full evidence, opportunities, and the
|
||||
**keep-list** this phase must not regress.
|
||||
- The auth surface: `client/src/components/auth/` (`LoginFlow.tsx`, `AuthCard.tsx`, `BrandMark.tsx`,
|
||||
`PhoneStep.tsx`, `OtpStep.tsx`, `SelectRole.tsx`, `RoleRouter.tsx`, `constants.ts`),
|
||||
`client/src/components/OtpInput/OtpInput.tsx`, `client/src/components/PhoneNumberField/`,
|
||||
`client/src/services/auth/routing.ts` (`resolveRoleDestination` — pure, unit-tested).
|
||||
- First-run: `client/src/app/[locale]/(private-routes)/(customer)/onboarding/page.tsx`,
|
||||
`client/src/components/RelationSelect/`, `client/src/components/StepperHeader/`, and the home redirect
|
||||
gate at `(customer)/page.tsx:60-68`.
|
||||
- Routing: `client/middleware.ts`, `client/src/constants/routes.ts` (`ROUTES`, `PUBLIC_PATHS`).
|
||||
- The design contract: [.claude/skills/frontend-designer/SKILL.md](../../../.claude/skills/frontend-designer/SKILL.md)
|
||||
(invoke the skill) + `client/CLAUDE.md` Golden rules and the auth-cookies section (what you must not touch).
|
||||
- Product truth for the trust copy: [product/overview/platform-summary.md](../../../product/overview/platform-summary.md)
|
||||
(the four ground truths), [product/business/02-nurse-verification.md](../../../product/business/02-nurse-verification.md)
|
||||
and [product/business/08-payments-and-escrow.md](../../../product/business/08-payments-and-escrow.md) —
|
||||
the trust bullets must state facts the platform actually implements, nothing aspirational.
|
||||
|
||||
## 3. Scope — build this
|
||||
|
||||
### 3.1 Login hero — a branded, trust-forward front door
|
||||
|
||||
Redesign `LoginFlow`/`AuthCard` as a branded moment on the cream backdrop (`background.default` /
|
||||
`--bal-bg-default`): the Phase-0 logotype, the tagline «مراقبت مطمئن در خانه», and **2–3 trust bullets**
|
||||
beneath the card stating what the product actually does — «پرستاران تاییدشده» (license + identity
|
||||
verification), «پرداخت امن امانی» (escrow until confirmed check-out), «پشتیبانی» — each with a registry
|
||||
icon. Add a calm illustration treatment: **composed CSS/SVG shapes in brand tokens are fine; no stock
|
||||
photos, no raster illustrations.** Keep the card readable at 320px and let the hero breathe on desktop.
|
||||
Keep the single login stack parameterized by `intendedRole` (`LoginFlow.tsx:22-24`, seeded from
|
||||
`?role=nurse`) and the A1/B1 switch link — the nurse variant may re-tint copy, never fork the tree.
|
||||
Keep the `' '` helperText placeholder that prevents layout jump.
|
||||
|
||||
### 3.2 OTP ergonomics — autofill, correction, and Persian digits
|
||||
|
||||
- **`autoComplete="one-time-code"`** on the `OtpInput` digit inputs (`slotProps.htmlInput`), so
|
||||
iOS/Android offer the SMS code as a keyboard suggestion.
|
||||
- **WebOTP:** feature-detect `'OTPCredential' in window`, call
|
||||
`navigator.credentials.get({ otp: { transport: ['sms'] }, signal })` with an `AbortController`
|
||||
(abort on unmount and on manual completion), distribute the received code through the existing
|
||||
`onChange`/`onComplete` path so the existing auto-verify fires. Unsupported browsers silently fall back
|
||||
to manual entry — no errors, no UI difference.
|
||||
- **File REQ-039** (see §4): WebOTP and native suggestion only work when the SMS **ends with the
|
||||
origin-bound line `@<domain> #<code>`** — the SMS template is server/Kavenegar-side.
|
||||
- **Backspace-on-empty clears the previous box:** in `OtpInput.tsx:89-93`, when backspace is pressed on
|
||||
an empty box, clear `chars[index-1]` *and* move focus — one keypress per digit to erase.
|
||||
- **Persian-digit countdown:** replace `formatMmSs`'s raw `String`/`padStart` (`OtpStep.tsx:24-28`) with
|
||||
the Phase-1 `formatNumber` helper so `/fa` renders ۰۱:۲۳ and `/en` renders 01:23. Keep the clock an
|
||||
LTR run inside the sentence.
|
||||
- **429 as a real error:** in `PhoneStep.tsx:76`, the rate-limited state must set `error` on the field
|
||||
(e.g. `error={invalid || rateLimited}`) so the message renders in error styling, not grey helperText.
|
||||
- **Bidi-isolate the masked phone echo:** wrap `maskIranMobile(phone)` in `OtpStep.tsx:100` in a
|
||||
`<bdi>`/`dir="ltr"` inline element (via `t.rich` or splitting the sentence) so `0912•••1234` never
|
||||
reorders inside the RTL sentence. Keep the masking itself.
|
||||
|
||||
### 3.3 Consent + legal pages
|
||||
|
||||
- Add the standard implicit-consent line under the login CTA in `PhoneStep`:
|
||||
«با ورود، [شرایط استفاده] و [حریم خصوصی] را میپذیرید» — the bracketed terms are `AppLink`s.
|
||||
- Create `/terms` and `/privacy` under `(public-routes)` (`terms/page.tsx`, `privacy/page.tsx`):
|
||||
readable, Typography-composed legal skeletons in **both locales**, clearly flagged in the phase report
|
||||
and a code comment as **draft copy requiring human/legal review before launch**. Add
|
||||
`ROUTES.TERMS`/`ROUTES.PRIVACY` and append both to `PUBLIC_PATHS` (`routes.ts:169`) so the middleware
|
||||
lets them through logged-out.
|
||||
|
||||
### 3.4 Select-role — an illustrated two-card fork
|
||||
|
||||
Replace the generic icons (`SelectRole.tsx:21-24` — `account` for customer, a **house** for nurse) with
|
||||
an illustrated two-card fork: *family receiving care* vs *nurse professional*, using the same CSS/SVG
|
||||
illustration treatment as 3.1. Selected state = `--bal-primary-soft` fill **plus a check glyph** —
|
||||
color must not be the only signal. Add a reassurance line that the other role can be added later
|
||||
(dual-role sessions are already supported). **Keep the radio a11y semantics exactly**: `role="radio"`,
|
||||
`aria-checked`, `tabIndex`, Enter/Space handlers (`SelectRole.tsx:64-72`). Admin is never offered here.
|
||||
If a check/role icon is missing from the registry, extend `AppIcon/config.ts` minimally and note it in
|
||||
the report (Phase 0 owns the file; later phases extend, never fork).
|
||||
|
||||
### 3.5 Onboarding as a focused journey
|
||||
|
||||
- **Move the A3→A4 wizard out of the customer shell chrome.** Today `onboarding/page.tsx` renders inside
|
||||
`CustomerLayout` (5-tab BottomBar + bell). Relocate it to a sibling route group, e.g.
|
||||
`(private-routes)/(customer-focused)/onboarding/`, whose layout keeps **`RoleGuard(expected=customer)`**
|
||||
(non-negotiable) but renders a chrome-free focused shell in the spirit of `AuthCard` — logo, progress,
|
||||
content, nothing to tab away to. Route groups don't change the URL, so `/onboarding`, the
|
||||
`ROUTES.ONBOARDING` constant, and the home redirect gate (`(customer)/page.tsx:63`) keep working
|
||||
untouched.
|
||||
- **A one-screen welcome moment** before the relation step: «خوش آمدید — بگویید مراقبت برای چه کسی
|
||||
است؟»-style framing with the brand mark, one CTA into the wizard.
|
||||
- **Distinct relation iconography:** the four options (`onboarding/page.tsx:31` — parent/spouse/child/
|
||||
self, currently all `'account'`) each get a distinct registry icon so the first product interaction
|
||||
isn't four identical cards.
|
||||
- **Progress via `StepperHeader`** (welcome doesn't count as a step; relation → patient does).
|
||||
- **Keep** the relation pre-shaping the patient form (relation field hidden on A4) and the settled-list
|
||||
redirect gate exactly as they are.
|
||||
- (DEFERRED → [Phase 4](ui-phase-4-customer-storefront.md) + product decision) a «بعداً تکمیل میکنم»
|
||||
skip path with a browse-capable home: it changes the zero-patient home gate, which is storefront
|
||||
territory. The forced redirect stays as-is in this phase.
|
||||
- (DEFERRED → [Phase 12](ui-phase-12-copy-motion-and-polish.md)) OTP delivery fallback escalation
|
||||
(voice-call OTP / support link after failed resend cycles) — needs a second delivery channel that
|
||||
doesn't exist server-side.
|
||||
|
||||
### 3.6 returnUrl — deep links survive login
|
||||
|
||||
- `middleware.ts:29`: when redirecting an unauthenticated hit to login, append the attempted
|
||||
locale-stripped path + query as `?next=<encoded>` — e.g.
|
||||
`/fa/bookings/42` → `/fa/login?next=%2Fbookings%2F42`.
|
||||
- Login honors it: `LoginFlow` reads `next` and passes it to `RoleRouter`; add a **pure, unit-tested**
|
||||
helper beside `resolveRoleDestination` in `services/auth/routing.ts` (e.g.
|
||||
`resolvePostLoginDestination(me, intendedRole, next)`) that returns `next` only when it is (a) a
|
||||
same-origin **relative** path — starts with `/`, not `//`, no scheme — and (b) permitted by the
|
||||
resolved roles (a customer's `next=/nurse/...` falls through). Anything else falls back to
|
||||
`resolveRoleDestination` — which stays the single "which app" source of truth.
|
||||
- Touch `middleware.ts` **surgically**: the token check, locale detection, header propagation, and
|
||||
next-intl handling are load-bearing; the auth gate semantics must not change.
|
||||
|
||||
### 3.7 PhoneNumberField autofill
|
||||
|
||||
Add `autoComplete="tel"` to the `PhoneNumberField` input so browsers/keyboards offer the user's own
|
||||
number. Keep the LTR forcing and digit normalization untouched.
|
||||
|
||||
## 4. Mocks & seams in this phase
|
||||
|
||||
**None introduced.** Auth is real (`USE_AUTH_MOCK = false` since refinement phase 4); every deliverable
|
||||
here is presentation, ergonomics, or client routing. Do not flip any mock flag.
|
||||
|
||||
**REQ posture:** backend gaps become REQ entries appended to
|
||||
[../../shared-working-context/frontend/requests/for-backend.md](../../shared-working-context/frontend/requests/for-backend.md)
|
||||
— REQ-001…038 are taken; number onward. This phase files exactly one:
|
||||
|
||||
- **REQ-039 — WebOTP-conformant OTP SMS template.** The OTP SMS must end with the origin-bound last line
|
||||
`@<domain> #<code>` (the [WebOTP](https://web.dev/articles/web-otp) / origin-bound one-time-code
|
||||
convention) so Chrome's WebOTP API and the iOS/Android keyboard suggestion can auto-read the code. This
|
||||
is a server/SMS-template change (the Kavenegar adapter from refinement phase 8); zero API-shape impact.
|
||||
The client work in 3.2 ships regardless and degrades to manual entry until this lands.
|
||||
|
||||
## 5. Critical rules you must not get wrong
|
||||
|
||||
- **Do not touch the auth/session machinery.** `services/auth` session logic, `persistAuthTokens`/
|
||||
`clearAuthTokens`, the fetch-layer silent refresh, `useLogout`, cookie handling, and the
|
||||
`RoleGuard`/`useRoleHydration` resolved-vs-pending behavior were hardened in refinement phases 2 and 5.
|
||||
This phase restyles screens and adds a routing helper — nothing else.
|
||||
- **The no-wrong-shell-flash behavior stays.** `RoleRouter` + branded `AuthSplash` while `/me` is in
|
||||
flight, `AuthAccountError` on failure, `RoleGuard` redirect-with-toast on mismatch. The relocated
|
||||
onboarding layout must keep `RoleGuard(expected=customer)`.
|
||||
- **OTP mechanics that already work stay:** paste distribution across boxes, Persian/Arabic→ASCII digit
|
||||
normalization, `dir="ltr"` on the OTP group and phone field, auto-verify on the 5th digit, the
|
||||
server-driven resend cooldown (`resendAvailableInSeconds` seeds `useCountdown`), resend staying
|
||||
available during lockout as the escape hatch, and the distinct wrong/expired/locked/429 states.
|
||||
- **`next` must never become an open redirect.** Only same-origin relative paths, validated in the pure
|
||||
helper (with unit tests covering `//evil.com`, `https:` schemes, and role-forbidden paths).
|
||||
- **One login stack.** `intendedRole` parameterizes; it never forks customer/nurse login trees.
|
||||
- **Admin roles are never offered** in SelectRole; the middleware stays a UX gate, not a security boundary.
|
||||
- **Design-contract non-negotiables:** every new string in **both** `messages/en.json` and
|
||||
`messages/fa.json`; tokens/palette keys, never hexes; RTL-safe logical props (verify `/fa` first);
|
||||
both color schemes; MUI v9 API only; illustrations are CSS/SVG in tokens — no stock photos; shared
|
||||
components (`OtpInput`, `PhoneNumberField`, `RelationSelect`, anything new in `components/`) keep/get
|
||||
co-located `.test.tsx`; `clientFetch`/cookie rules untouched.
|
||||
|
||||
## 6. Definition of Done
|
||||
|
||||
On top of the shared [definition-of-done.md](../../phases/_shared/definition-of-done.md):
|
||||
|
||||
- [ ] `npm run check` green; `npm run test:ci` green for every touched shared component
|
||||
(`OtpInput`, `PhoneNumberField`, `RelationSelect`, the new routing helper's unit tests, and any
|
||||
new shared component); `en.json`/`fa.json` in sync.
|
||||
- [ ] Visual verification on all four axes — `/fa` + `/en` × light + dark — and mobile (360px) +
|
||||
desktop for login, OTP, select-role, terms/privacy, and onboarding.
|
||||
- [ ] The login screen shows the brand mark, tagline, trust bullets, and consent line; no starter
|
||||
chrome, no pencil, no hard-coded English anywhere in the flow.
|
||||
- [ ] OTP inputs carry `autoComplete="one-time-code"`; WebOTP auto-fills on a supporting
|
||||
Android/Chrome device (or is verified degrading silently elsewhere); backspace clears the
|
||||
previous digit in one keypress.
|
||||
- [ ] The resend countdown renders ۰۱:۲۳ on `/fa` and 01:23 on `/en`; the masked phone echo renders
|
||||
un-scrambled inside the Persian sentence.
|
||||
- [ ] A 429 on request-OTP renders with error styling on the field, not grey helper text.
|
||||
- [ ] `/terms` and `/privacy` load logged-out in both locales; the consent line links to them.
|
||||
- [ ] Select-role shows the illustrated fork; the selected card has a soft fill + check glyph; keyboard
|
||||
selection (Tab, Enter/Space) still works.
|
||||
- [ ] `/onboarding` renders chrome-free (no BottomBar/bell), opens with the welcome screen, shows four
|
||||
visually distinct relation cards, and still creates the patient and lands on Home.
|
||||
- [ ] Visiting `/fa/bookings` logged-out → login → after OTP, landing back on `/fa/bookings`;
|
||||
`?next=//evil.com` and `?next=https://evil.com` are ignored (role-home fallback).
|
||||
- [ ] REQ-039 appended to the tracker.
|
||||
|
||||
## 7. How to test (what a human can verify after this phase)
|
||||
|
||||
1. Open `/fa` logged-out → redirected to `/fa/login`. The screen is a branded hero: logotype, tagline,
|
||||
trust bullets, consent line with working «شرایط استفاده»/«حریم خصوصی» links. Toggle dark mode and
|
||||
`/en` — everything tracks.
|
||||
2. Enter a phone (demo seeds `0912000000x`), request the code. On the OTP screen the masked number reads
|
||||
`0912•••…` correctly inside the Persian sentence; the countdown ticks in Persian digits on `/fa`.
|
||||
3. Type a wrong digit mid-code, press backspace twice — each press erases one digit. Paste a 5-digit
|
||||
code — boxes fill and verify fires automatically (unchanged).
|
||||
4. Spam request-OTP until a 429 → the message renders in error styling on the field.
|
||||
5. On an Android/Chrome device with a WebOTP-formatted SMS (post REQ-039): the code fills without
|
||||
typing. On desktop Firefox/Safari: no errors in console; manual entry works.
|
||||
6. Log in with a fresh phone → `/select-role` shows two illustrated cards; select the nurse card —
|
||||
soft fill + check glyph appear; the reassurance line about adding the other role later is present;
|
||||
arrow/Enter keyboard selection works.
|
||||
7. As a fresh customer with zero patients → land on `/onboarding`: welcome screen → relation step with
|
||||
four distinct icons → patient form (relation pre-filled and hidden) → save → Home. During the wizard
|
||||
there is no bottom nav or bell to tab away to.
|
||||
8. Logged-out, open `/fa/bookings` → login carries `?next=%2Fbookings` → after OTP you land on
|
||||
`/fa/bookings`. Repeat with `?next=https://evil.com` manually — you land on your role home.
|
||||
9. Sanity: a seeded nurse still lands on `/nurse`, an admin on `/admin` (RoleRouter untouched); `?role=nurse`
|
||||
still pre-selects the nurse copy and carries into select-role.
|
||||
|
||||
## 8. Hand off & document (close the phase)
|
||||
|
||||
- Update `client/CLAUDE.md` **Project Structure**: the new `(public-routes)` `terms`/`privacy` pages, the
|
||||
relocated onboarding route group and its focused layout, any new/renamed auth components, and the new
|
||||
routing helper — in the same change.
|
||||
- Append **REQ-039** to
|
||||
[for-backend.md](../../shared-working-context/frontend/requests/for-backend.md) as specified in §4.
|
||||
- Write the frontend report at `dev/shared-working-context/reports/ui-phase-3-report.md`: what shipped
|
||||
per scope item, the REQ filed, the **draft-legal-copy flag** for `/terms`/`/privacy` (human/legal
|
||||
review required before launch), any icon-registry additions made under the Phase-0 ownership rule, and
|
||||
the four-axes verification evidence.
|
||||
- Save a memory note per operating-rules §8: auth/first-run redesigned (login hero + consent, WebOTP +
|
||||
OTP ergonomics, illustrated select-role, focused onboarding, validated `returnUrl`), REQ-039 pending
|
||||
server-side SMS template, skip-onboarding deliberately deferred to Phase 4.
|
||||
Reference in New Issue
Block a user