# Frontend ↔ backend gaps — REQ reconciliation

**Audit date:** 2026-07-10 · **Sources:** `dev/shared-working-context/frontend/requests/for-backend.md`
(REQ-001…015), the frontend phase reports/STATUS (f0–f8), the client code's mock flags, the published
contracts (`dev/contracts/domains/*.md` + `dev/contracts/openapi/swagger.v1.json`), and the server code.
Every verdict was checked against **both** the contract surface and the actual DTO/handler/controller code.

**Headline:** the backend chain is complete (b0–b15), but of the 15 filed REQs only **REQ-001** and
**REQ-015** are effectively satisfied and **REQ-010** is a documentation fix — the other **12 are
undelivered**. Every REQ still reads `Status: open` in the tracker. As a direct consequence, **11 of the
client's 12 service domains still default to mock-primary** (only auth is real-default,
`client/src/services/auth/constants.ts:6`). Beyond the filed REQs, the unbuilt frontend phases f9–f15 will
consume backend surfaces that mostly exist — with one data gap (catalog option groups) and one pre-flagged
shape gap (checkout VAT line).

## Verdict summary

| REQ | Ask (short) | Verdict | One-line evidence |
| --- | --- | --- | --- |
| REQ-001 | Envelope / casing / pagination shape | **Done** (confirm + caveat) | `ApiResult` + `PagedResult` match the typed shape; `statusCode` is an **integer** enum |
| REQ-002 | `codeLength`/`expiresInSeconds` on RequestOtpResult | **Missing** | `RequestOtpResult.cs:7` has only `OtpSent`, `ResendAvailableInSeconds` |
| REQ-003 | Machine error codes for verify_otp | **Missing** | envelope has no `code` slot; lockout differs only by message text |
| REQ-004 | `activeRole` on MeResult (confirmation) | **Missing** (answer: client owns it) | `MeResult.cs:9` — no ActiveRole anywhere in the contract |
| REQ-005 | Patient `relation` + `conditions` | **Missing** | `PatientDto.cs:7`, create/update commands unchanged |
| REQ-006 | Avatar upload route + `avatarUrl` | **Missing** | zero `IFormFile`/avatar matches in `server/src` |
| REQ-007 | Customer name + preferred language | **Missing** | upsert body is emergency-contact only |
| REQ-008 | Accept client map pin on address create/update | **Missing** | commands have no lat/lng; always geocodes |
| REQ-009 | `provinceId` on CustomerAddressDto | **Missing** | DTO ends at RecipientPhone |
| REQ-010 | pageSize vs page_size | **Partial** | server binds `pageSize` (verified); contract docs still say `page_size` |
| REQ-011 | Nurse credential_details endpoint + `isRequired` | **Missing** | no such route/command; step DTO lacks isRequired |
| REQ-012 | Search row name/avatar/distance + `GET nurses/{id}/profile` | **Missing** | DTO ids-only; no profile action on NursesController |
| REQ-013 | `variantPrice` on BookingRequestDto | **Missing** | DTO has unit without price |
| REQ-014 | `variantLabel`/`patientAge` on list item | **Missing** | list DTO omits both |
| REQ-015 | Status enum codes + `checkInAddressMatch` tri-state (confirmation) | **Done** (verified in code) | snake_case string constants on the wire; null-when-no-GPS confirmed |

---

## Per-REQ detail

### REQ-001 — envelope, casing, pagination — **Done, needs a written confirmation + one caveat**

- **Frontend expects:** payload always under `data` in
  `{ isSuccess, statusCode, message, requestId, data }`; camelCase JSON; lists as
  `{ items, total, page, pageSize }`.
- **Backend ships:** exactly that. `ApiResult` at
  `server/src/Core/Baya.Application/Models/ApiResult/ApiResult.cs:8` (+ generic `Data` at `:28`);
  `PagedResult<T>(Items, Total, Page, PageSize)` at
  `server/src/Core/Baya.Application/Models/Common/PagedResult.cs:4`; camelCase is the System.Text.Json
  default (no naming-policy override exists in `server/src/API`); swagger confirms
  (`dev/contracts/openapi/swagger.v1.json:13448` envelope, `:14205` paged shape).
- **Caveat to communicate:** `statusCode` serializes as an **integer** (`ApiResultStatusCode` enum,
  swagger `:13468-13469`) — matches the client's `number` typing, but worth stating so nobody expects an
  HTTP-status string.
- **Fix:** zero code. Write the confirmation into the REQ and mark it delivered.

### REQ-002 — OTP length + expiry — **Missing**

- **Expected:** `RequestOtpResult { otpSent, resendAvailableInSeconds, codeLength, expiresInSeconds }`.
- **Actual:** `server/src/Core/Baya.Application/Models/Identity/RequestOtpResult.cs:7` — two fields only;
  handler returns them at `Features/Identity/Commands/RequestOtp/RequestOtpCommand.Handler.cs:67`; swagger
  agrees (`swagger.v1.json:16539`). The client hardcodes `OTP_CODE_LENGTH = 6`
  (`client/src/services/auth/constants.ts:19`).
- **Fix:** add the two ints (code length is a constant today; TTL from the OTP provider options). S effort.

### REQ-003 — machine-readable verify_otp errors — **Missing**

- **Expected:** stable `code` (`otp_invalid` | `otp_expired` | `otp_locked`) + `retryAfterSeconds` on
  lockout.
- **Actual:** the envelope has no `code` slot (`ApiResult.cs:8`; `OperationResult` carries only boolean
  flags — `Models/Common/OperationResult.cs:14-31`). Wrong/expired share one anti-enumeration message
  (`Features/Identity/Commands/VerifyOtp/VerifyOtpCommand.Handler.cs:24,30,34,50`); lockout is a different
  English string only (`:38`). The client keys off the mock-only `otp_locked` code
  (`client/src/services/auth/constants.ts:29`).
- **Fix:** add an optional `code` (+ optional `data`) to the failure envelope — a small
  `OperationResult`/`ApiResult` extension — and emit `otp_locked` + `retryAfterSeconds` from the lockout
  branch; keep wrong-vs-expired collapsed if enumeration-safety is preferred (state that in the REQ
  answer). S–M effort (the only REQ touching a cross-cutting type).

### REQ-004 — activeRole confirmation — **Missing (recommend: answer "client owns it")**

- **Actual:** no `activeRole` on `MeResult`
  (`server/src/Core/Baya.Application/Models/Identity/MeResult.cs:9`) or anywhere in the contract (schema
  scan). No endpoint persists a current-role choice.
- **Fix:** zero code — write the decision (client-owned `intended_role` stands) into the REQ so the router
  behavior is contract-blessed. If the product later wants a persisted active role, it's a `me/select_role`
  extension.

### REQ-005 — patient relation + conditions — **Missing**

- **Actual:** `PatientDto` ends at `InitialMedicalNotes`/`IsActive`
  (`Models/Identity/PatientDto.cs:7,15-16`); create/update commands unchanged
  (`Features/Identity/Commands/CreatePatient/CreatePatientCommand.cs:12-19`,
  `UpdatePatient/UpdatePatientCommand.cs:8-16`); no `relation`/`conditions` in any schema.
- **Fix:** `relation` as a nullable code column; `conditions` as stable codes (JSON column or child table —
  child table if search/filtering is ever wanted). Gate: flips `USE_PATIENTS_MOCK`
  (`client/src/services/patients/constants.ts:8`). S–M effort.

### REQ-006 — avatar upload + avatarUrl — **Missing**

- **Actual:** zero `IFormFile`/multipart/avatar usage in `server/src` (repo-wide grep); no `avatarUrl` on
  `NurseProfileDto` (swagger `:18945`) or `CustomerProfileDto`
  (`Models/Identity/CustomerProfileDto.cs:7`). The client's real path deliberately throws 501
  (`client/src/services/profiles/apis/clientApi.ts:84`).
- **Fix:** `POST api/v1/{nurse|customer}_profiles/avatar` (multipart, size/type-validated) storing via
  `IObjectStorage` + `avatar_url` column on both profiles. Note it also feeds REQ-012 (search card avatar)
  and REQ-013 (nurse avatar on request detail) — deliver before or with those. M effort (first multipart
  endpoint; pairs with the object-storage swap, plan §5.5).

### REQ-007 — customer name + preferred language — **Missing**

- **Actual:** upsert body is emergency-contact only
  (`Features/Identity/Commands/UpsertCustomerProfile/UpsertCustomerProfileCommand.cs:11`); `MeResult`
  exposes name read-only (`MeResult.cs:12`); no `preferredLanguage` anywhere (schema scan).
- **Fix:** decide the home (recommend: extend the upsert to write `Users.FirstName/LastName` +
  `preferred_language` on the customer profile) and answer the REQ. S effort.

### REQ-008 — accept the client map pin — **Missing**

- **Actual:** create/update commands have no coordinates; the server always geocodes
  (`Features/Addresses/Commands/CreateAddress/CreateAddressCommand.cs:9-12`,
  `UpdateAddress/UpdateAddressCommand.cs:8-9`; swagger `:18051`). The user's pin is silently discarded on
  the real path — exactly what the REQ warned. This also degrades **EVV accuracy** (b9 measures distance to
  the stored coordinate; a mock/geocoded centroid is ±5 km off — `CrossCutting/Seams/MockGeocoder.cs:52`).
- **Fix:** optional `latitude`/`longitude` on both bodies; when present store as source `user_pin`, else
  geocode as today. S effort; do before the real geocoder swap (plan §5.4).

### REQ-009 — provinceId on CustomerAddressDto — **Missing**

- **Actual:** DTO fields run `Id..RecipientPhone` (`Models/Addresses/CustomerAddressDto.cs:9-24`); no
  `provinceId` (swagger `:17983` — the property exists only on `CityDto`).
- **Fix:** join `cities.province_id` into the address projections. S effort. Gate (with REQ-008):
  `USE_ADDRESSES_MOCK` (`client/src/services/addresses/constants.ts:10`).

### REQ-010 — pageSize param name — **Partial (server verified; docs stale)**

- **Actual:** every list binds a `PageSize` record property via `[FromQuery]` — so the working wire name is
  camelCase `pageSize` (case-insensitive), and `page_size` **silently does not bind**. Verified:
  `Features/ServiceAreas/Queries/ListMyServiceAreas/ListMyServiceAreasQuery.cs:8`,
  `Features/Variants/Queries/ListMyVariants/ListMyVariantsQuery.cs:8`,
  `Controllers/V1/NurseServiceAreasController.cs:35`, `AdminPayoutsController.cs:54`; swagger names the
  parameter `pageSize` (`swagger.v1.json:3104`). But the requested deliverable — fixing the docs — never
  happened: `dev/contracts/domains/catalog.md:41` and `config-reference.md:11` (and others, e.g.
  bookings-evv.md, verification.md) still write `page_size`.
- **Fix:** sweep the contract docs to `pageSize`, answer the REQ. Zero server code.

### REQ-011 — nurse credential_details + isRequired — **Missing**

- **Actual:** the nurse-facing controller exposes only submit/status/upload_url/documents/run
  (`Controllers/V1/NurseVerificationController.cs:26-57`); repo-wide grep for
  `credential_details|SubmitCredential` finds nothing. `VerificationStepDto` has no `IsRequired`
  (`Models/Verification/VerificationDtos.cs:17`); the flag exists only on the admin step-type catalog.
  Consequence on the real path: the INO number + specialties a nurse types are **silently dropped**
  (`verificationClientApi.submitCredentialDetails` no-ops —
  `dev/shared-working-context/reports/frontend-phase-5-report.md:101`).
- **Fix:** `POST api/v1/nurse_verification/credential_details` writing the structured
  `nurse_credentials` fields (the registry table already stores number/authority/expiry), + project
  `isRequired` onto the step DTO. M effort. Gate: `USE_VERIFICATION_MOCK`
  (`client/src/services/verification/constants.ts:9`).

### REQ-012 — search enrichment + public nurse profile — **Missing (highest-leverage gap)**

- **Actual:** `NurseSearchResultDto` carries ids + price/rating/gender/geo only
  (`Models/Search/NurseSearchResultDto.cs:8-19`); the public `NursesController` has trust_badge, reviews,
  review_tags — **no `/profile`** (`Controllers/V1/NursesController.cs:24-36`); no
  `avatarUrl`/`distanceKm` anywhere in the contract (schema scan).
- **Why it leads the priority list:** C2/C3 are the trust funnel — the family picks a *named, faced,
  priced* nurse here; this single REQ keeps `services/search` mock-primary
  (`client/src/services/search/constants.ts:9`) and blocks the whole discovery→request→booking real-path
  chain (search feeds C4's nurse/variant ids).
- **Fix:** (a) denormalize `nurse_name`/`avatar_url` into `nurse_search_index` (the maintainer already
  re-derives rows from source — `Persistence/Services/Search/SearchIndexMaintainer.cs:25`; add columns +
  reindex-on-profile-change) or join at query time in `SqlNurseSearch`; `distanceKm` is optional — the
  district model makes it derived-if-cheap. (b) an aggregated `GET nurses/{id}/profile` composing existing
  reads (profile + variants + trust badge + latest published review). M effort; depends on REQ-006 for the
  avatar itself.

### REQ-013 — variantPrice on BookingRequestDto — **Missing**

- **Actual:** the DTO has `VariantLabel` + `VariantPriceUnit` but no price and no nurse avatar
  (`Models/Booking/BookingRequestDto.cs:20-21`, full list `:11-42`; swagger `:16674`).
- **Fix:** join the variant's `Price` (IRR digit-string, consistent with the money convention) into the
  projection. The money-free rule stays intact — this is the display *rate*, not an engagement total (the
  request row still stores no money). S effort.

### REQ-014 — variantLabel/patientAge on the inbox row — **Missing**

- **Actual:** `BookingRequestListItemDto` has neither (`Models/Booking/BookingRequestListItemDto.cs:10-21`;
  swagger `:16903`) — the nurse inbox can't show *which service* was requested without opening the detail.
- **Fix:** add `variantLabel` (already on the detail DTO); `patientAge` as a coarse band if product wants
  it. S effort. Gate (with REQ-013): `USE_BOOKING_REQUESTS_MOCK`
  (`client/src/services/bookingRequests/constants.ts:14`) — though that flip also needs the upstream
  domains real (see below).

### REQ-015 — enum codes + checkInAddressMatch tri-state — **Done (verified), needs a written confirmation**

- **Verified in code:** statuses are stored/projected as snake_case **string constants** — exactly the
  client unions: `Domain/Entities/Booking/BookingStatus.cs:11-30`, `BookingSessionStatus.cs:10-19`,
  `VisitVerificationStatus.cs:11-17`; DTOs copy them verbatim (`Models/Booking/BookingDtos.cs:97`), so no
  PascalCase/int ever hits the wire. `checkInAddressMatch` is `bool?` (`BookingDtos.cs:104`) assigned only
  inside the lat/lng-present branch
  (`Features/Bookings/Commands/CheckInVisit/CheckInVisitCommand.Handler.cs:64-77`) → **null when GPS is
  absent**; a `false` is advisory only (support alert + notification, no block — `:90-109`).
- **One nuance to include in the answer:** `null` also occurs when GPS *was* sent but the frozen booking
  address has no resolvable coordinates — the client copy for «موقعیت ثبت نشد» should tolerate that.
- **Fix:** zero code; write the confirmation, mark delivered.

---

## Beyond the filed REQs — what f9–f15 will hit

Frontend phases f0–f8 are built (reports exist); **f9–f15 are specs only**. Reconciling their declared
consumption against the shipped backend:

| Upcoming phase | Consumes | Backend reality | Verdict |
| --- | --- | --- | --- |
| f9 checkout/card | b10 `payments.md` + b11 invoice | endpoints exist (initiate/webhook/`GET invoices/{booking_id}`), but **no checkout-summary read with the VAT line** — f8 already flagged `BookingDetailDto` has no tax field (`reports/frontend-phase-8-report.md:113`); f9's spec expects `vat_irr`/`vat_rate`/`redirect_url` shapes (`dev/phases/frontend/frontend-phase-9-b10.md:117,330`) | **Partial — pre-file the checkout-summary REQ now** |
| f10 refund status | b11 `refunds-invoices.md` | `GET refunds/{id}/status` + `GET invoices/{booking_id}` shipped (`Controllers/V1/RefundsController`, `InvoicesController`) | Done (verify shapes when f10 runs) |
| f11 BNPL | b12 `bnpl.md` | full eligibility→initiate→status surface shipped (`CheckoutBnplController`) | Done (verify shapes) |
| f12 nurse earnings | b13 `payouts.md` | `nurse_payouts/history` + admin console shipped (`NursePayoutsController`, `AdminPayoutsController`) | Done (verify shapes) |
| f13 reviews/care records | b14 `reviews-records.md` | submit/list/tags/moderation + care records shipped (5 controllers) | Done (verify shapes) |
| f14 tickets + notifications | b15 + **b1 notifications** | tickets shipped; notifications **verified present**: `GET notifications/get_notifications`/`get_unread_count`, `POST mark_notification_read`/`mark_all_read` (`Controllers/V1/NotificationsController.cs:24-42`) — the f14 spec's worry about missing b1 endpoints is unfounded | Done |
| f15 admin/partner consoles | admin endpoints across b1/b6/b11/b13/b14/b15 | all shipped per the chain (verification queue, refunds, payouts, moderation, config/holidays/audit/support-alerts, partner centers) | Done (expect shape-polish REQs when f15 runs) |

**Data gap (not a contract gap):** flipping `USE_CATALOG_MOCK` against a fresh backend yields categories
with **no option groups** — only the 5 categories are seeded; groups/values are admin-authored and the
admin catalog UI is f15 (`reports/frontend-phase-4-report.md:92`). Until f15 (or a seed migration), the
variant builder's required-option step has nothing to render on the real path. Recommend: a small
representative option-group seed, or prioritize the f15 catalog manager.

**Tracker hygiene:** all 15 REQs read `Status: open` (`for-backend.md:32…216`) and the mocks-registry's
early block contradicts its own later rows (see plan §7.6). Whoever lands this batch should update both in
the same change.

---

## Frontend-unblock priority

1. **REQ-012** (search row enrichment + public profile) — unlocks the discovery funnel; everything
   downstream needs C2/C3 real. Include the `nurse_search_index` columns + reindex.
2. **REQ-005, REQ-008, REQ-009** — the booking-request *inputs* (patients, addresses) go real; REQ-008
   also protects EVV accuracy.
3. **REQ-013, REQ-014** — the request flow prices/labels itself; with (1)+(2) the whole
   search→request→accept chain can flip to real.
4. **REQ-006, REQ-007** — profile/avatar polish; REQ-006 also feeds (1) and (3)'s avatar fields.
5. **REQ-011** — verification detail capture (stops silent INO/specialty data loss).
6. **REQ-002, REQ-003** — auth UX polish (real path already works without them).
7. **Zero-code batch: REQ-001, REQ-004, REQ-010, REQ-015** — written confirmations + contract-doc
   `page_size` sweep + tracker statuses.
8. **Pre-file the f9 checkout-summary REQ** (VAT line, redirect_url, idempotency header echo) so b-side
   work can precede the f9 build.