cleanup phases 6
This commit is contained in:
hamid
@@ -0,0 +1,117 @@
|
||||
# Frontend Phase 4 — Catalog browse (Home A5) & nurse service builder (B7) — Report (2026-07-05)
|
||||
|
||||
Lights up the two faces of the configurable catalog: the **customer Home (A5)** front door and the
|
||||
**nurse "add a service" builder + offerings list (B7 services half)**, over a new cached `services/catalog`
|
||||
domain. Consumes the b5 `catalog` contract. Unlocks search & discovery (f6).
|
||||
|
||||
## What was built
|
||||
|
||||
### `services/catalog` domain (`client/src/services/catalog/`)
|
||||
- **`types.ts`** — DTOs mirrored from [`catalog.md`](../../contracts/domains/catalog.md) (**camelCase** wire):
|
||||
`ServiceCategory`, `ServiceOptionGroup` (`serviceCategoryId: number|null` = cross-category, `isRequired`),
|
||||
`ServiceOptionValue`, `NurseServiceVariant` (`price` = **IRR digit-string**, `priceUnit`, `sessionCount`,
|
||||
`options[]`), `CreateVariantInput`/`UpdateVariantInput`, the `CatalogApi` seam, and helpers
|
||||
`isGroupApplicable` / `optionSetSignature` (the duplicate-listing signature). `PriceUnit` +the `PRICE_UNITS`
|
||||
array are the **only** closed enum — categories/groups/values are data-driven.
|
||||
- **`keys.ts`** — `catalogKeys`: `categories()`, `categoryOptionGroups(id)`, `myVariants(params)` /
|
||||
`myVariantsLists()` (invalidation prefix), `variant(id)`.
|
||||
- **`constants.ts`** — `USE_CATALOG_MOCK` (default `true`); `CATALOG_REFERENCE_STALE_TIME = Infinity` +
|
||||
`CATALOG_REFERENCE_GC_TIME` (reference data cached session-long, like geography); `MY_VARIANTS_STALE_TIME`;
|
||||
page sizes.
|
||||
- **`apis/`** — `clientApi.ts` (real, action-style routes, camelCase bodies, `pageSize` pagination),
|
||||
`mockApi.ts` + `seed.ts` (in-memory, behind the seam), `index.ts` (config-selected seam).
|
||||
- **`hooks/`** (one per file) — `useServiceCategories`, `useCategoryOptionGroups` (cached reference data);
|
||||
`useMyVariants` (paginated, auth-gated, self-scoped); `useCreateVariant`, `useUpdateVariant`
|
||||
(`setQueryData` the row + invalidate), `useSetVariantActive` (deactivate/reactivate). `index.ts` barrels hooks.
|
||||
- **`names.ts`** — `pickCatalogName(row, locale)` locale-label helper (fa primary).
|
||||
|
||||
### Shared components (`client/src/components/`, each with a co-located `*.test.tsx`)
|
||||
- **`CategoryTile`** — data-driven, tappable category tile (icon disc + localised label; `selected` state for
|
||||
the builder; robust `iconKey`→icon fallback to a generic `category` icon).
|
||||
- **`PriceDisplay`** — renders `{Toman} {unit}` via the f0 money util + an i18n unit label off `price_unit`, and
|
||||
the **unit-aware estimated total** (`price × sessionCount`, integer-safe) only when a duration is present.
|
||||
- **`VariantCard`** — a nurse offering: `display_name`, `PriceDisplay`, active/deactivated distinction (dimmed +
|
||||
neutral chip + "can't be booked" hint), Edit + Deactivate/Reactivate actions — **no delete affordance**.
|
||||
|
||||
### Money util (`client/src/utils/money.ts`)
|
||||
- `tomanToRial(value)` — the sanctioned **Toman→IRR digit-string** conversion at the field boundary.
|
||||
- `multiplyIrr(value, count)` — integer-safe `price × count` for the estimated total (never from price alone).
|
||||
- Both unit-tested (`money.test.ts`).
|
||||
|
||||
### Screens
|
||||
- **Customer Home (A5)** — `app/[locale]/(private-routes)/(customer)/page.tsx` (rewritten): greeting + avatar
|
||||
(`useMe` firstName / initial), **search bar** (navigates toward `/search?q=…`; execution deferred to f6),
|
||||
**data-driven category grid** (`useServiceCategories`; loading skeletons / empty / error+retry; tiles carry
|
||||
`service_category_id` → `/search?category_id=`), the complete-patient-record nudge (reuses the **cached f2
|
||||
`usePatients`** — no new fetch), and the preserved first-login onboarding gate.
|
||||
- **`/search`** — deferred `PlaceholderScreen` stub so the Home CTAs don't dead-end (echoes the q/category).
|
||||
- **Nurse Services & prices (B7)** — `app/[locale]/(private-routes)/nurse/services/` (new sidebar tab). `page.tsx`
|
||||
switches between `MyServicesList` (offerings — active/inactive, edit, soft-deactivate w/ confirm, reactivate,
|
||||
empty/skeleton) and `VariantBuilder` (create/edit).
|
||||
|
||||
### Builder (`VariantBuilder.tsx`)
|
||||
- **Create** = 3-step stepper (reuses the f0 `StepperHeader`): category (CategoryTile grid) → options
|
||||
(single-select `ToggleButtonGroup` per group; required badge; **blocks advancing until every required group is
|
||||
answered**, cross-category groups included) → price+unit+duration. Price entered in **Toman** → submitted as an
|
||||
**IRR digit-string** (`tomanToRial`, no float on the path); **live unit-aware estimated total** via
|
||||
`PriceDisplay`; editable auto-generated `display_name`. The duplicate-listing **`409`** shows a friendly inline
|
||||
warning. **Edit** locks the category + option-set and edits only price/unit/duration/display.
|
||||
|
||||
### Wiring
|
||||
- i18n: `catalog` / `services` / `search` namespaces + `home` additions + `nav.services` (both locales, in sync,
|
||||
313 keys). Icons: `services`, `category`, `elderly`, `post_surgery`, `infant`, `chronic`, `companionship`.
|
||||
Routes: `SEARCH`, `NURSE_SERVICES`. Nurse sidebar gains **Services**.
|
||||
|
||||
## What is now testable (and exactly how)
|
||||
|
||||
Run `npm run dev` (mock is on by default — no backend needed). Follow the phase §7 steps:
|
||||
1. **Home** — sign in as a customer → greeting + avatar, search bar, and the **category grid** (5 seeded
|
||||
categories ordered by `sortOrder`); the patient nudge shows/hides off the cached patient state (React Query
|
||||
Devtools: the `patients` query is **reused**, not refetched).
|
||||
2. **Locale + RTL** — toggle `fa`↔`en`: labels translate, `dir` flips, tiles/grid mirror; Persian unit labels
|
||||
(ساعتی/روزانه/شبانهروزی) read correctly.
|
||||
3. **Build a variant** — sign in as a nurse → `/nurse/services` → `+ افزودن خدمت` → pick **مراقبت از سالمند**;
|
||||
in options, try **Next** without answering **نوع شیفت** (required) → blocked, the required badge turns red;
|
||||
answer it → Next; enter a **Toman** price + unit (ساعتی) + a duration → the **estimated total** updates from
|
||||
`price × duration`; edit the auto `display_name`; submit → the card appears (`… تومان ساعتی`).
|
||||
4. **Duplicate** — create a second variant with the **same category + same option-set** → the friendly
|
||||
`409` duplicate warning shows inline; no crash / no generic toast.
|
||||
5. **Edit + deactivate** — edit a variant's price/name → the list reflects it without a full refetch (Devtools:
|
||||
`setQueryData` + single invalidation). Deactivate → confirm dialog → the row dims to the deactivated state
|
||||
with the "can't be booked" hint; **no delete** option. Reactivate from the inactive row.
|
||||
6. **Caching** — Devtools: `catalogKeys.categories()` / `categoryOptionGroups` are served from cache across Home
|
||||
and every builder step (no per-step refetch); a variant mutation invalidates only `myVariants`.
|
||||
7. **Gate** — `npm run check` + `npm run test:ci` pass.
|
||||
|
||||
## What is mocked / waiting on a real service
|
||||
- **`CatalogApi`** — `client/src/services/catalog/apis/mockApi.ts` (+ `seed.ts`), behind `USE_CATALOG_MOCK`
|
||||
(default `true`). Faithfully reproduces the b5 create validation (`400` missing-required / bad-price) and the
|
||||
`(nurse, category, option-set)` duplicate **`409`**; categories mirror the real seed; the variant store starts
|
||||
**empty** (so the empty state demos). See [`mocks-registry.md`](./mocks-registry.md) (`CatalogApi` row).
|
||||
**Swap = one line** (`USE_CATALOG_MOCK = false`); `catalogClientApi` is already wired to the action-style routes.
|
||||
Caveat recorded there: the mock seeds representative **option groups the fresh backend does not** (an admin
|
||||
authors them per category) — after the swap, categories have no groups until seeded server-side.
|
||||
|
||||
## Contracts
|
||||
- **Consumed:** [`dev/contracts/domains/catalog.md`](../../contracts/domains/catalog.md) (backend-phase-b5) —
|
||||
types/services derive from it; no shape guessed.
|
||||
- **Requested:** `REQ-010` in [`for-backend.md`](../frontend/requests/for-backend.md) — confirm/align the list
|
||||
pagination query-param name (`pageSize`, per the proven b4 binding, vs the doc's `page_size`).
|
||||
- **Produced:** none (frontend produces no contract).
|
||||
|
||||
## Docs updated
|
||||
- [`client/CLAUDE.md`](../../../client/CLAUDE.md) — *Project Structure* (customer `search` stub, nurse `services`
|
||||
route, `services/catalog` domain, `CategoryTile`/`PriceDisplay`/`VariantCard`); the reference-data caching note
|
||||
(catalog = second long-lived cached domain); the i18n namespaces list (`catalog`/`services`/`search`, `home`).
|
||||
- This report + `STATUS.md` + `mocks-registry.md` + `for-backend.md` (REQ-010).
|
||||
- No product-doc rule change was needed; the estimated-total presentation rule (total only from
|
||||
price × session_count, never price alone) is captured here and enforced in `PriceDisplay`/the builder.
|
||||
|
||||
## Follow-ups for later phases
|
||||
- **f6 (search & discovery)** — the Home **search bar** hands a `q` / `service_category_id` to `/search` (today a
|
||||
placeholder); f6 builds the results, filters, and nurse cards, and can **reuse** `CategoryTile`, `PriceDisplay`,
|
||||
the cached `useServiceCategories`/`useCategoryOptionGroups`, and the `catalog`/`search` namespaces. The **variant
|
||||
builder is what populates the index f6 reads** (a nurse must have ≥1 active variant + coverage to appear).
|
||||
- **Backend** — deliver `REQ-010` (pagination param confirmation), then f6 can flip `USE_CATALOG_MOCK=false`.
|
||||
- **Deferred (unchanged):** admin catalog manager (→ f15), nurse availability slots, public nurse-profile service
|
||||
rows (→ f6 C3), holiday/surge pricing.
|
||||
Reference in New Issue
Block a user