refinement phase 7

server/CLAUDE.md

@@ -56,10 +56,15 @@ You are a **senior .NET software engineer** working on this codebase. That means
 | Update DB | `dotnet ef database update --project src/Infrastructure/Baya.Infrastructure.Persistence --startup-project src/API/Baya.Web.Api` |
 
 **Default URL:** `https://localhost:5002` — Swagger at `/swagger`.
-On boot (non-Testing), `Program.cs` calls `ApplyMigrationsAsync()` + `SeedDefaultUsersAsync()` (roles always;
-a bootstrap admin **only if `Seed:AdminUsername`/`Seed:AdminPassword` are configured** — never a committed
-credential), and **only in Development** `SeedPaymentGatewaysAsync()` (the sandbox gateway) + `SeedDemoWorldAsync()`
-(the demo marketplace, see Persistence below). A reachable SQL Server is required to start. Startup **fails fast**
+**Migrations are split from boot (refinement-phase-7).** `dotnet run -- migrate` (the deploy-time one-shot / a CI
+`dotnet ef database update`) applies migrations + the idempotent seeders, then exits — so multi-instance boots never
+race on DDL and the runtime login needs no permanent DDL rights. **In Development**, boot still migrates + seeds for
+convenience: `Program.cs` calls `ApplyMigrationsAsync()` + `SeedDefaultUsersAsync()` (roles always; a bootstrap admin
+**only if `Seed:AdminUsername`/`Seed:AdminPassword` are configured** — never a committed credential) + the
+Development-only `SeedPaymentGatewaysAsync()` (sandbox gateway) + `SeedDemoWorldAsync()` (demo marketplace, see
+Persistence below). **In deployed environments**, boot instead only *checks* the schema is current
+(`EnsureSchemaUpToDateAsync` — fail fast on a pending migration) and seeds roles/break-glass admin (idempotent). A
+reachable SQL Server is required to start. Startup **fails fast**
 (`StartupSecretsGuard`) if a load-bearing secret — the DB connection strings, and in deployed environments the
 JWE + field-encryption keys — is missing or left at its committed `SET_VIA_USER_SECRETS_OR_ENV` placeholder
 (refinement-phase-5). Development supplies working dev-only crypto keys via `appsettings.Development.json`; only
@@ -90,7 +95,7 @@ src/
 │   ├── Baya.Domain          Entities (User, Role, UserSession, RoleNames…, Identity/ (NurseProfile, CustomerProfile, Patient, NurseBankAccount, CustomerAddress), Geography/ (Province, City, District, NurseServiceArea), Catalog/ (ServiceCategory, ServiceOptionGroup, ServiceOptionValue, NurseServiceVariant, NurseServiceVariantOption, PriceUnits), Verification/ (NurseVerification, VerificationStepType, VerificationStep, VerificationDocument, NurseCredential + VerificationStatus/VerificationStepStatus enums), Search/ (NurseSearchIndex — the denormalized search projection), Booking/ (BookingRequest — the money-free pre-payment intent + BookingRequestStatus/BookingRequestTransitions forward-only status guard + CaregiverGender codes; b9 adds Booking/BookingSession/BookingCareInstruction/VisitVerification/CancellationPolicy + their status/transition tables + BookingAmounts money split), Payments/ (b10 ledger/txn/webhook/gateway + LedgerPosting; b11 adds Refunds/ + Invoices/), Bnpl/ (b12 BnplTransaction + BnplStatus/BnplTransitions/BnplEligibilityStatus/BnplProviderCodes — the net-of-fee card-payment model), Payouts/ (b13 NursePayoutBatch/NursePayout/NursePayoutBookingLink + PayoutBatchStatus/PayoutStatus/*Transitions — the weekly payout run), Reviews/ (b14 Review (IAuditable) + ReviewModerationStatus/ReviewModerationAction codes + ReviewTagMaster/ReviewTagLink + PatientCareRecord — moderated reviews, tag vocab & patient-scoped encrypted clinical notes), + Configuration/Audit/Analytics/Holidays/Notifications/SupportAlerts), BaseEntity, IEntity, ITimeModification, IAuditableEntity, IAuditable (audit-row marker)
 │   └── Baya.Application     Features/ (Commands & Queries; Identity area = auth + profiles/patients/nurse-bank-accounts; Geography/ServiceAreas/Addresses areas = geo hierarchy + nurse service areas + customer addresses; Catalog/Variants areas = admin catalog skeleton + nurse pricing variants; Verification area = the b6 nurse-verification pipeline (submit/status/uploads/automated runs + admin review/suspend/scan + public trust badge); Search area = the b7 discovery query + admin index-rebuild; Booking area = the b8 booking-request lifecycle (create/accept/reject/cancel + role-scoped inbox/detail + the expiry sweep command); Bookings area = the b9 booking engine (convert/detail/list/transition, care-instructions submit+gated read, EVV check-in/out + today's sessions + admin EVV queue, cancel booking/session, no-show sweep, cancellation-policy CRUD); Payments area = the b10 money core (initiate/webhook/confirm-post-ledger/nurse-payable-balance); Refunds + Invoices areas = the b11 reversal leg (create refund/confirm-settlement/mark-failed [refinement-phase-6: the BNPL/manual `processing → succeeded` clearing]/write-off clawback/list/refund-status; issue invoice/get invoice); Bnpl area = the b12 provider-financed-installment checkout (eligibility/initiate/verify/settle/revert/callback/status + BookingConversion shared with b10); Payouts area = the b13 weekly payout engine (compute-eligible/generate-batch/process/retry/mark-failed + admin batch detail/list + nurse history; PayoutSettlement shared ledger+clawback-netting step); Reviews area = the b14 reviews & ratings (submit/moderate/attach-tags + public list/tag-aggregates + admin moderation-queue; RecomputeNurseRating from-source helper + ReviewCache); PatientCareRecords area = the b14 encrypted patient-scoped clinical notes (write/history under strict clinical access); + Configuration/Audit/Analytics/Holidays/Notifications/SupportAlerts areas), Contracts/ (incl. Contracts/Common cross-cutting seams incl. IBankAccountOwnershipVerifier + IGeocoder + IVariantSnapshotSerializer + IShahkarVerifier + IIdentityKycProvider + ICredentialVerifier + Contracts/Reviews IReviewModerationService (AI review pre-screen seam) + the platform-signal facade contracts + Contracts/Search (INurseSearch read seam + ISearchIndexMaintainer write seam) + Contracts/Persistence per-domain repositories on IUnitOfWork incl. IVerificationRepository + IReviewRepository + IPatientCareRecordRepository), Models/, pipeline behaviors (Common/ — validators auto-registered from this assembly; VerificationAggregator + IdentityNameMatch helpers)
 ├── Infrastructure/
-│   ├── Baya.Infrastructure.Persistence     ApplicationDbContext (+ encrypted-PII value converters & phone-hash sync), ValueConversion/, Repositories/, Configuration/ (per-area EF config incl. SearchConfig/ + BookingConfig/ — b8 BookingRequest + b9 bookings/sessions/care/EVV/cancellation-policy configs & seed + ReviewsConfig/ — b14 reviews/tags-master (seeded)/tag-links/patient-care-records configs), Repositories/ (incl. b9 BookingRepository + CancellationPolicyRepository + b14 ReviewRepository + PatientCareRecordRepository), Migrations/, Interceptors/ (AuditFieldInterceptor — audit-fields + audit-log rows), Services/ (DB-backed platform-signal facades + notification-retention hosted service + Search/ = SearchIndexMaintainer + SqlNurseSearch + Booking/ = BookingRequestExpiryHostedService)
+│   ├── Baya.Infrastructure.Persistence     ApplicationDbContext (+ encrypted-PII value converters & phone-hash sync), ValueConversion/, Repositories/, Configuration/ (per-area EF config incl. SearchConfig/ + BookingConfig/ — b8 BookingRequest + b9 bookings/sessions/care/EVV/cancellation-policy configs & seed + ReviewsConfig/ — b14 reviews/tags-master (seeded)/tag-links/patient-care-records configs), Repositories/ (incl. b9 BookingRepository + CancellationPolicyRepository + b14 ReviewRepository + PatientCareRecordRepository), Migrations/, Interceptors/ (AuditFieldInterceptor — audit-fields + audit-log rows), Services/ (DB-backed platform-signal facades + Scheduling/ = RecurringJobSchedulerHostedService + Jobs/ (the IRecurringJob crons — refinement-phase-7) + Search/ = SearchIndexMaintainer + SqlNurseSearch)
 │   ├── Baya.Infrastructure.Identity        Jwt/, Identity/ (Managers, Stores, PermissionManager, Seed, CurrentUser/)
 │   ├── Baya.Infrastructure.CrossCutting    Serilog wiring + Seams/ (mock impls of the cross-cutting seams incl. LoggingSmsSender + MockBankAccountOwnershipVerifier + MockShahkarVerifier + MockIdentityKycProvider + MockCredentialVerifier + MockPaymentCaptureSimulator + MockBankTransferProvider + MockReviewModerationService) + AddCrossCuttingSeams
 │   └── Baya.Infrastructure.Monitoring      HealthChecks, OpenTelemetry, prometheus-net
@@ -127,9 +132,8 @@ contracts — `IPlatformConfig` (typed cached config), `IHolidayCalendar` (bank-
 trail), `INotificationService` (per-user notification reads/commands), `ISupportAlertService` (internal
 worklist) — are implemented in **`Baya.Infrastructure.Persistence/Services/`** and registered by
 `AddPersistenceServices`, *not* in CrossCutting. The real `INotificationDispatcher` (in-app
-`notifications` write) also lives there and **supersedes** the b0 log stub. The
-`NotificationRetentionHostedService` (the retention/`IJobScheduler` seam) is registered as a hosted
-service there too. Other domains call these contracts; they never re-create the tables. The
+`notifications` write) also lives there and **supersedes** the b0 log stub. Other domains call these
+contracts; they never re-create the tables. The
 `AuditFieldInterceptor` additionally writes an append-only `audit_logs` row for any `IAuditable` entity
 (`PlatformConfig`, `PartnerCenter`, `Review`, and — refinement-phase-6 — the admin-decided money & trust
 entities `Refund`, `NurseClawback`, `NursePayout`, `NursePayoutBatch`, `NurseVerification`; encrypted columns
@@ -241,8 +245,8 @@ b9/b10). One customer requests one nurse for a patient/variant/address/date; the
 30-minute payment window) or rejects before a frozen response deadline; unanswered/unpaid requests auto-expire.
 Features under `Baya.Application/Features/Booking/{Commands|Queries}/`; config in
 `Persistence/Configuration/BookingConfig/`; per-domain repo (`IBookingRequestRepository`) on `IUnitOfWork`;
-the recurring sweep is `Persistence/Services/Booking/BookingRequestExpiryHostedService` (reuses the b1
-`IJobScheduler`/`BackgroundService` seam). Load-bearing rules:
+the recurring expiry sweep is the `booking_request_expiry` `IRecurringJob` run by the scheduler (see
+"Unattended operation" below — refinement-phase-7 re-homed it from a standalone hosted service). Load-bearing rules:
 - **No money, ever, and no `bookings` row.** A request carries no price/total; accept only opens the payment
   window. b9 consumes an `accepted_awaiting_payment` request → creates the booking → sets it `converted`.
 - **Two-stage clinical disclosure (stage 1).** The nurse sees **only** the unencrypted, limited `customer_notes`
@@ -512,6 +516,29 @@ controllers `TicketsController` / `AdminTicketsController` / `AdminPartnerCenter
   manual-approve at MVP; `VerifyPartnerCenter` records the human decision. There is **no** telephony/VoIP seam
   (the emergency call is an out-of-platform `tel:` link by design). This is the last backend phase.
 
+**Unattended operation — the recurring-job scheduler (refinement-phase-7).** A single in-process scheduler,
+`Persistence/Services/Scheduling/RecurringJobSchedulerHostedService`, drives every registered `IRecurringJob`
+(`Services/Scheduling/Jobs/`) on its own cadence — replacing the two stand-alone `PeriodicTimer` hosted services
+and giving the previously admin-manual sweeps a schedule, **using no new infrastructure** (SQL Server stays the
+only external dependency). Jobs, each reading its seeded `platform_configs` cadence key via `IPlatformConfig`:
+`booking_request_expiry` (1 min const) · `notification_retention` (24 h const) · `verification_expiry_scan`
+(`verification_expiry_scan_cadence_hours`) · `no_show_sweep` (`no_show_scan_cadence_hours`) ·
+`weekly_payout_generation` (`nurse_payout_interval_days`). Load-bearing rules:
+- **Add a cron = implement `IRecurringJob` + one `AddSingleton<IRecurringJob, …>()`** in `AddPersistenceServices`.
+  Phase 8 registers the Moadian reconciliation + refund-settlement poll exactly this way. The scheduler owns the
+  per-tick DI scope, error isolation (a throwing tick never kills the loop), and the lock; a job says only *how
+  often* and *what one idempotent run does*.
+- **Jobs must be idempotent** — a retry (or a second instance once the lock is Redis-backed) must never double-pay
+  or double-post; the DB uniques/state-machines are the backstop. Each tick runs under
+  `IDistributedLock("scheduler:{name}")` — in-proc today, the **>1-instance scale-out gate** (swap the seam to
+  Redis to serialize ticks across nodes; single-instance MVP needs neither Redis nor Hangfire/Quartz).
+- **Money movement stays human-approved.** The payout job schedules *generation* only (a `draft` batch, recorded
+  system-initiated — `NursePayoutBatch.InitiatedByAdminId` is nullable = "no human initiator"); the irreversible
+  `process` step remains an explicit admin action. The command's `SystemInitiated` flag is scheduler-only —
+  `AdminPayoutsController` neutralizes any request-supplied value.
+- **Admin manual triggers remain overrides** (the same idempotent commands). The scheduler is **dormant under the
+  `Testing` environment** so integration tests stay deterministic; each job/command is unit-tested directly.
+
 **Keeping the Project map current.** When a change touches the architecture — adds, removes, or
 renames a project/assembly, a Clean-Architecture layer, or a major folder, or changes a cross-layer
 dependency — you **must** update this Project map (and the dependency rule above, if affected) in the
@@ -529,7 +556,7 @@ builder.ValidateRequiredSecrets()  // refinement-phase-5: fail fast on missing/p
 ConfigureHealthChecks() · SetupOpenTelemetry()
 AddApplicationServices()           // Mediator + pipeline behaviors (Logging → Metrics → Validate)
 RegisterIdentityServices(…, requireHttpsMetadata)  // Identity, JWT/JWE (RequireHttpsMetadata on outside Dev/Testing), ICurrentUser
-AddPersistenceServices(...)        // DbContext (+ AuditFieldInterceptor), UnitOfWork, repositories
+AddPersistenceServices(...)        // DbContext (+ AuditFieldInterceptor), UnitOfWork, repositories, the IRecurringJob crons + RecurringJobSchedulerHostedService (refinement-phase-7)
 AddCrossCuttingSeams(config)       // IDateTimeProvider, IFieldEncryptor, ICacheService, IObjectStorage, INotificationDispatcher (mocks)
 AddWebFrameworkServices()          // API versioning + snake_case routing
 AddCorsPolicies(config)            // browser CORS policy from Cors:AllowedOrigins (refinement-phase-0; default http://localhost:3000 in Dev)