kasl/libs/pause.rs
1//! Pause data management and formatting utilities.
2//!
3//! Provides the core data structures and formatting functionality for handling
4//! break periods detected by the activity monitor.
5//!
6//! ## Features
7//!
8//! - **Data Modeling**: Represents pause periods with precise timing information
9//! - **Display Formatting**: Converts raw pause data into human-readable formats
10//! - **Collection Processing**: Batch operations on pause collections
11//! - **Report Integration**: Provides data structures suitable for reporting systems
12//!
13//! ## Usage
14//!
15//! ```rust,no_run
16//! use kasl::libs::pause::Pause;
17//! use chrono::{NaiveDateTime, Duration};
18//!
19//! let pause = Pause {
20//! id: 1,
21//! start: NaiveDateTime::parse_from_str("2025-08-11 09:15:00", "%Y-%m-%d %H:%M:%S")?,
22//! end: Some(NaiveDateTime::parse_from_str("2025-08-11 09:30:00", "%Y-%m-%d %H:%M:%S")?),
23//! duration: Some(Duration::minutes(15)),
24//! };
25//! ```
26
27use chrono::{Duration, prelude::NaiveDateTime};
28
29/// Represents a single pause period with complete timing information.
30///
31/// This structure models a break period detected by the activity monitor,
32/// containing all necessary information for analysis, reporting, and display.
33/// It handles both active (ongoing) and completed pause periods gracefully.
34///
35/// ## Field Semantics
36///
37/// - **`id`**: Unique database identifier for pause tracking and updates
38/// - **`start`**: Precise timestamp when inactivity threshold was reached
39/// - **`end`**: Completion timestamp (None for ongoing pauses)
40/// - **`duration`**: Calculated break duration (None for ongoing pauses)
41///
42/// ## State Handling
43///
44/// The structure supports two primary states:
45///
46/// ### Completed Pause
47/// - All fields populated with meaningful values
48/// - `end` contains actual completion timestamp
49/// - `duration` contains calculated break duration
50/// - Ready for reporting and analysis
51///
52/// ### Ongoing Pause (Active)
53/// - `start` field contains pause initiation time
54/// - `end` field is None (pause still in progress)
55/// - `duration` field is None (cannot calculate until completion)
56/// - Can be displayed with special formatting for active state
57///
58/// ## Duration Calculation
59///
60/// Durations are calculated and stored at the database level for consistency:
61/// - **Precision**: Calculated to the second for accurate reporting
62/// - **Storage**: Stored as seconds in database, converted to Duration for display
63/// - **Consistency**: All duration calculations use same algorithm
64/// - **Timezone**: Uses local time for user-friendly display
65///
66/// ## Display Considerations
67///
68/// The structure is designed for easy formatting:
69/// - Timestamps use standard format suitable for parsing
70/// - Duration is compatible with `chrono::Duration` formatting utilities
71/// - None values are handled gracefully in display formatting
72/// - Supports both detailed and summary display modes
73#[derive(Debug, Clone)]
74pub struct Pause {
75 /// The unique identifier for the pause record in the database.
76 ///
77 /// This ID is auto-generated when the pause record is created and
78 /// serves as the primary key for all database operations. It's used
79 /// for updating pause records when they end and for referencing
80 /// specific pauses in reports and analysis.
81 pub id: i32,
82
83 /// The timestamp when the pause period began.
84 ///
85 /// This represents the precise moment when the activity monitor
86 /// detected that the user had been inactive for the configured
87 /// pause threshold duration. The timestamp uses local time zone
88 /// for user-friendly display and reporting.
89 ///
90 /// ## Precision
91 /// - Stored with second-level precision in the database
92 /// - Captured when inactivity threshold is first exceeded
93 /// - Uses system local time for consistency with user expectations
94 pub start: NaiveDateTime,
95
96 /// The timestamp when the pause period ended.
97 ///
98 /// This field is populated when user activity resumes after a break.
99 /// It remains None for ongoing pauses that haven't completed yet.
100 ///
101 /// ## State Semantics
102 /// - **Some(timestamp)**: Pause has completed, duration can be calculated
103 /// - **None**: Pause is still active, user hasn't returned yet
104 ///
105 /// ## Update Process
106 /// The field is updated when the monitor detects resumed activity:
107 /// 1. Activity monitor detects keyboard/mouse input
108 /// 2. Database record is updated with current timestamp
109 /// 3. Duration is calculated and stored simultaneously
110 pub end: Option<NaiveDateTime>,
111
112 /// The calculated duration of the pause period.
113 ///
114 /// This represents the total time the user was away from the computer
115 /// during this break period. The duration is calculated automatically
116 /// when the pause ends and stored for efficient reporting.
117 ///
118 /// ## Calculation Details
119 /// - **Formula**: `end_time - start_time`
120 /// - **Precision**: Second-level accuracy for detailed analysis
121 /// - **Storage**: Converted from seconds to Duration for easy manipulation
122 /// - **Filtering**: Only pauses meeting minimum duration are typically displayed
123 ///
124 /// ## None Handling
125 /// The field is None for ongoing pauses where the end time hasn't been
126 /// determined yet. Display formatting handles this gracefully by showing
127 /// placeholder values or real-time duration calculation.
128 pub duration: Option<Duration>,
129}