backend phase 14 & frontend phase 7
This commit is contained in:
hamid
@@ -0,0 +1,91 @@
|
||||
# Backend Phase 14 — Reviews, ratings & patient care records — Report
|
||||
|
||||
**Date:** 2026-07-09 · **Track:** backend · **Status:** complete, gate green.
|
||||
|
||||
Closes the trust loop (moderated reviews + an honest, recomputed-from-source public rating + low-rating safety
|
||||
alerts) and the continuity-of-care loop (encrypted, patient-scoped clinical notes under strict access).
|
||||
|
||||
## What was built
|
||||
|
||||
### Schema (one additive migration `ReviewsAndPatientCareRecords`, `reviews` schema)
|
||||
- **`Reviews`** — one per completed booking. `UNIQUE(booking_id)` (1:1), `CHECK(rating BETWEEN 1 AND 5)`, guarded
|
||||
`moderation_status` (+ reason/moderator/time), soft-delete filter. Indexes: unique `booking_id`,
|
||||
`(nurse_profile_id, moderation_status)`, `moderation_status`. Marked `IAuditable` → the SaveChanges interceptor
|
||||
writes an append-only `audit_logs` diff on creation and every moderation transition.
|
||||
- **`ReviewTagsMaster`** — seeded vocabulary (`punctual/professional/clean/kind/communicative`), `UNIQUE(code)`.
|
||||
- **`ReviewTagLinks`** — N:N join, `UNIQUE(review_id, review_tag_master_id)`.
|
||||
- **`PatientCareRecords`** — nurse-authored, **patient-scoped** (`patient_id`, not booking), nullable `booking_id`
|
||||
provenance, `body_encrypted` (ciphertext, no EF converter), `(patient_id, recorded_at)` index, soft-delete.
|
||||
- **`NurseProfile`** gained `SetReviewAggregates(avg, count)` — the single sanctioned write for the existing
|
||||
`AverageRating`/`TotalReviews` columns (no new aggregate table).
|
||||
|
||||
### Features (CQRS, `Baya.Application/Features/`)
|
||||
- **Reviews/**: `SubmitReviewCommand`, `ModerateReviewCommand`, `AttachReviewTagsCommand`,
|
||||
`ListReviewsForNurseQuery`, `GetReviewModerationQueueQuery`, `GetTagAggregatesQuery`; plus the internal
|
||||
`RecomputeNurseRating` from-source helper and `ReviewCache` (cached public aggregate + eviction).
|
||||
- **PatientCareRecords/**: `WritePatientCareRecordCommand`, `GetPatientHistoryQuery`.
|
||||
|
||||
### Endpoints (5 controllers)
|
||||
| Verb & route | Maps to | Auth |
|
||||
| --- | --- | --- |
|
||||
| `POST /v1/bookings/{bookingId}/review` | SubmitReview | customer (owns booking) |
|
||||
| `POST /v1/reviews/{reviewId}/tags` | AttachReviewTags | author / moderator |
|
||||
| `PATCH /v1/reviews/{reviewId}/status` | ModerateReview | admin / moderator |
|
||||
| `GET /v1/nurses/{nurseProfileId}/reviews` | ListReviewsForNurse | public |
|
||||
| `GET /v1/nurses/{nurseProfileId}/review_tags` | GetTagAggregates | public |
|
||||
| `GET /v1/admin/reviews/moderation_queue` | GetReviewModerationQueue | admin |
|
||||
| `POST /v1/patients/{patientId}/care_records` | WritePatientCareRecord | nurse (confirmed booking) |
|
||||
| `GET /v1/patients/{patientId}/care_records` | GetPatientHistory | owner / nurse / admin |
|
||||
|
||||
### Key design decisions (non-obvious)
|
||||
- **Recompute is exclude-and-fold, in one transaction.** A fresh LINQ query can't see the tracked, uncommitted
|
||||
status change, so `RecomputeNurseRating` reads `COUNT`/`SUM(rating)` over the nurse's published reviews
|
||||
**excluding the transitioning review** (id `0` for a brand-new one), then folds in that review's *new* status in
|
||||
memory. Correct-from-source and single-commit — no `+delta`/`-delta`, no stale re-query, no second commit.
|
||||
- **Care records encrypt manually (no EF value converter).** Unlike the b3/b9 converter-backed columns,
|
||||
`body_encrypted` stores ciphertext directly; the handler `Encrypt`s on write and `Decrypt`s only after the access
|
||||
check passes — so no query path (list, projection) can ever surface plaintext. `recorded_at` is `DateTime` (UTC),
|
||||
not `DateTimeOffset`, so the SQLite test provider can `ORDER BY` it.
|
||||
- **AI verdict → initial disposition.** `SubmitReview` calls `IReviewModerationService.ScreenAsync`; the verdict
|
||||
maps to the initial status (`Approve`→published, `Reject`→hidden, else pending). The mock defaults clean text to
|
||||
a human-review **Flag** so the **publish gate holds by default** (reviews land `pending_moderation`);
|
||||
`Seams:ReviewModeration:AutoApproveClean` opts into auto-publish. Human `ModerateReview` always overrides.
|
||||
|
||||
## What is now testable and exactly how (the phase §7 steps)
|
||||
Run the API against SQL Server; use Swagger/curl.
|
||||
1. **Submit on a completed booking → accepted.** `POST bookings/{completedId}/review {rating:5}` as the owner →
|
||||
`200`, `moderationStatus: pending_moderation`. It does **not** appear in `GET nurses/{id}/reviews` (publish gate).
|
||||
2. **Submit on a cancelled booking → rejected;** a second submit on an already-reviewed booking → conflict (1:1).
|
||||
3. **Moderate publish recomputes up.** `PATCH reviews/{id}/status {action:"publish"}` → the review appears in the
|
||||
public list; the aggregate `publishedCount` increments and `averageRating` reflects it.
|
||||
4. **Moderate hide recomputes down.** Publish a 5★ and a 1★, then `hide` the 1★ → the public list drops it and the
|
||||
aggregate rises / count decrements (re-derived from source).
|
||||
5. **Low rating raises an alert.** `POST … {rating:1}` → a `low_rating` `support_alerts` row exists (visible only on
|
||||
the admin/internal path — never in a user response; its id shows on the moderation queue row).
|
||||
6. **Write + read a care record.** As a nurse with a confirmed booking, `POST patients/{P}/care_records` → `200`;
|
||||
the stored column is ciphertext. As the owning customer or that nurse, `GET …` → decrypted note, newest first.
|
||||
7. **Unauthorized nurse denied.** A nurse with no confirmed booking for P → `403` on both write and read.
|
||||
|
||||
**Automated coverage:** 13 Foundation handler tests (`Baya.Test.Foundation/Reviews/`) cover steps 1–7 incl. the
|
||||
recompute-from-source math (hide lowers count **and** average) and ciphertext-at-rest; 4 API tests
|
||||
(`Baya.Test.Api/ReviewsApiTests.cs`) cover the HTTP pipeline (public reads anonymous, admin/patient reads 401
|
||||
without a token). Full suite: **346 pass**, build clean (0 new warnings).
|
||||
|
||||
## What is mocked / waiting on a real service
|
||||
- **`IReviewModerationService`** (introduced here) — `MockReviewModerationService` (keyword filter / pass-through),
|
||||
config `Seams:ReviewModeration:{AutoApproveClean,BannedWords}`. Make it real → a text classifier / LLM endpoint,
|
||||
registration-only swap (see reports/mocks-registry.md, row → 🟡). `ModerateReviewCommand` keeps decision authority.
|
||||
- Reused seams: `IFieldEncryptor` (clinical notes), `ISearchIndexMaintainer` (aggregate refresh),
|
||||
`ISupportAlertService` (low-rating alert), `INotificationDispatcher` (review-outcome notice), `IPlatformConfig`
|
||||
(`min_rating_for_support_alert`), `ICacheService` (aggregate cache).
|
||||
|
||||
## Contracts produced
|
||||
- `dev/contracts/domains/reviews-records.md` (8 endpoints, enums, DTOs, care-record access matrix).
|
||||
- `dev/contracts/openapi/swagger.v1.json` refreshed (all 8 paths present).
|
||||
|
||||
## Follow-ups for later phases (b15)
|
||||
- Ticket system, partner centers, and the admin **support-alert worklist console** (this phase only *raises*
|
||||
`low_rating` alerts).
|
||||
- `SuspendNurse` / `ResolveSupportAlert` / `FlagConcern` admin actions.
|
||||
- Deferred by design: two-way double-blind reviews with timed reveal; a first-class `incidents` entity + ML fraud
|
||||
scoring; optional structured `vitals_encrypted` on care records.
|
||||
Reference in New Issue
Block a user