mirror of https://github.com/DRYTRIX/TimeTracker.git synced 2026-02-19 20:18:42 -06:00

Files

Dries Peeters c93a37f126 feat: add overtime tracking support with configurable working hours

Implement comprehensive overtime tracking feature that allows users to
set their standard working hours per day and automatically calculates
overtime for hours worked beyond that threshold.

Core Features:
- Add standard_hours_per_day field to User model (default: 8.0 hours)
- Create Alembic migration (031_add_standard_hours_per_day.py)
- Implement overtime calculation utilities (app/utils/overtime.py)
  * calculate_daily_overtime: per-day overtime calculation
  * calculate_period_overtime: multi-day overtime aggregation
  * get_daily_breakdown: detailed day-by-day analysis
  * get_weekly_overtime_summary: weekly overtime statistics
  * get_overtime_statistics: comprehensive overtime metrics

User Interface:
- Add "Overtime Settings" section to user settings page
- Display overtime data in user reports (regular vs overtime hours)
- Show "Days with Overtime" badge in reports
- Add overtime analytics API endpoint (/api/analytics/overtime)
- Improve input field styling with cleaner appearance (no spinners)

Reports Enhancement:
- Standardize form input styling across all report pages
- Replace inline Tailwind classes with consistent form-input class
- Add FontAwesome icons to form labels for better UX
- Improve button hover states and transitions

Testing:
- Add comprehensive unit tests (tests/test_overtime.py)
- Add smoke tests for quick validation (tests/test_overtime_smoke.py)
- Test coverage for models, utilities, and various overtime scenarios

Documentation:
- OVERTIME_FEATURE_DOCUMENTATION.md: complete feature guide
- OVERTIME_IMPLEMENTATION_SUMMARY.md: technical implementation details
- docs/features/OVERTIME_TRACKING.md: quick start guide

This change enables organizations to track employee overtime accurately
based on individual working hour configurations, providing better
insights into work patterns and resource allocation.

2025-10-27 08:44:04 +01:00

3.3 KiB

Raw Blame History

Overtime Tracking Feature

Quick Start

The Overtime Tracking feature allows users to track hours worked beyond their standard workday.

For Users

Set Your Standard Hours
- Go to Settings → Overtime Settings
- Enter your standard working hours per day (e.g., 8.0)
- Click Save
View Your Overtime
- Navigate to Reports → User Report
- Select your date range
- View overtime breakdown in the report table

For Developers

Key Files:

app/utils/overtime.py - Core calculation functions
app/models/user.py - User model with standard_hours_per_day field
app/routes/reports.py - Report route with overtime display
app/routes/analytics.py - Analytics API endpoint
migrations/versions/031_add_standard_hours_per_day.py - Database migration

API Endpoint:

GET /api/analytics/overtime?days=30

Key Functions:

from app.utils.overtime import (
    calculate_daily_overtime,
    calculate_period_overtime,
    get_daily_breakdown,
    get_overtime_statistics
)

Testing

# Run all overtime tests
pytest tests/test_overtime.py tests/test_overtime_smoke.py -v

# With coverage
pytest tests/test_overtime*.py --cov=app.utils.overtime --cov-report=html

Documentation

Full Documentation: OVERTIME_FEATURE_DOCUMENTATION.md
Implementation Summary: OVERTIME_IMPLEMENTATION_SUMMARY.md

How It Works

User sets standard hours per day in settings (default: 8.0)
System tracks all time entries as usual
When viewing reports, system calculates:
- For each day: regular hours (up to standard) + overtime hours (beyond standard)
Reports display:
- Total hours worked
- Regular hours (green)
- Overtime hours (orange)
- Days with overtime

Examples

Example 1: Full-time Employee (8 hours/day)

Monday: 8 hours → 8 regular, 0 overtime
Tuesday: 10 hours → 8 regular, 2 overtime
Wednesday: 7 hours → 7 regular, 0 overtime

Example 2: Part-time Employee (6 hours/day)

Monday: 6 hours → 6 regular, 0 overtime
Tuesday: 7 hours → 6 regular, 1 overtime
Wednesday: 5 hours → 5 regular, 0 overtime

Configuration

User Setting: standard_hours_per_day

Type: Float
Default: 8.0
Range: 0.5 to 24.0
Location: User Settings → Overtime Settings

Database

Table: users Column: standard_hours_per_day

Type: FLOAT
Default: 8.0
Nullable: NO

Migration: 031_add_standard_hours_per_day

Features

✅ User-configurable standard hours
✅ Automatic overtime calculation
✅ Display in user reports
✅ Analytics API endpoint
✅ Daily overtime breakdown
✅ Weekly overtime summaries
✅ Comprehensive statistics
✅ Full test coverage
✅ Complete documentation

Future Enhancements

Weekly overtime thresholds
Overtime approval workflows
Overtime pay rate calculations
Email notifications for excessive overtime
Overtime budget limits
Export overtime reports

Support

For questions or issues:

Review the full documentation
Check test cases for examples
Open a GitHub issue

Version: 1.0.0
Status: ✅ Production Ready
Last Updated: October 27, 2025

3.3 KiB Raw Blame History