Skip to main content

Fixed Time Attendance Computation Documentation

This code provides functions to compute attendance summaries for fixed-time shifts. It processes scan logs, applies rules, and calculates various attendance metrics such as breaks, overtime, and presence.

Constants​

const (
    SUMMARY_HEADER    string = "header"
    SUMMARY_SHIFT     string = "shift"
    SUMMARY_BREAK     string = "break"
    SUMMARY_INTERVAL  string = "interval"
    SUMMARY_OVERWRITE string = "overwrite"
    SUMMARY_TOTAL     string = "total"
)

SummaryScoreStruct struct​

type SummaryScoreStruct struct {
    DurationMinutes  int
    ScanCompleteness int // almost like percent : how many scanPoint hits / total ScanPoint * 1000 (like 78.29% == 7829) rounded
    PenaltiesMinutes int
    Distance         int
    Total            int
}
  • DurationMinutes int: The total duration in minutes.
  • ScanCompleteness int: The completeness of scan points.
  • PenaltiesMinutes int: The total penalties in minutes.
  • Distance int: The total distance of scan points.
  • Total int: The total score.

AttendanceSummariesCompute struct​

type AttendanceSummariesCompute struct {
    *entity.AttendanceSummariesTable

    DurationLessMoreActual float64 `json:"duration_less_more_actual"   db:"duration_less_more_actual"`
    DurationLessMoreRule   float64 `json:"duration_less_more_rule"     db:"duration_less_more_rule"`
    CiEarlyLateActual      float64 `json:"ci_early_late_actual"        db:"ci_early_late_actual"`
    CiEarlyLateRule        float64 `json:"ci_early_late_rule"          db:"ci_early_late_rule"`
    CoEarlyLateActual      float64 `json:"co_early_late_actual"        db:"co_early_late_actual"`
    CoEarlyLateRule        float64 `json:"co_early_late_rule"          db:"co_early_late_rule"`

    FromCalendarSchedule bool
    CannotCompute        map[string]string  // key=json-tag of each field. value=reason?
    Origin               map[string]string  // key=json-tag of the variable in AttendanceSummariesTable? value = rule_detail_id, if not empty means rule hit
    RulesHit             RulesHitStruct     // key = rule_detail_id
    ScanPoints           ScanPointMap       // only for fixed-time shift only
    Shift                *entity.ShiftTable // this include rules, in caching
    Score                SummaryScoreStruct
    Cache                *caching.AllCacheStruct
    Order                []ScanPointEvent
}
  • AttendanceSummariesTable *entity.AttendanceSummariesTable: The base attendance summaries table.
  • DurationLessMoreActual float64: The actual duration less or more.
  • DurationLessMoreRule float64: The rule-based duration less or more.
  • CiEarlyLateActual float64: The actual early or late check-in.
  • CiEarlyLateRule float64: The rule-based early or late check-in.
  • CoEarlyLateActual float64: The actual early or late check-out.
  • CoEarlyLateRule float64: The rule-based early or late check-out.
  • FromCalendarSchedule bool: Indicates if the summary is from a calendar schedule.
  • CannotCompute map[string]string: Reasons for not being able to compute certain fields.
  • Origin map[string]string: The origin of the values in the attendance summaries table.
  • RulesHit RulesHitStruct: The rules that were hit during computation.
  • ScanPoints ScanPointMap: The scan points for fixed-time shifts.
  • Shift *entity.ShiftTable: The shift table.
  • Score SummaryScoreStruct: The score for the summary.
  • Cache *caching.AllCacheStruct: The cache structure.
  • Order []ScanPointEvent: The order of scan point events.

Functions​

calculateScanPointsAndCreateBreaks​

func calculateScanPointsAndCreateBreaks(summary *AttendanceSummariesCompute, cache *caching.AllCacheStruct)

Calculates scan points and creates break details for a summary.

  • summary *AttendanceSummariesCompute: The attendance summary.
  • cache *caching.AllCacheStruct: The cache structure.

NewAttendanceSummariesComputeFromExisting​

func NewAttendanceSummariesComputeFromExisting(summaries []*entity.AttendanceSummariesTable, curUser *entity.UserProfileTable, force, cacheFollowForce bool, cache *caching.AllCacheStruct) []AttendanceSummariesCompute

Creates new attendance summaries from existing summaries.

  • summaries []*entity.AttendanceSummariesTable: The existing summaries.
  • curUser *entity.UserProfileTable: The current user profile.
  • force bool: Whether to force the computation.
  • cacheFollowForce bool: Whether to follow the cache force.
  • cache *caching.AllCacheStruct: The cache structure.

Returns a slice of AttendanceSummariesCompute.

NewAttendanceSummariesCompute​

func NewAttendanceSummariesCompute(curUser *entity.UserProfileTable, calcDate string, force, cacheFollowForce bool, cache *caching.AllCacheStruct) []AttendanceSummariesCompute

Creates new attendance summaries for a user and calculation date.

  • curUser *entity.UserProfileTable: The current user profile.
  • calcDate string: The calculation date.
  • force bool: Whether to force the computation.
  • cacheFollowForce bool: Whether to follow the cache force.
  • cache *caching.AllCacheStruct: The cache structure.

Returns a slice of AttendanceSummariesCompute.

CreateSummaryFixed​

func CreateSummaryFixed(summary *AttendanceSummariesCompute, scanLogs []*entity.AttendanceLogTable)

Creates a fixed-time attendance summary.

  • summary *AttendanceSummariesCompute: The attendance summary.
  • scanLogs []*entity.AttendanceLogTable: The scan logs.

CalculateBreaks​

func CalculateBreaks(summary *AttendanceSummariesCompute, scanLogs []*entity.AttendanceLogTable)

Calculates breaks for an attendance summary.

  • summary *AttendanceSummariesCompute: The attendance summary.
  • scanLogs []*entity.AttendanceLogTable: The scan logs.

SetSummaryFromScanPointCandidateOrRule​

func SetSummaryFromScanPointCandidateOrRule(summary *AttendanceSummariesCompute)

Sets the summary from scan point candidates or rules.

  • summary *AttendanceSummariesCompute: The attendance summary.

calculateEarlyLateHeader​

func calculateEarlyLateHeader(header *AttendanceSummariesCompute)

Calculates early and late times for a summary header.

  • header *AttendanceSummariesCompute: The summary header.

CalculatePrecense​

func CalculatePrecense(header *AttendanceSummariesCompute)

Calculates presence for a summary header.

  • header *AttendanceSummariesCompute: The summary header.

CalculateOvertime​

func CalculateOvertime(header *AttendanceSummariesCompute)

Calculates overtime for a summary header.

  • header *AttendanceSummariesCompute: The summary header.

CalculateScore​

func CalculateScore(header *AttendanceSummariesCompute)

Calculates the score for a summary header.

  • header *AttendanceSummariesCompute: The summary header.

CreateSummaryTotalMultipleShift​

func CreateSummaryTotalMultipleShift(summariesCompute []AttendanceSummariesCompute) AttendanceSummariesCompute

Creates a total summary for multiple shifts.

  • summariesCompute []AttendanceSummariesCompute: The attendance summaries for multiple shifts.

Returns a total AttendanceSummariesCompute.

Example Usage​

package main

import (
    "fio-backend/entity"
    "fio-backend/utils/caching"
    "fio-backend/utils/compute"
    "fio-backend/utils/timedate"
    "fmt"
    "time"
)

func main() {
    // Create a sample user profile
    user := &entity.UserProfileTable{
        Id:        "user_id_123",
        FullName:  "John Doe",
        CompanyID: "company_id_123",
    }

    // Create a sample cache
    cache := &caching.AllCacheStruct{
        Summaries: &caching.LocalSummaries{
            Threshold: 0.75,
        },
        Shifts: &caching.LocalShifts{
            IndexedShifts: map[string]*entity.ShiftTable{
                "shift_id_123": {
                    Id:                "shift_id_123",
                    ShortLabel:        "Morning Shift",
                    StartTime:         "08:00:00",
                    EndTime:           "17:00:00",
                    DurationMinutes:   540,
                    ShiftBreaks:       []entity.ShiftBreakTable{},
                    AttendanceRule:    &entity.RuleTable{},
                    MinIntervalDurationMinutes: 30,
                    MinWorkDurationMinutes:     480,
                    CountAs:                    1.0,
                },
            },
        },
    }

    // Create a sample calculation date
    calcDate := "2024-05-01"

    // Create new attendance summaries
    summaries := compute.NewAttendanceSummariesCompute(user, calcDate, false, false, cache)

    // Print the summaries
    for _, summary := range summaries {
        fmt.Printf("Summary: %+v\n", summary)
    }

    // Create sample scan logs
    scanLogs := []*entity.AttendanceLogTable{
        {
            Id:           "log_id_1",
            UserProfileID: "user_id_123",
            Timestamp:    "2024-05-01T08:00:00Z",
        },
        {
            Id:           "log_id_2",
            UserProfileID: "user_id_123",
            Timestamp:    "2024-05-01T17:00:00Z",
        },
    }

    // Create a fixed-time attendance summary
    compute.CreateSummaryFixed(&summaries[0], scanLogs)

    // Print the updated summary
    fmt.Printf("Updated Summary: %+v\n", summaries[0])
}

Improvements and Considerations​

  • Error Handling: Improve error handling by returning errors instead of just logging them.
  • Code Clarity and Comments: Improve code comments to explain complex logic more clearly.
  • Unit Tests: Add unit tests to ensure the functions work correctly with various inputs and edge cases.
  • Performance Optimization: Optimize the functions for performance, especially when processing large numbers of scan logs and breaks.
  • Modularization: Break down the functions into smaller, more modular functions to improve readability and maintainability.

This comprehensive documentation provides a detailed understanding of the fixed-time attendance computation functions and their functionalities. By addressing the suggested improvements, you can create a more robust and maintainable solution for calculating attendance summaries.