Radiology Service — User Stories
Service: radiology-service Story prefix: RAD-US Last updated: 2026-04-18
Stories
RAD-US-001 — Register PACS endpoint
| Field | Value |
|---|---|
| Issue type | Story |
| Summary | Admin registers a DICOMweb PACS endpoint for a facility |
| Epic link | RAD-EPIC-01 |
| Status | To Do |
| Priority | Must |
| Story points | 3 |
| Labels | service:radiology, type:backend, slice:S0 |
| Components | pacs-endpoints |
| FR references | FR-RAD-006 |
| Legacy FR refs | FR-RAD-006 |
| Dependencies | — |
User story: As a radiology administrator, when I set up a new facility, I want to register the facility's PACS DICOMweb endpoint so that imaging studies can be queried and displayed in the EHR.
Acceptance criteria (Gherkin):
- Given valid DICOMweb URLs, when I POST to
/v1/radiology/pacs-endpoints, then the endpoint is created and a connectivity test returns 200. - Given an invalid QIDO-RS URL (unreachable), when created, then endpoint is saved but flagged as
connectivity_status: unknown. - Given a duplicate endpoint name per tenant, when submitted, then 409 is returned.
Technical notes:
auth_configencrypted at rest; never returned in responses
Definition of Done:
- Unit + integration tests; coverage ≥ 80%; docs updated.
RAD-US-002 — Register imaging study from order
| Field | Value |
|---|---|
| Issue type | Story |
| Summary | System registers an ImagingStudyRef when an imaging order is placed |
| Epic link | RAD-EPIC-01 |
| Status | To Do |
| Priority | Must |
| Story points | 5 |
| Labels | service:radiology, type:backend, slice:S0 |
| Components | study-metadata |
| FR references | FR-RAD-001 |
| Legacy FR refs | FR-RAD-001 |
| Dependencies | cross-service: ORDERS-US-001 |
User story:
As the platform, when an imaging order is placed, I want an ImagingStudyRef created so that the study can be tracked from order to report.
Acceptance criteria (Gherkin):
- Given
clinical.orders.placedevent with imaging ServiceRequest, when processed, thenImagingStudyRefcreated with statusregisteredanddiag.radiology.study.availablepublished when PACS confirms study exists. - Given duplicate order event with same Idempotency-Key, when processed, then idempotent — no duplicate study.
Technical notes:
- Inbox consumer on
clinical.orders.placed; QIDO-RS query scheduled after registration
Definition of Done:
- Integration test; inbox.spec.ts; outbox.spec.ts; docs updated.
RAD-US-003 — Sync study metadata from PACS
| Field | Value |
|---|---|
| Issue type | Story |
| Summary | Service syncs study metadata via QIDO-RS from the PACS |
| Epic link | RAD-EPIC-01 |
| Status | To Do |
| Priority | Must |
| Story points | 5 |
| Labels | service:radiology, type:backend, slice:S0 |
| Components | dicomweb-client |
| FR references | FR-RAD-001 |
| Legacy FR refs | FR-RAD-001 |
| Dependencies | RAD-US-001 |
User story: As the system, when a study is registered, I want to query the PACS via QIDO-RS to retrieve series/instance counts and study metadata so that clinicians see accurate information.
Acceptance criteria (Gherkin):
- Given a registered study and reachable PACS, when QIDO-RS is queried, then
series_countandinstance_countare updated and status becomesavailable. - Given PACS returns 503, when queried, then retry with exponential backoff; study remains
registered; alert after 3 failures.
Technical notes:
- Scheduled retry via NATS worker; DICOMweb QIDO-RS adapter
Definition of Done:
- Integration test with Orthanc mock; PACS failure test; docs updated.
RAD-US-004 — Submit preliminary radiology report
| Field | Value |
|---|---|
| Issue type | Story |
| Summary | Radiologist submits a preliminary report for a study |
| Epic link | RAD-EPIC-02 |
| Status | To Do |
| Priority | Must |
| Story points | 5 |
| Labels | service:radiology, type:backend, slice:S1 |
| Components | reports |
| FR references | FR-RAD-003, FR-RAD-004 |
| Legacy FR refs | FR-RAD-003 |
| Dependencies | RAD-US-002 |
User story: As an on-call radiologist, when I review an urgent study, I want to submit a preliminary report so that the ordering clinician has an early read while I complete my full analysis.
Acceptance criteria (Gherkin):
- Given a registered study, when I POST a preliminary report, then status becomes
preliminaryanddiag.radiology.report.receivedis published. - Given a study with existing final report, when I submit prelim, then 409 returned — prelim cannot follow final.
Technical notes:
POST /v1/radiology/studies/{studyId}/reportswithstatus: "preliminary"
Definition of Done:
- Unit + integration tests; docs updated.
RAD-US-005 — Sign and finalize radiology report
| Field | Value |
|---|---|
| Issue type | Story |
| Summary | Radiologist signs a report, filing it as the final authoritative read |
| Epic link | RAD-EPIC-02 |
| Status | To Do |
| Priority | Must |
| Story points | 5 |
| Labels | service:radiology, type:backend, slice:S1 |
| Components | reports, fhir-publish |
| FR references | FR-RAD-004 |
| Legacy FR refs | FR-RAD-004 |
| Dependencies | RAD-US-004 |
User story: As a radiologist, when I complete my analysis, I want to sign the report so that it becomes the final authoritative read and is filed to the patient chart.
Acceptance criteria (Gherkin):
- Given a preliminary report, when I sign it, then status becomes
final, FHIRDiagnosticReportis created, anddiag.radiology.report.signedis published. - Given the sign action with
criticalFindingFlag=true, when processed, thendiag.radiology.finding.criticalis additionally published. - Given an already-final report, when sign is called, then 409 — must amend.
Technical notes:
POST /v1/radiology/reports/{id}/sign; outbox for FHIR publish
Definition of Done:
- Integration test for full sign flow; outbox.spec.ts; FHIR conformance; docs updated.
RAD-US-006 — Amend a final report
| Field | Value |
|---|---|
| Issue type | Story |
| Summary | Radiologist submits an amendment to a final report |
| Epic link | RAD-EPIC-02 |
| Status | To Do |
| Priority | Must |
| Story points | 3 |
| Labels | service:radiology, type:backend, slice:S1 |
| Components | reports |
| FR references | FR-RAD-004 |
| Legacy FR refs | FR-RAD-004 |
| Dependencies | RAD-US-005 |
User story: As a radiologist, when I need to correct or supplement a final report, I want to submit an amendment so that the updated finding is available and the prior version is preserved.
Acceptance criteria (Gherkin):
- Given a final report, when I amend it with reason, then a new report version is created and the prior version's status becomes
superseded. - Given a preliminary report (not final), when amend is attempted, then
RAD_REPORT_NOT_FINAL409 returned.
Technical notes:
POST /v1/radiology/reports/{id}/amend;amendmentReasonrequired
Definition of Done:
- Unit test for amendment chain; integration test; docs updated.
RAD-US-007 — Launch imaging viewer from EHR
| Field | Value |
|---|---|
| Issue type | Story |
| Summary | Clinician launches imaging viewer with a signed token |
| Epic link | RAD-EPIC-03 |
| Status | To Do |
| Priority | Must |
| Story points | 5 |
| Labels | service:radiology, type:backend, slice:S1 |
| Components | viewer-launch |
| FR references | FR-RAD-002 |
| Legacy FR refs | FR-RAD-002 |
| Dependencies | RAD-US-002, cross-service: IDENT-US-001 |
User story: As a clinician, when I open the imaging tab for a patient, I want to launch the imaging viewer with one click so that I can view the DICOM images without separate login.
Acceptance criteria (Gherkin):
- Given a clinician with access to the patient, when they POST to viewer-launch, then a signed token + viewer URL is returned.
- Given a clinician without patient access, when they attempt viewer launch, then 403
RAD_ACCESS_DENIEDis returned. - Given a token, when it expires after TTL, then it is rejected by the viewer.
Technical notes:
POST /v1/radiology/studies/{id}/viewer-launch; ABAC check via access-policy-service; HS256 signed JWT
Definition of Done:
- Integration test with ABAC mock; token expiry test; audit event verified; docs updated.
RAD-US-008 — Viewer launch audit logging
| Field | Value |
|---|---|
| Issue type | Story |
| Summary | All viewer launches are recorded in audit log |
| Epic link | RAD-EPIC-03 |
| Status | To Do |
| Priority | Must |
| Story points | 2 |
| Labels | service:radiology, type:backend, slice:S1 |
| Components | audit |
| FR references | FR-RAD-002 |
| Legacy FR refs | FR-RAD-002 |
| Dependencies | RAD-US-007 |
User story: As a compliance officer, when a viewer launch occurs, I want it recorded in the audit log so that access to imaging can be reviewed.
Acceptance criteria (Gherkin):
- Given a successful viewer launch, when processed, then
rad.viewer.launchedaudit event published withactorId,studyId,patientId,tenantId. - Given a failed launch (ABAC denial), when attempted, then
rad.viewer.launch_deniedaudit event published.
Technical notes:
- Audit events published via
IAuditPort→ audit-service
Definition of Done:
- Integration test; audit event schema conformance test; docs updated.
RAD-US-009 — Flag critical finding on report
| Field | Value |
|---|---|
| Issue type | Story |
| Summary | Radiologist flags a critical finding when signing a report |
| Epic link | RAD-EPIC-04 |
| Status | To Do |
| Priority | Must |
| Story points | 3 |
| Labels | service:radiology, type:backend, slice:S1 |
| Components | critical-findings |
| FR references | FR-RAD-005 |
| Legacy FR refs | FR-RAD-005 |
| Dependencies | RAD-US-005 |
User story: As a radiologist, when I identify a critical finding, I want to flag it on the report so that an urgent notification is dispatched to the ordering clinician.
Acceptance criteria (Gherkin):
- Given a report signed with
criticalFindingFlag: true, when processed, thendiag.radiology.finding.criticalis published with finding summary. - Given no critical finding, when report signed, then no critical event published.
Technical notes:
criticalFindingFlagfield on report sign/ingest; outbox for event
Definition of Done:
- Integration test; event schema conformance; docs updated.
RAD-US-010 — View imaging studies list for patient
| Field | Value |
|---|---|
| Issue type | Story |
| Summary | Clinician views all imaging studies for a patient with report status |
| Epic link | RAD-EPIC-03 |
| Status | To Do |
| Priority | Must |
| Story points | 3 |
| Labels | service:radiology, type:backend, slice:S0 |
| Components | study-metadata |
| FR references | FR-RAD-001 |
| Legacy FR refs | FR-RAD-001 |
| Dependencies | RAD-US-002 |
User story: As a clinician, when I open a patient's imaging tab, I want to see a list of all imaging studies with modality, date, and report status so that I can quickly find relevant results.
Acceptance criteria (Gherkin):
- Given a patient with 3 CT studies, when I query, then all 3 are returned with modality, date, and current report status.
- Given a study with no report yet, when listed, then
reportStatus: nullis returned. - Given the query, when executed, then p95 response < 2 s.
Technical notes:
GET /v1/radiology/studies?patientId={id}
Definition of Done:
- Performance test; integration test; docs updated.
RAD-US-011 — Radiologist worklist
| Field | Value |
|---|---|
| Issue type | Story |
| Summary | Radiologist views pending studies needing a report |
| Epic link | RAD-EPIC-05 |
| Status | To Do |
| Priority | Should |
| Story points | 3 |
| Labels | service:radiology, type:backend, slice:S2 |
| Components | worklist |
| FR references | FR-RAD-001 |
| Legacy FR refs | FR-RAD-001 |
| Dependencies | RAD-US-002 |
User story: As a radiologist, when I start my shift, I want to see a worklist of studies awaiting reporting so that I can work through them in priority order.
Acceptance criteria (Gherkin):
- Given studies in
registeredorpreliminarystatus, when I query the worklist, then they are returned sorted by study date ascending (oldest first). - Given a study with a final report, when queried, then it does not appear in the worklist.
Technical notes:
GET /v1/radiology/worklist?status=registered&modality=CT
Definition of Done:
- Integration test; docs updated.