refinement phase 1

2026-07-13 00:49:24 +03:30
parent 7acecda5c4
commit 0b45ec51f4
11 changed files with 856 additions and 6 deletions
@@ -12,6 +12,31 @@ One block per completed backend phase. Newest at the top. Backend lane writes he
 - **Notes for frontend:** <anything load-bearing>
 -->

+## refinement-phase-1 — Database: local-dev story, demo seed & migration hygiene — 2026-07-13
+- **Shipped (no migration, no endpoint, no contract change):** Development-gated **demo-world seeder** —
+  `Persistence/Services/Seeding/DemoWorldSeeder.cs` + `DemoWorldDefinitions.cs`, scoped-registered in
+  `AddPersistenceServices`, invoked from `Program.cs` via new `SeedDemoWorldAsync()` **only under
+  `IsDevelopment()`**. Idempotently (guarded on phone) creates **3 nurses** (2 verified: `MarkVerified()` +
+  `nurse_verifications` `approved` + credentials + `matched_national_id` primary bank + 2–3 IRR variants +
+  Tehran areas incl. whole-city `district_id=NULL`; 1 unverified), **2 customers** (patients + coord
+  addresses), and **1 cross-category required demo option group** (شیفت / Shift Type). Search rows are driven
+  through the real `ISearchIndexMaintainer.RebuildAsync` — never hand-inserted, so `is_searchable` stays
+  truthful (verified surface, unverified doesn't). Reference `HasData` seeds + the 17 migrations untouched.
+- **Local DB / migration hygiene:** verified Phase 0's compose + placeholder connstrings + boot-migrate;
+  documented the explicit `dotnet ef database update` path + demo-reset flow in the RUNBOOK; confirmed no
+  pending model changes. Forward-dep FKs (Phase 6) and the boot-migrate multi-instance split (Phase 7) are
+  out of scope by design.
+- **Contracts:** none produced; swagger snapshot **not** regenerated (no route/shape change).
+- **Mocked:** none introduced (the seeder uses the real handlers/maintainer/converters).
+- **Gate:** build clean (0 new warnings) / tests green (**372**: +3 `DemoWorldSeederTests` proving over the
+  real HTTP pipeline — verified nurse in search, unverified not, trust badge correct, idempotent). Added
+  `InternalsVisibleTo("Baya.Test.Api")` on Persistence for the seeder test.
+- **Handoff:** backend/handoff/after-refinement-phase-1.md
+- **Notes for frontend:** demo accounts to log in as (phone-OTP) — nurses `09120000001` (verified) /
+  `09120000002` (verified) / `09120000003` (unverified); customers `09120000010` / `09120000011`. Tehran
+  `city_id=101`. `GET /search/nurses?service_category_id=1&city_id=101` now returns real verified nurses.
+  **No `USE_*_MOCK` flag flipped — de-mocking is Phase 4.**
+
 ## refinement-phase-0 — Local end-to-end bring-up & the integration seam — 2026-07-12
 - **Shipped (integration/plumbing — no business logic):** **CORS** (`Baya.WebFramework/ServiceConfiguration/
  CorsServiceExtension.cs` → `AddCorsPolicies`, policy `BalinyaarWebClient` from `Cors:AllowedOrigins`, default
@@ -0,0 +1,46 @@
+# Handoff — after refinement-phase-1 (Database: local-dev story, demo seed & migration hygiene)
+
+**Date:** 2026-07-13 · **Track:** backend (+ DB) · **Unlocks:** real search/discovery/booking data for
+[Refinement Phase 4](../../../post-phase/refinement/refinement-phase-4-frontend-de-mock.md).
+
+## What the frontend can now do
+- **A fresh Development DB is a populated marketplace, not an empty shell.** On boot (Development only) the API
+  now seeds a coherent demo world *after* the reference/lookup seeds. Every real-path discovery/search/booking
+  screen has data on the real path — no frontend change required to see it.
+- **Log in as real demo accounts** (phone-OTP flow; read the code from the server console or
+  `GET /api/v1/dev/last_otp/{phone}`). The accounts already hold the right role, so the role router lands them
+  on the correct shell:
+
+  | Phone | Role | Who | State |
+  | --- | --- | --- | --- |
+  | `09120000001` | nurse | زهرا عزیزی (female) | **verified**, accepting, 3 variants, whole-city + 2 districts |
+  | `09120000002` | nurse | علی کریمی (male) | **verified**, accepting, 2 variants, 3 districts |
+  | `09120000003` | nurse | مریم احمدی (female) | **unverified** (pending) — never surfaces in search |
+  | `09120000010` | customer | سارا محمدی (female) | 2 patients, 1 Tehran address (coords) |
+  | `09120000011` | customer | رضا حسینی (male) | 1 patient, 1 Tehran address (coords) |
+
+- **Search returns real nurses.** `GET /api/v1/search/nurses?service_category_id=1&city_id=101` (Elderly Care in
+  Tehran) returns the two verified nurses' priced variants. Categories offered only by the unverified nurse
+  (Infant Care, `service_category_id=3`) return an empty page — the `is_searchable` invariant holds.
+- **Trust badges are real.** `GET /api/v1/nurses/{id}/trust_badge` returns `isVerified=true` + credential types
+  for the verified nurses, `false` for the unverified one.
+- **The variant builder's required-option step renders on the real path.** The demo seeder adds one
+  cross-category **required** option group — شیفت / *Shift Type* (`Daytime`/`Night`/`Live-in`) — so
+  `GET /api/v1/catalog/...` option-group reads are non-empty in Development (the "categories but no option
+  groups" data gap). This group is **Development-only demo data**, not a production catalog decision.
+
+## What did NOT change (important)
+- **No `USE_*_MOCK` flag was flipped** — de-mocking the client is still [Phase 4](../../../post-phase/refinement/refinement-phase-4-frontend-de-mock.md).
+  This phase only makes the *backend* real path return data.
+- **No new endpoints, no contract changes, no new migration.** The 17 migrations are unchanged and current;
+  the reference `HasData` seeds are untouched. The demo seeder writes through the existing entities/handlers.
+- **Nothing runs in Production/Staging.** The seeder is gated on `IsDevelopment()`.
+
+## How to reset / re-seed
+- `docker compose down -v` (wipe the DB volume) then `dotnet run` → migrate + reference seed + demo seed from
+  scratch. Re-running `dotnet run` against an already-seeded DB is a **no-op** (guarded on each persona's phone).
+
+## Gotchas
+- **Money is IRR Rials** (e.g. per-24h live-in = `3500000`); on the wire variant prices are digit strings.
+- The unverified nurse **has** a variant and a covered area but `is_verified=0`, so the search maintainer
+  computes `is_searchable=0`. Do not treat "has a variant" as "is discoverable".