hamid
251 lines
18 KiB
Markdown
251 lines
18 KiB
Markdown
# 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.
|