init

enriched-qwen3-coder-next/Common/DTS.Common/Events/DTS.Viewer/Reports.md

@@ -0,0 +1,65 @@
+---
+source_files:
+  - Common/DTS.Common/Events/DTS.Viewer/Reports/SaveReportToCSVRequestedEvent.cs
+  - Common/DTS.Common/Events/DTS.Viewer/Reports/SaveReportToPDFRequestedEvent.cs
+generated_at: "2026-04-16T03:27:02.713322+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "c23355273750380a"
+---
+
+# Reports
+
+## Documentation: Report Export Request Events
+
+### 1. Purpose  
+This module defines Prism-based pub/sub events used to signal user-initiated requests to export report data to external formats—specifically CSV and PDF. These events decouple the UI layer (e.g., a report viewer control or dialog) from the export implementation logic, enabling loose coupling and testability in the MVVM pattern. When a user selects "Save as CSV" or "Save as PDF", the UI publishes the corresponding event, and a dedicated handler (e.g., in a service or view model) subscribes to perform the actual file I/O and export processing.
+
+### 2. Public Interface  
+
+- **`SaveReportToCSVRequestedEvent`**  
+  *Type:* `class` inheriting from `PubSubEvent<SaveReportToCSVRequestedEventArgs>`  
+  *Behavior:* A Prism event used to publish requests to save a report to CSV format. Subscribers receive an instance of `SaveReportToCSVRequestedEventArgs` containing the target directory and parent view model context.
+
+- **`SaveReportToCSVRequestedEventArgs`**  
+  *Type:* `class`  
+  *Properties:*  
+  - `Directory` (`string`): The file system directory where the CSV file should be saved.  
+  - `ParentVM` (`IBaseViewModel`): The view model that initiated or owns the report context (e.g., the active report view model). Used for context-aware operations (e.g., resolving data sources or parent window handles).  
+
+- **`SaveReportToPDFRequestedEvent`**  
+  *Type:* `class` inheriting from `PubSubEvent<SaveReportToPDFRequestedEventArgs>`  
+  *Behavior:* A Prism event used to publish requests to save a report to PDF format. Subscribers receive an instance of `SaveReportToPDFRequestedEventArgs` with the same payload structure as the CSV variant.
+
+- **`SaveReportToPDFRequestedEventArgs`**  
+  *Type:* `class`  
+  *Properties:*  
+  - `Directory` (`string`): The file system directory where the PDF file should be saved.  
+  - `ParentVM` (`IBaseViewModel`): The view model that initiated or owns the report context.  
+
+> **Note:** Both event argument classes are *mutable* (public setters on properties) and lack validation or immutability guarantees.
+
+### 3. Invariants  
+- The `Directory` property in both argument types is expected to be a valid, writable file system path at the time of event publication.  
+- The `ParentVM` property is expected to be non-null at event publication; however, no explicit null-checking or enforcement is present in the event argument classes themselves.  
+- Events are published *before* export logic executes (i.e., they are request triggers, not completion notifications).  
+- No ordering guarantees exist between multiple subscribers—concurrent or conflicting writes to the same path are possible if not handled by subscribers.
+
+### 4. Dependencies  
+- **Internal Dependencies:**  
+  - `DTS.Common.Base.IBaseViewModel`: Defines the contract for view models used in the parent context.  
+  - `Prism.Events.PubSubEvent<T>`: Prism’s event aggregation infrastructure.  
+- **External Dependencies:**  
+  - `System` and `System.Collections.Generic`, `System.Linq`, `System.Text`, `System.Threading.Tasks`: Standard .NET libraries.  
+- **Consumers (inferred):**  
+  - UI components (e.g., report viewer controls) that publish these events on user action.  
+  - Export service classes or view models that subscribe to these events to handle file generation.  
+  - Likely used in conjunction with `IBaseViewModel` implementations that expose report data and coordinate with export services.
+
+### 5. Gotchas  
+- **No filename specification:** The event arguments only provide a *directory*, not a filename. Subscribers must derive filenames (e.g., via timestamp, report name from `ParentVM`, or user input), which may lead to inconsistent naming or overwrites if not handled carefully.  
+- **No cancellation support:** Events lack a mechanism to signal cancellation (e.g., via `CancellationToken`) or to abort the operation mid-process.  
+- **No error propagation:** Exceptions thrown by subscribers are not captured or propagated back to the publisher; error handling must be implemented entirely within subscribers.  
+- **No format-specific metadata:** Arguments do not include export options (e.g., CSV delimiter, PDF page size, inclusion of headers). Subscribers must hardcode or infer such settings.  
+- **Mutable payload:** Since `Directory` and `ParentVM` have public setters, subscribers could inadvertently modify the event args—though this is unlikely to be intentional.  
+- **None identified from source alone.**