Pro (Doctor) API Flows

JWT audience: snr_pro. Doctor ID from JWT id claim.

List assigned cases

sequenceDiagram
  participant Pro as Pro App
  participant Worker as second_opinion
  participant D1 as D1

  Pro->>Worker: POST /pro/sops { coordinator?, page }
  Note over Worker: JWT id = second_opinions.doctor_id
  Worker->>D1: SELECT second_opinions WHERE active=1
  Worker-->>Pro: paginated sop list

Review case details

sequenceDiagram
  participant Pro as Pro App
  participant Worker as second_opinion
  participant D1 as D1
  participant PX as Persistence

  Pro->>Worker: POST /pro/review-case-details { case_id, coordinator? }
  Note over Worker: JWT id = coordinator or assigned doctor
  Worker->>D1: verify access (case_coordinator_id or second_opinions)
  Worker->>D1: SELECT review_cases + joins
  Worker->>D1: SELECT second_opinions + case_status_history
  Worker->>D1: LOAD sop_doctors for team
  Worker->>PX: fetch patient profile (optional)
  Worker-->>Pro: case detail, assigned doctors, report status

List doctors (for assignment)

sequenceDiagram
  participant Coord as Coordinator Pro App
  participant Worker as second_opinion
  participant D1 as D1

  Coord->>Worker: POST /pro/list-doctors { case_id }
  Note over Worker: JWT id must = case_coordinator_id
  Worker->>D1: SELECT disease_categories.doctor_ids
  Worker->>D1: LOAD sop_doctors profiles
  Worker-->>Coord: eligible specialist list

Assign doctor to case

sequenceDiagram
  participant Coord as Coordinator Pro App
  participant Worker as second_opinion
  participant D1 as D1
  participant Sock as Socket Hub

  Coord->>Worker: POST /pro/assign-doctor
  Note over Worker: JWT id must = case_coordinator_id
  Worker->>D1: INSERT second_opinions (is_coordinator=0)
  Worker->>Sock: notify assigned doctor
  Worker-->>Coord: { sop_id, doctor_id }

Request additional documents

sequenceDiagram
  participant Pro as Pro App
  participant Worker as second_opinion
  participant D1 as D1

  Pro->>Worker: POST /pro/request-documents
  Worker->>D1: UPDATE second_opinions.requested_documents
  Worker-->>Pro: { sop_id }

Submit doctor opinion

sequenceDiagram
  participant Pro as Pro App
  participant Worker as second_opinion
  participant D1 as D1
  participant Sock as Socket Hub

  Pro->>Worker: POST /pro/review-report { sop_id, status: submitted }
  Note over Worker: Doctor assignment only (not coordinator row)
  Worker->>D1: UPDATE second_opinions diagnosis + recommendations
  Worker->>D1: INSERT sop_activity
  Worker->>Sock: notify coordinator
  Worker-->>Pro: { status: 1000 }

Submit coordinator summary

sequenceDiagram
  participant Coord as Coordinator Pro App
  participant Worker as second_opinion
  participant D1 as D1
  participant PDF as PDF Service
  participant Sock as Socket Hub

  Coord->>Worker: POST /pro/submit-coordinator-summary { sop_id }
  Worker->>D1: UPDATE coordinator summary on second_opinions
  Worker->>D1: UPDATE review_cases → completed
  Worker->>D1: INSERT case_status_history (completed)
  Worker->>PDF: generate final report PDF
  Worker->>D1: UPDATE review_cases.report
  Worker->>Sock: notify patient + coordinator
  Worker-->>Coord: { status: 1000 }

Case documents

sequenceDiagram
  participant Pro as Pro App
  participant Worker as second_opinion
  participant D1 as D1

  Pro->>Worker: POST /pro/case-documents { case_id }
  Note over Worker: Coordinator or assigned doctor
  Worker->>D1: SELECT review_cases.medical_documents
  Worker-->>Pro: parsed document list for review UI

Delay notification

sequenceDiagram
  participant Coord as Coordinator Pro App
  participant Worker as second_opinion
  participant D1 as D1
  participant Sock as Socket Hub

  Coord->>Worker: POST /pro/delay-notification { case_id }
  Note over Worker: JWT id must = case_coordinator_id
  Worker->>D1: validate case + coordinator
  Worker->>Sock: send overdue report alert
  Worker-->>Coord: { status: 1000 }