Struct ClinicalService

pub struct ClinicalService<S> { /* private fields */ }

Service for managing clinical record operations.

This service uses the type-state pattern to enforce correct usage at compile time. The generic parameter S can be either Uninitialised or Initialised, determining which operations are available.

Type States

• ClinicalService<Uninitialised> - Created via new(). Can only call initialise().

• ClinicalService<Initialised> - Created via with_id() or returned from initialise(). Can call operations like link_to_demographics().

Implementations

impl ClinicalService<Uninitialised>

pub fn new(cfg: Arc<CoreConfig>) -> Self

Creates a new ClinicalService in the uninitialised state.

This is the starting point for creating a new clinical record. The returned service can only call initialise() to create the record.

Arguments

• cfg - The core configuration containing paths, templates, and system settings.

Returns

A ClinicalService<Uninitialised> ready to initialise a new clinical record.

impl ClinicalService<Initialised>

pub fn with_id(cfg: Arc<CoreConfig>, clinical_id: Uuid) -> Self

Creates a ClinicalService in the initialised state with an existing clinical ID.

Use this when you already have a clinical record and want to perform operations on it, such as linking to demographics or updating the EHR status.

Arguments

• cfg - The core configuration containing paths, templates, and system settings.
• clinical_id - The UUID of an existing clinical record.

Returns

A ClinicalService<Initialised> ready to operate on the specified clinical record.

Note

This constructor does not validate that the clinical record actually exists. Operations on a non-existent record will fail at runtime.

pub fn clinical_id(&self) -> Uuid

Returns the clinical ID for this initialised service.

Returns

The UUID of the clinical record associated with this service.

impl ClinicalService<Uninitialised>

pub fn initialise( self, author: Author, care_location: NonEmptyText, ) -> PatientResult<ClinicalService<Initialised>>

Initialises a new clinical record for a patient.

This function creates a new clinical entry with a unique UUID, stores it in a sharded directory structure, copies the clinical template into the patient’s directory, writes an initial ehr_status.yaml, and initialises a Git repository for version control.

This method consumes self and returns a new ClinicalService<Initialised> on success, enforcing at compile time that you cannot call initialise() twice on the same service.

Arguments

• author - The author information for the initial Git commit. Must have a non-empty name.
• care_location - High-level organisational location for the commit (e.g. hospital name). Must be a non-empty string.

Returns

Returns ClinicalService<Initialised> containing the newly created clinical record. Use clinical_id() to get the UUID.

Errors

Returns a PatientError if:

• The author’s name is empty or whitespace-only (PatientError::MissingAuthorName)
• The care location is empty or whitespace-only (PatientError::MissingCareLocation)
• Required inputs or configuration are invalid (PatientError::InvalidInput)
• The clinical template cannot be located or is invalid
• A unique patient directory cannot be allocated after 5 attempts
• File or directory operations fail while creating the record or copying templates (PatientError::FileWrite)
• Writing ehr_status.yaml fails
• Git repository initialisation fails (e.g., PatientError::GitInit)
• The initial commit fails (e.g., certificate/signature mismatch)
• Cleanup of a partially-created record directory fails (PatientError::CleanupAfterInitialiseFailed)

impl ClinicalService<Initialised>

pub fn link_to_demographics( &self, author: &Author, care_location: NonEmptyText, demographics_uuid: &str, namespace: Option<NonEmptyText>, ) -> PatientResult<()>

Links the clinical record to the patient’s demographics.

This function updates the clinical record’s ehr_status.yaml file to include an external reference to the patient’s demographics record.

The clinical UUID is obtained from the service’s internal state (via clinical_id()), ensuring type safety and preventing mismatched UUIDs.

Arguments

• author - The author information for the Git commit recording this change. Must have a non-empty name.
• care_location - High-level organisational location for the commit (e.g. hospital name). Must be a non-empty string.
• demographics_uuid - The UUID of the associated patient demographics record. Must be a canonical 32-character lowercase hex string.
• namespace - Optional namespace for the external reference URI. If None, uses the value configured in CoreConfig. The namespace must be URI-safe (no special characters like <, >, /, \).

Returns

Returns Ok(()) on success. The ehr_status.yaml file is updated and committed to Git.

Errors

Returns a PatientError if:

• The author’s name is empty or whitespace-only (PatientError::MissingAuthorName)
• The care location is empty or whitespace-only (PatientError::MissingCareLocation)
• The demographics UUID cannot be parsed (PatientError::Uuid)
• The namespace is invalid/unsafe for embedding into a ehr://{namespace}/mpi URI (PatientError::InvalidInput)
• The ehr_status.yaml file does not exist (PatientError::InvalidInput)
• Reading or writing ehr_status.yaml fails (PatientError::FileRead or PatientError::FileWrite)
• The existing ehr_status.yaml cannot be parsed (PatientError::Openehr)
• Git commit fails (various Git-related error variants)

Safety & Rollback

If the file write or Git commit fails, this method attempts to restore the previous content of ehr_status.yaml.

pub fn create_letter( &self, author: &Author, care_location: NonEmptyText, body_content: Option<NonEmptyText>, attachment_files: &[PathBuf], clinical_lists: Option<&[ClinicalList]>, ) -> PatientResult<TimestampId>

Creates a new clinical letter with optional body and/or attachments.

This is the unified function for creating letters with any combination of:

• Body content only (markdown text saved as body.md)
• Attachments only (files stored via FilesService)
• Both body content AND attachments

At least one of body_content or attachment_files must be provided.

Arguments

• author - The author information for the Git commit. Must have a non-empty name.
• care_location - High-level organisational location for the commit (e.g. hospital name). Must be a non-empty string.
• body_content - Optional Markdown content for the letter body (body.md).
• attachment_files - Paths to files to attach (e.g., PDFs, images). Can be empty.
• clinical_lists - Optional clinical lists to include in the composition.

Returns

Returns the generated timestamp ID for the letter on success.

Errors

Returns a PatientError if:

• Both body_content and attachment_files are empty/None
• The author’s name is empty or whitespace-only
• The care location is empty or whitespace-only
• The clinical UUID cannot be parsed
• Any attachment file cannot be read or stored
• Creating the composition.yaml content fails
• Writing files or committing to Git fails

pub fn new_letter( &self, author: &Author, care_location: NonEmptyText, letter_content: NonEmptyText, clinical_lists: Option<&[ClinicalList]>, ) -> PatientResult<TimestampId>

Creates a new clinical letter with body content.

This is a convenience wrapper around create_letter for the common case of creating a letter with only body content.

Arguments

• author - The author information for the Git commit.
• care_location - High-level organisational location for the commit.
• letter_content - The Markdown content for the letter body.
• clinical_lists - Optional clinical lists to include.

Returns

Returns the generated timestamp ID for the letter on success.

This function creates a new letter with the specified content, generates a unique timestamp-based ID, and commits both the composition.yaml and body.md files to Git.

Arguments

• author - The author information for the Git commit. Must have a non-empty name.
• care_location - High-level organisational location for the commit (e.g. hospital name). Must be a non-empty string.
• letter_content - The Markdown content for the letter body (body.md).

Returns

Returns the generated timestamp ID for the letter on success.

Errors

Returns a PatientError if:

• The author’s name is empty or whitespace-only
• The care location is empty or whitespace-only
• The clinical UUID cannot be parsed
• Creating the composition.yaml content fails
• Writing files or committing to Git fails

pub fn read_letter(&self, timestamp_id: &str) -> PatientResult<ReadLetterResult>

Reads an existing clinical letter.

This function reads both the body.md and composition.yaml files for a letter, parses the composition metadata, and returns them together.

Arguments

• timestamp_id - The timestamp ID of the letter to read.

Returns

Returns a ReadLetterResult containing both the body content and parsed letter data.

Errors

Returns a PatientError if:

• The timestamp ID cannot be parsed
• The clinical UUID cannot be parsed
• The body.md or composition.yaml file does not exist
• Reading either file fails
• Parsing the composition.yaml fails

pub fn get_letter_attachments( &self, timestamp_id: &str, ) -> PatientResult<Vec<LetterAttachment>>

Retrieves all attachments for a clinical letter.

This function reads all attachment metadata files from the letter’s attachments directory and retrieves the actual file content from storage.

Arguments

• timestamp_id - The timestamp ID of the letter.

Returns

Returns a vector of LetterAttachment containing metadata and file content for each attachment.

Errors

Returns a PatientError if:

• The timestamp ID cannot be parsed
• The clinical UUID cannot be parsed
• The attachments directory does not exist or cannot be read
• Any attachment metadata file cannot be read or parsed
• Any file cannot be retrieved from storage

pub fn new_letter_with_attachments( &self, author: &Author, care_location: NonEmptyText, attachment_files: &[PathBuf], clinical_lists: Option<&[ClinicalList]>, ) -> PatientResult<TimestampId>

Creates a new clinical letter with file attachments.

This is a convenience wrapper around create_letter for creating a letter with only attachments (no body content).

Arguments

• author - The author information for the Git commit.
• care_location - High-level organisational location for the commit.
• attachment_files - Paths to files to attach (e.g., PDFs, images).
• clinical_lists - Optional clinical lists to include.

Returns

Returns the generated timestamp ID for the letter on success.

Trait Implementations

impl<S: Clone> Clone for ClinicalService<S>

fn clone(&self) -> ClinicalService<S>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<S: Debug> Debug for ClinicalService<S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.