Initial import of the CBDDC codebase with docs and tests. Add a .NET-focused gitignore to keep generated artifacts out of source control.

src/ZB.MOM.WW.CBDDC.Core/Exceptions/CBDDCExceptions.cs

@@ -0,0 +1,189 @@
+using System;
+
+namespace ZB.MOM.WW.CBDDC.Core.Exceptions;
+
+/// <summary>
+/// Base exception for all CBDDC-related errors.
+/// </summary>
+public class CBDDCException : Exception
+{
+    /// <summary>
+    /// Error code for programmatic error handling.
+    /// </summary>
+    public string ErrorCode { get; }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="CBDDCException"/> class.
+    /// </summary>
+    /// <param name="errorCode">The application-specific error code.</param>
+    /// <param name="message">The exception message.</param>
+    public CBDDCException(string errorCode, string message)
+        : base(message)
+    {
+        ErrorCode = errorCode;
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="CBDDCException"/> class.
+    /// </summary>
+    /// <param name="errorCode">The application-specific error code.</param>
+    /// <param name="message">The exception message.</param>
+    /// <param name="innerException">The exception that caused the current exception.</param>
+    public CBDDCException(string errorCode, string message, Exception innerException)
+        : base(message, innerException)
+    {
+        ErrorCode = errorCode;
+    }
+}
+
+/// <summary>
+/// Exception thrown when network operations fail.
+/// </summary>
+public class NetworkException : CBDDCException
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="NetworkException"/> class.
+    /// </summary>
+    /// <param name="message">The exception message.</param>
+    public NetworkException(string message)
+        : base("NETWORK_ERROR", message) { }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="NetworkException"/> class.
+    /// </summary>
+    /// <param name="message">The exception message.</param>
+    /// <param name="innerException">The exception that caused the current exception.</param>
+    public NetworkException(string message, Exception innerException)
+        : base("NETWORK_ERROR", message, innerException) { }
+}
+
+/// <summary>
+/// Exception thrown when persistence operations fail.
+/// </summary>
+public class PersistenceException : CBDDCException
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="PersistenceException"/> class.
+    /// </summary>
+    /// <param name="message">The exception message.</param>
+    public PersistenceException(string message)
+        : base("PERSISTENCE_ERROR", message) { }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="PersistenceException"/> class.
+    /// </summary>
+    /// <param name="message">The exception message.</param>
+    /// <param name="innerException">The exception that caused the current exception.</param>
+    public PersistenceException(string message, Exception innerException)
+        : base("PERSISTENCE_ERROR", message, innerException) { }
+}
+
+/// <summary>
+/// Exception thrown when synchronization operations fail.
+/// </summary>
+public class SyncException : CBDDCException
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="SyncException"/> class.
+    /// </summary>
+    /// <param name="message">The exception message.</param>
+    public SyncException(string message)
+        : base("SYNC_ERROR", message) { }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="SyncException"/> class.
+    /// </summary>
+    /// <param name="message">The exception message.</param>
+    /// <param name="innerException">The exception that caused the current exception.</param>
+    public SyncException(string message, Exception innerException)
+        : base("SYNC_ERROR", message, innerException) { }
+}
+
+/// <summary>
+/// Exception thrown when configuration is invalid.
+/// </summary>
+public class ConfigurationException : CBDDCException
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ConfigurationException"/> class.
+    /// </summary>
+    /// <param name="message">The exception message.</param>
+    public ConfigurationException(string message)
+        : base("CONFIG_ERROR", message) { }
+}
+
+/// <summary>
+/// Exception thrown when database corruption is detected.
+/// </summary>
+public class DatabaseCorruptionException : PersistenceException
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DatabaseCorruptionException"/> class.
+    /// </summary>
+    /// <param name="message">The exception message.</param>
+    public DatabaseCorruptionException(string message)
+        : base(message) { }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DatabaseCorruptionException"/> class.
+    /// </summary>
+    /// <param name="message">The exception message.</param>
+    /// <param name="innerException">The exception that caused the current exception.</param>
+    public DatabaseCorruptionException(string message, Exception innerException)
+        : base(message, innerException) { }
+}
+
+/// <summary>
+/// Exception thrown when a timeout occurs.
+/// </summary>
+public class TimeoutException : CBDDCException
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="TimeoutException"/> class.
+    /// </summary>
+    /// <param name="operation">The operation that timed out.</param>
+    /// <param name="timeoutMs">The timeout in milliseconds.</param>
+    public TimeoutException(string operation, int timeoutMs)
+        : base("TIMEOUT_ERROR", $"Operation '{operation}' timed out after {timeoutMs}ms") { }
+}
+
+
+/// <summary>
+/// Exception thrown when a document is not found in a collection.
+/// </summary>
+public class DocumentNotFoundException : PersistenceException
+{
+    /// <summary>
+    /// Gets the document key that was not found.
+    /// </summary>
+    public string Key { get; }
+
+    /// <summary>
+    /// Gets the collection where the document was searched.
+    /// </summary>
+    public string Collection { get; }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DocumentNotFoundException"/> class.
+    /// </summary>
+    /// <param name="collection">The collection where the document was searched.</param>
+    /// <param name="key">The document key that was not found.</param>
+    public DocumentNotFoundException(string collection, string key)
+        : base($"Document with key '{key}' not found in collection '{collection}'.")
+    {
+        Collection = collection;
+        Key = key;
+    }
+}
+
+/// <summary>
+/// Exception thrown when a concurrency conflict occurs during persistence operations.
+/// </summary>
+public class CBDDCConcurrencyException : PersistenceException
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="CBDDCConcurrencyException"/> class.
+    /// </summary>
+    /// <param name="message">The exception message.</param>
+    public CBDDCConcurrencyException(string message) : base(message) { }
+}