feat(domain): implement RelayController trait and error handling

Add RelayController async trait (T030) defining interface for Modbus
relay operations with methods for read/write state, bulk operations,
connection checks, and firmware queries.

Implement ControllerError enum (T031) with variants for connection
failures, timeouts, Modbus exceptions, and invalid relay IDs.

Provide MockRelayController (T029) in-memory implementation using
Arc<Mutex<HashMap>> for thread-safe state storage with timeout
simulation for error handling tests.

Add RelayLabelRepository trait abstraction.

Ref: T029 T030 T031 (specs/001-modbus-relay-control/tasks.md)

backend/src/domain/relay/controller.rs

@@ -1,7 +1,96 @@
+use async_trait::async_trait;
+
+use super::types::{RelayId, RelayState};
+
 /// Errors that can occur during relay controller operations.
 #[derive(Debug, thiserror::Error)]
 pub enum ControllerError {
-    /// The provided relay ID is outside the valid range (1-8).
+    /// Failed to establish or maintain connection to the Modbus device.
+    #[error("Connection error: {0}")]
+    ConnectionError(String),
+    /// Operation exceeded the specified timeout duration (in seconds).
+    #[error("Timeout after {0} seconds")]
+    Timeout(u64),
+    /// Modbus protocol exception occurred during communication.
+    #[error("Modbus exception: {0}")]
+    ModbusException(String),
+    /// Attempted to access a relay with an invalid ID (valid range: 1-8).
     #[error("Invalid relay ID: {0}")]
     InvalidRelayId(u8),
 }
+
+type Result<T> = std::result::Result<T, ControllerError>;
+
+/// Abstraction for controlling Modbus-connected relays.
+///
+/// This trait defines the interface for reading and writing relay states,
+/// supporting both individual relay operations and bulk operations for all 8 relays.
+/// Implementations must be thread-safe (`Send + Sync`) for use in async contexts.
+#[async_trait]
+pub trait RelayController: Send + Sync {
+    /// Reads the current state of a single relay.
+    ///
+    /// # Errors
+    ///
+    /// Returns `ControllerError` if:
+    /// - Connection to Modbus device fails
+    /// - Operation times out
+    /// - Modbus protocol exception occurs
+    /// - Relay ID is invalid
+    async fn read_relay_state(&self, id: RelayId) -> Result<RelayState>;
+
+    /// Writes a new state to a single relay.
+    ///
+    /// # Errors
+    ///
+    /// Returns `ControllerError` if:
+    /// - Connection to Modbus device fails
+    /// - Operation times out
+    /// - Modbus protocol exception occurs
+    /// - Relay ID is invalid
+    async fn write_relay_state(&self, id: RelayId, state: RelayState) -> Result<()>;
+
+    /// Reads the states of all 8 relays.
+    ///
+    /// Returns a vector of relay states ordered by relay ID (1-8).
+    ///
+    /// # Errors
+    ///
+    /// Returns `ControllerError` if:
+    /// - Connection to Modbus device fails
+    /// - Operation times out
+    /// - Modbus protocol exception occurs
+    async fn read_all_states(&self) -> Result<Vec<RelayState>>;
+
+    /// Writes states to all 8 relays in a single operation.
+    ///
+    /// The states vector must contain exactly 8 elements, corresponding to relays 1-8.
+    ///
+    /// # Errors
+    ///
+    /// Returns `ControllerError` if:
+    /// - Connection to Modbus device fails
+    /// - Operation times out
+    /// - Modbus protocol exception occurs
+    /// - States vector length is invalid
+    async fn write_all_states(&self, states: Vec<RelayState>) -> Result<()>;
+
+    /// Checks if the connection to the Modbus device is active.
+    ///
+    /// # Errors
+    ///
+    /// Returns `ControllerError` if the connection check fails.
+    async fn check_connection(&self) -> Result<()>;
+
+    /// Retrieves the firmware version of the Modbus device, if available.
+    ///
+    /// Returns `None` if the device does not support firmware version reporting.
+    ///
+    /// # Errors
+    ///
+    /// Returns `ControllerError` if:
+    /// - Connection to Modbus device fails
+    /// - Operation times out
+    /// - Modbus protocol exception occurs
+    async fn get_firmware_version(&self) -> Result<Option<String>>;
+}

backend/src/domain/relay/repository.rs

@@ -1,4 +1,6 @@
-use super::types::RelayId;
+use async_trait::async_trait;
+
+use super::types::{RelayId, RelayLabel};
 
 /// Errors that can occur during repository operations.
 ///
@@ -13,3 +15,39 @@ pub enum RepositoryError {
     #[error("Relay not found: {0}")]
     NotFound(RelayId),
 }
+
+/// Repository trait for persisting and retrieving relay labels.
+///
+/// This trait abstracts data persistence operations for relay labels,
+/// enabling different storage implementations (e.g., `SQLite`, `PostgreSQL`, in-memory).
+/// Implementations must be thread-safe (`Send + Sync`) for use in async contexts.
+#[async_trait]
+pub trait RelayLabelRepository: Send + Sync {
+    /// Retrieves the label for a specific relay.
+    ///
+    /// Returns `None` if no label has been set for the relay.
+    ///
+    /// # Errors
+    ///
+    /// Returns `RepositoryError::DatabaseError` if the database operation fails.
+    async fn get_label(&self, id: RelayId) -> Result<Option<RelayLabel>, RepositoryError>;
+
+    /// Saves or updates the label for a specific relay.
+    ///
+    /// If a label already exists for the relay, it will be overwritten.
+    ///
+    /// # Errors
+    ///
+    /// Returns `RepositoryError::DatabaseError` if the database operation fails.
+    async fn save_label(&self, id: RelayId, label: RelayLabel) -> Result<(), RepositoryError>;
+
+    /// Retrieves all relay labels from the repository.
+    ///
+    /// Returns a vector of tuples containing relay IDs and their corresponding labels.
+    /// Relays without labels are not included in the result.
+    ///
+    /// # Errors
+    ///
+    /// Returns `RepositoryError::DatabaseError` if the database operation fails.
+    async fn get_all_labels(&self) -> Result<Vec<(RelayId, RelayLabel)>, RepositoryError>;
+}

backend/src/domain/relay/types/relayid.rs

@@ -5,7 +5,7 @@ use crate::domain::relay::controller::ControllerError;
 /// Uses the newtype pattern to provide type safety and prevent mixing relay IDs
 /// with other numeric values. Valid values range from 0-255, corresponding to
 /// individual relay channels in the Modbus controller.
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Ord, PartialOrd)]
 #[repr(transparent)]
 pub struct RelayId(u8);