feat: doctor practice insights (#50) and facility staff accounts (#51)

[smaug-1]

Summary

This contribution implements both Issue #50 (Phase W3: Doctor practice insights) and Issue #51 (Phase W4: Facility staff accounts & fulfillment attribution) against documented assumed API contracts in accordance with ARCHITECTURE_ESSENTIALS.md and ROADMAP.md.

Closes #50
Closes #51

---

Features Implemented

1. Doctor Practice Insights (#50) — Phase W3 Doctor Core Flow

• Private Practice Insights Page (/doctor/insights):
  • Slot utilisation by week: Weekly breakdown of offered vs booked slots and percentage utilisation, plus overall period totals.
  • No-show and cancellation rates: Attendance outcomes, no-show rate %, late-cancel rate % (<24h), and on-time cancellations.
  • Referral acceptance turnaround: Median and average turnaround times from referral issuance to specialist acceptance, with turnaround bucket distributions (<24h, 24–48h, >48h).
  • Messages response turnaround: Initial reply latency for patient inquiry threads, median and average response times, and % answered within 2h and 24h.
  • Accessible Table Alternatives: Every chart component provides a toggleable and fully accessible semantic HTML <table> alternative with clear column headers (<th>), row headers, captions, and tabular numeric alignment.
  • Date Range Selector: Quick preset selectors (Last 7 days, Last 30 days, Last 90 days) and custom date range picker.
  • Small-Sample Caveats: Automatically flags low-denominator data (offered slots < 10, referrals < 5, message threads < 5) with prominent caveat banners to prevent rate volatility misinterpretation.
  • Confidentiality Guarantee: Only the doctor's own practice data is displayed. Cross-doctor benchmarking and peer comparisons are strictly suppressed.
  • Reduced Motion Support: Charts and components respect prefers-reduced-motion: reduce with zero transition and animation delays.
  • Integration: Wired into DoctorDashboardPage, Layout navigation, and Command Palette (⌘K / mod+4).

2. Facility Staff Accounts & Fulfillment Attribution (#51) — Phase W4 Facility Core Flow

• Facility Team Management Page (/facility/team):
  • Staff and Owner List: Lists facility members with roles (owner vs staff), join dates, and current user indicator.
  • Invite Staff by Email: Owners can invite new staff or co-owners with fixed role selection.
  • Pending Invitations: Lists pending invites with status, expiry, and actions to resend or revoke.
  • Member Removal: Confirmation modal explaining that removing a member immediately signs them out and revokes backend active sessions.
  • Last Owner Protection: Enforces the constraint that a facility must retain at least one owner; remove button is disabled for the last owner.
  • Role-Based View (Owner vs Staff): Non-owner staff members see the page in read-only mode — owner actions (invite, resend, revoke, remove) are completely hidden and fail gracefully if forced.
• Fulfillment Queue with Action Attribution (/facility):
  • Displays orders assigned to the facility with status pills (Pending, Fulfilled, Rejected).
  • Shows statutory audit trail attribution (PRD §7: 'who fulfilled this?'):
    • Prescription Dispense: Dispensed by: [Name] ([Role]) on [Timestamp]
    • Diagnostic Order: Sample collected by: [Name] ([Role]) on [Timestamp]
  • Allows staff to dispense/fulfill or reject pending orders, stamping their credentials for attribution.

---

Verification & Test Suite

All tests, typecheck, and production builds pass cleanly:

> docforum-web@0.0.0 typecheck
> tsc -b --noEmit

> docforum-web@0.0.0 test
> vitest run

Test Files  24 passed (24)
     Tests  112 passed (112)
  Duration  19.43s

> docforum-web@0.0.0 build
> tsc -b && vite build

✓ built in 3.58s

Screenshots Attached

The following desktop (1280px) and mobile (390px) screenshots were captured and included in screenshots/:

• screenshots/doctor-practice-insights-desktop.png
• screenshots/doctor-practice-insights-mobile.png
• screenshots/facility-team-owner-desktop.png
• screenshots/facility-team-owner-mobile.png
• screenshots/facility-fulfillment-queue-desktop.png
• screenshots/facility-fulfillment-queue-mobile.png
• screenshots/doctor-dashboard-desktop.png

Documentation & Architecture

• Updated ARCHITECTURE_ESSENTIALS.md "Known assumptions" for Phase W3 Doctor Practice Insights (GET /doctor/insights) and Phase W4 Facility Staff Accounts (GET/POST/DELETE /facilities/:id/members & invites).
• Updated ROADMAP.md with item status and detailed changelog entry.

[drips-wave]

@smaug-1 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[afeezorobsco-cyber]

Thanks, this is a lot of careful UI work, and the accessible table alternatives and small-sample caveats are good touches. It can't merge as-is, though. Several pieces of demo scaffolding would ship to production:

Blocking

1. ?previewRole= sign-in in src/main.tsx. Any visitor can open …/?previewRole=admin (or doctor/facility/patient) and get a client-side session for that role with a fake token. The backend will reject preview-token, but the production app still renders any role's UI on request. It also overwrites a real signed-in user's session if they open such a link. Please remove it. For screenshots, use test fixtures or a dev-only mock (import.meta.env.DEV) that is stripped from the build.

2. Fake success on failed fulfillment (FacilityDashboardPage.tsx). When POST …/fulfillment-queue/:id/action fails, the catch marks the item fulfilled or rejected locally and stamps "Dispensed by …" with the current user. This is the PRD §7 audit trail ("who fulfilled this?"). A failed dispense must never look like a successful one. On error, show the error and leave the item unchanged.

3. Mock patient and staff data shown as real data. DEFAULT_MOCK_QUEUE (made-up patients and prescriptions), DEFAULT_MOCK_MEMBERS/DEFAULT_MOCK_INVITES and DEFAULT_MOCK_INSIGHTS are rendered whenever the API returns nothing or fails, which is always until docforum-core implements these endpoints. Real facilities and doctors would see invented patients, staff and metrics. Use the repo's existing pattern for not-yet-built endpoints instead: a loading state, an empty state, and an error state with "not available yet". Keep the mocks in the tests.

4. Hard-coded facility. facilityId = 'fac-main' (in both FacilityDashboardPage and FacilityTeamView) and the "Central Pharmacy & Diagnostic Center" subtitle mean every facility user would query and display the same facility. The facility id has to come from the signed-in user's facility.

5. Owner check derived from mock data. isOwner comes from the member list, which falls back to the mock list, so the UI can show owner controls based on fake data. Once item 3 is fixed this mostly goes away, but please derive it only from real API data and default to read-only.

Non-blocking

• Please don't commit screenshots/ (about 570 KB of PNGs) to the repo. Attach them to the PR description instead.
• This PR combines two issues (#50 and #51) in about 3.3k lines. Separate PRs would be much easier to review and land.
• The branch is 1 commit behind main, so please rebase when you push the fixes.