cleanup phases 6
This commit is contained in:
hamid
@@ -0,0 +1,108 @@
|
||||
# Frontend Phase 11 — BNPL installment checkout (D1–D5) — report
|
||||
|
||||
**Track:** frontend · **Depends on:** f9 (checkout & payment) + the b12 BNPL contract · **Date:** 2026-07-10
|
||||
**Gate:** `npm run check` green · `npm run test:ci` green (223 tests, +9) · `npm run build` green with
|
||||
`NEXT_PUBLIC_API_URL` set (the build's missing-`.env` prerender failure is pre-existing/environmental and
|
||||
affects unrelated pages).
|
||||
|
||||
## What was built
|
||||
|
||||
The **second exit off C6**: instead of paying the full card amount, the family chooses **اقساط** and is taken
|
||||
through a provider BNPL flow (pick provider → pick plan → credit check → accept schedule → pay down-payment),
|
||||
after which **the booking confirms exactly as the card path** (the provider paid Balinyaar in full). Repayment
|
||||
is then tracked from the **کیفپول (Wallet)** tab.
|
||||
|
||||
### `services/bnpl` (new domain, f0 pattern)
|
||||
- **`types.ts`** — the b12 enums (`BnplStatus`/`BnplEligibilityStatus`/`ProviderCode`), `BnplProvider` +
|
||||
`BnplPlanOption` (per-plan served monthly/down-payment/total IRR strings), `BnplEligibilityResult`,
|
||||
`BnplSchedule` + `BnplInstallmentRow`, `BnplOrderStatus`, `WalletInstallmentPlan` (D5 provider-reported),
|
||||
the `BnplApi` seam, and helpers (`isTerminalBnplStatus`, `isBnplSettlementSuccess`, `installmentStatusKind`).
|
||||
**All money is the IRR digit-string type.**
|
||||
- **`keys.ts`** — `bnplKeys.options/eligibility/schedule/order/walletInstallments`.
|
||||
- **`apis/`** — `clientApi.ts` (real, maps b12 `eligibility`/`initiate`/order-by-id 1:1; options/schedule/
|
||||
wallet/by-request-order are REQ-022/024 gaps on proposed slugs), `mockApi.ts` (**PRIMARY**), selecting
|
||||
`index.ts` (`USE_BNPL_MOCK`).
|
||||
- **`hooks/`** — `useBnplOptions`/`useCheckEligibility`/`useBnplSchedule`/`useIssueBnplToken`/
|
||||
`useAcceptBnplSchedule`(invalidates booking+checkout+wallet)/`useBnplOrder`(bounded backoff poll)/
|
||||
`useWalletInstallments`. `invalidations.ts` reuses the f9 `invalidateAfterPaymentSuccess` + the wallet key.
|
||||
|
||||
### Screens (customer shell, terracotta financial accent = `--bal-secondary`)
|
||||
- **D1 روش پرداخت** (`checkout/bnpl/page.tsx` + `MethodStep.tsx`) — payable amount + full-card option
|
||||
(returns to the f9 card flow) + provider option cards **from `useBnplOptions`** (never hardcoded) + an
|
||||
ownership disclosure at the point of choice. A stateful wizard (`StepperHeader`) drives D1→D4.
|
||||
- **D2 انتخاب طرح** (`PlanStep.tsx`) — single-select `BnplPlanCard` group (term/fee/served monthly/down-payment).
|
||||
- **D3 اعتبارسنجی** (`EligibilityStep.tsx`) — کد ملی (10-digit client format) + prefilled موبایل (session) +
|
||||
**consent-gated** submit → `useCheckEligibility` → approved (credit ceiling) / declined+ceiling-exceeded
|
||||
(declined panel **+ card fall-back**).
|
||||
- **D4 تایید طرح و قرارداد** (`ScheduleStep.tsx`) — served repayment table (`InstallmentScheduleRow`) +
|
||||
the ownership-truth note + a **contract-acceptance-gated** final action → `useIssueBnplToken` handoff.
|
||||
- **Provider handoff** (`bnpl/gateway/page.tsx` harness → `bnpl/return/page.tsx`) — settle (down-payment
|
||||
cleared) → invalidate → **the reused f9 confirmation** (`?method=bnpl` adds «پرداختشده با اقساط»).
|
||||
- **D5 پیگیری اقساط** (`wallet/page.tsx` → `WalletInstallments.tsx`) — provider-reported outstanding
|
||||
balance (terracotta card), next-installment + **early-pay provider hand-off** (opens the provider URL, not
|
||||
a Balinyaar payment), per-installment due list with status chips, and the provider-owned ownership note.
|
||||
|
||||
### Shared composites (tested)
|
||||
- **`BnplPlanCard`** — D2 plan option (terracotta selectable).
|
||||
- **`InstallmentScheduleRow`** — one repayment row, reused by D4 schedule + D5 wallet due list.
|
||||
|
||||
### Wiring / changes
|
||||
- C6 (`checkout/page.tsx`): the «پرداخت اقساطی» button is enabled (`BNPL_ENABLED = true`) and navigates into
|
||||
the wizard with `?request_id=`.
|
||||
- The f9 confirmation renders the installments line on `?method=bnpl` (no parallel confirmation built).
|
||||
- New `ROUTES.CHECKOUT_BNPL[_GATEWAY|_RETURN]`, the `installments` AppIcon, and the `bnpl` i18n namespace
|
||||
(87 keys, both locales in sync, RTL-first, ICU-`number` params for Persian digits).
|
||||
|
||||
## What is now testable, and exactly how
|
||||
|
||||
Run `npm run dev`, sign in as a customer, reach a **confirmed** booking's checkout (C6) via the f9 flow (the
|
||||
seam mock closes the loop):
|
||||
1. **C6 → اقساط → D1**: payable amount + دیجیپی/اسنپپی/اقساط بالینیار (terracotta). Pick → «ادامه با …».
|
||||
2. **D2**: plans (۳/۶/۱۲ ماهه or ۴ قسط) with monthly + down-payment; amounts render in Toman via the money util.
|
||||
3. **D3**: enter کد ملی, tick consent (submit stays disabled until consent) → **mock approves** with a ceiling.
|
||||
**Declined path:** a national ID ending in `0` → `not_eligible` (declined panel + card fall-back);
|
||||
an order above the ceiling → `ceiling_exceeded`.
|
||||
4. **D4**: پیشپرداخت (امروز) + قسط rows with **Shamsi** due dates; accept the contract (final action disabled
|
||||
until ticked) → handoff harness → **the booking confirms**, landing on the f9 confirmation marked اقساطی.
|
||||
5. **کیفپول (Wallet) → D5**: provider-reported outstanding balance + next due + per-installment due list
|
||||
(پرداختشده / سررسید نزدیک / آینده), the ownership note, and an **early-pay hand-off** (opens the provider).
|
||||
6. Switch to `en` → all BNPL strings translate, RTL⇄LTR flips; dark mode intact.
|
||||
|
||||
## What is mocked / waiting on a real service
|
||||
|
||||
`services/bnpl` is **mock-primary** (`USE_BNPL_MOCK = true`) — see the `BnplApi` row in
|
||||
[`mocks-registry.md`](./mocks-registry.md). The mock reads the frozen request gross from the f7 store, plays
|
||||
the provider (eligibility verdict, plan math, token/redirect), and on settle **reuses the f9 conversion
|
||||
bridge** (`mockInsertConvertedBooking` + `mockMarkBookingRequestConverted`) — a settled BNPL order is a card
|
||||
payment net-of-fee — then seeds a provider-reported Wallet plan. All money is served IRR digit-strings (the
|
||||
mock computes plan/schedule with integer BigInt math; components only format). Swap is a one-line flip once
|
||||
the upstream is real and the REQs land.
|
||||
|
||||
## Contracts consumed + gaps filed
|
||||
|
||||
Consumed [`dev/contracts/domains/bnpl.md`](../../contracts/domains/bnpl.md) (b12) for all types/routes.
|
||||
Filed to [`for-backend.md`](../frontend/requests/for-backend.md):
|
||||
- **REQ-022** — provider/plan options (D1/D2) + repayment schedule (D4); the contract serves neither and
|
||||
explicitly does not model the repayment schedule. Also: add `balinyaar` to the `provider_code` enum.
|
||||
- **REQ-023** — BNPL eligibility should accept the D3 KYC inputs (national ID / mobile / consent).
|
||||
- **REQ-024** — provider-reported Wallet installment status (D5), a customer-readable `bookingId` on the
|
||||
settled order, and a by-request order lookup for the return poll (`GET checkout_bnpl/{id}` is order-id-keyed).
|
||||
|
||||
## Adversarial review (multi-agent workflow)
|
||||
|
||||
Ran a 6-dimension review (money · ownership · contract · reuse/caching · gates/flow · i18n/RTL/theme) with an
|
||||
adversarial verify pass. Of the raised findings, **5 were confirmed and all fixed**; the rest were refuted
|
||||
(mock-allowed, non-reachable, or f9-parity conventions):
|
||||
1. Return-page **window-expired** branch had a mislabeled CTA + wrong copy → now reuses the f9
|
||||
`window_expired_*` + `back_to_request` keys (label matches the destination).
|
||||
2. Real `getBnplOrder` keyed by request id vs the contract's order-id path → the settle-on-return now reads
|
||||
the order **by its own id** (contract-correct); the by-request poll is honestly flagged as a REQ-024 gap.
|
||||
3. Return-page order poll fired one needless fetch on immediate success → gated on the late-settle case only.
|
||||
4. Dead i18n keys (`col_*`) deleted; the strongest ownership disclosure (`ownership_note`) is now rendered at D1.
|
||||
5. D1 provider-glyph text was near-illegible in dark mode → switched to the `--bal-secondary-dark` text token.
|
||||
|
||||
## Follow-ups for later phases
|
||||
- **f15 admin BNPL** — the admin revert/cancel console (b12 `admin_bnpl/*`) is out of scope here.
|
||||
- **BNPL refund/revert** — the customer cancellation + BNPL revert ETA surface is **f10** (not duplicated here).
|
||||
- When REQ-022/023/024 land, flip `USE_BNPL_MOCK = false` (one line); if `f12` nurse-earnings Wallet content
|
||||
lands, it sits beside the self-contained D5 section under `/wallet`.
|
||||
Reference in New Issue
Block a user