feat: implement attendance analytics and reporting functions

contracts/common_types/src/lib.rs

@@ -9,10 +9,11 @@ mod types;
 
 // Re-export all types
 pub use types::{
-    validate_attribute, validate_metadata, AttendanceAction, MembershipStatus, MetadataUpdate,
-    MetadataValue, SubscriptionPlan, SubscriptionTier, TierChangeRequest, TierChangeStatus,
-    TierChangeType, TierFeature, TierLevel, TierPromotion, TokenMetadata, UserRole,
-    MAX_ATTRIBUTES_COUNT, MAX_ATTRIBUTE_KEY_LENGTH, MAX_DESCRIPTION_LENGTH, MAX_TEXT_VALUE_LENGTH,
+    validate_attribute, validate_metadata, AttendanceAction, AttendanceFrequency, DateRange,
+    DayPattern, MembershipStatus, MetadataUpdate, MetadataValue, PeakHourData, SubscriptionPlan,
+    SubscriptionTier, TierChangeRequest, TierChangeStatus, TierChangeType, TierFeature, TierLevel,
+    TierPromotion, TimePeriod, TokenMetadata, UserAttendanceStats, UserRole, MAX_ATTRIBUTES_COUNT,
+    MAX_ATTRIBUTE_KEY_LENGTH, MAX_DESCRIPTION_LENGTH, MAX_TEXT_VALUE_LENGTH,
 };
 
 #[cfg(test)]

contracts/common_types/src/types.rs

@@ -183,6 +183,146 @@ pub enum MembershipStatus {
     Inactive,
 }
 
+// ============================================================================
+// Attendance Analytics Types
+// ============================================================================
+
+/// Time period options for analytics queries.
+///
+/// Used to group and filter attendance data by specific time ranges.
+///
+/// # Variants
+/// * `Daily` - Daily aggregation
+/// * `Weekly` - Weekly aggregation
+/// * `Monthly` - Monthly aggregation
+/// * `Custom` - Custom date range
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum TimePeriod {
+    /// Daily time period
+    Daily,
+    /// Weekly time period
+    Weekly,
+    /// Monthly time period
+    Monthly,
+    /// Custom date range
+    Custom,
+}
+
+/// Date range structure for filtering attendance records.
+///
+/// Specifies a time window for querying attendance data.
+///
+/// # Fields
+/// * `start_time` - Start timestamp (inclusive)
+/// * `end_time` - End timestamp (inclusive)
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct DateRange {
+    /// Start timestamp
+    pub start_time: u64,
+    /// End timestamp
+    pub end_time: u64,
+}
+
+/// Aggregated attendance statistics for a user.
+///
+/// Contains comprehensive attendance metrics including duration,
+/// frequency, and pattern analysis.
+///
+/// # Fields
+/// * `user_id` - User address
+/// * `total_sessions` - Total number of attendance sessions
+/// * `total_duration` - Total time spent (seconds)
+/// * `average_duration` - Average session duration (seconds)
+/// * `first_clock_in` - Timestamp of first attendance
+/// * `last_clock_out` - Timestamp of last departure
+/// * `total_days_present` - Number of unique days with attendance
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct UserAttendanceStats {
+    /// User address
+    pub user_id: Address,
+    /// Total attendance sessions
+    pub total_sessions: u32,
+    /// Total duration in seconds
+    pub total_duration: u64,
+    /// Average session duration in seconds
+    pub average_duration: u64,
+    /// First clock-in timestamp
+    pub first_clock_in: u64,
+    /// Last clock-out timestamp
+    pub last_clock_out: u64,
+    /// Total unique days present
+    pub total_days_present: u32,
+}
+
+/// Attendance frequency metrics for a specific time period.
+///
+/// Tracks attendance frequency patterns and distribution.
+///
+/// # Fields
+/// * `period` - Time period type
+/// * `period_start` - Period start timestamp
+/// * `period_end` - Period end timestamp
+/// * `total_attendances` - Total attendance records in period
+/// * `unique_users` - Number of unique users
+/// * `average_daily_attendance` - Average attendances per day
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct AttendanceFrequency {
+    /// Time period
+    pub period: TimePeriod,
+    /// Period start timestamp
+    pub period_start: u64,
+    /// Period end timestamp
+    pub period_end: u64,
+    /// Total attendance records
+    pub total_attendances: u32,
+    /// Unique users count
+    pub unique_users: u32,
+    /// Average daily attendance
+    pub average_daily_attendance: u32,
+}
+
+/// Peak hour analysis data.
+///
+/// Identifies hours and days with highest attendance activity.
+///
+/// # Fields
+/// * `hour` - Hour of day (0-23)
+/// * `attendance_count` - Number of attendances in this hour
+/// * `percentage` - Percentage of total attendances
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct PeakHourData {
+    /// Hour of day (0-23)
+    pub hour: u32,
+    /// Attendance count
+    pub attendance_count: u32,
+    /// Percentage of total
+    pub percentage: u32,
+}
+
+/// Daily attendance pattern data.
+///
+/// Tracks attendance distribution across days of the week.
+///
+/// # Fields
+/// * `day_of_week` - Day (0=Sunday, 6=Saturday)
+/// * `attendance_count` - Number of attendances on this day
+/// * `percentage` - Percentage of total attendances
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct DayPattern {
+    /// Day of week (0=Sunday, 6=Saturday)
+    pub day_of_week: u32,
+    /// Attendance count
+    pub attendance_count: u32,
+    /// Percentage of total
+    pub percentage: u32,
+}
+
 // ============================================================================
 // Subscription Tier Types
 // ============================================================================