settings

# Company Settings

## Overview

Each company has a dedicated settings page where HR/Admin can configure various system behaviors. All settings are company-specific and apply to all employees within that company.

## Access

**URL**: `/<company>/settings`

**Authentication**: Requires HR/Admin credentials (same as admin page)

**Example**: `http://localhost:8080/acmecorp/settings`

## Available Settings

### 1. Employee Log Access

**Purpose**: Control how employees view their own work logs

**Settings:**

**Log Search Range:**
- 30 days (default)
- 60 days
- 90 days
- 6 months (180 days)
- 1 year (365 days)

**Access Method:**
- Face Verification - Employee verifies face to view logs (secure, prevents unauthorized access)

**Use Cases:**
- **Short Range (30-60 days)**: Recent history only, minimal data exposure
- **Long Range (6-12 months)**: Full history for tax/payroll purposes

**Documentation**: See `EMPLOYEE_SELF_SERVICE.md`

---

### 2. Security Settings

**Purpose**: Configure anti-spoofing detection for employee login

**Settings:**

**Anti-Spoofing Detection:**
- Enabled (default) - Liveness detection active
- Disabled - Faster login without spoofing checks

**How It Works:**
- **Enabled**: System analyzes webcam frames for blur and color variance to detect photos/videos
- **Disabled**: Face verification only, no liveness detection

**Use Cases:**
- **Enabled**: High-security environments, prevent photo/video attacks
- **Disabled**: Trusted environments, faster login process

**Documentation**: See `ANTI_SPOOFING.md`

---

### 3. Inactive Employee Tracking

**Purpose**: Monitor employees who haven't clocked in for extended periods

**Settings:**

**Tracking:**
- Enabled - Show inactive employees on search page
- Disabled (default) - Don't track inactivity

**Threshold:**
- 3 days
- 5 days
- 7 days (default)
- 14 days
- 30 days

**How It Works:**
- System identifies employees who haven't logged in for X days
- Displays warning box on admin search page
- Shows employee name, user ID, last activity, days inactive

**Use Cases:**
- **Enabled**: Track attendance issues, identify absent employees
- **Disabled**: Don't need inactivity monitoring

**Documentation**: See `INACTIVE_TRACKING.md`

---

### 4. Colleague Visibility

**Purpose**: Control whether employees see who else is currently logged in

**Settings:**

**Employee Colleague Visibility:**
- Enabled (default) - Employees see colleague list
- Disabled - Only admin sees colleague list

**How It Works:**
- **Enabled**: Employees see names of currently logged-in colleagues on their dashboard
- **Disabled**: Employees don't see colleague list, admin always sees it
- Admin view is always on regardless of setting

**Display:**
- **Employee View**: First and last names only
- **Admin View**: Names, user IDs, and login timestamps
- **Live Updates**: Auto-refreshes every 5 seconds

**Use Cases:**
- **Enabled**: Promote team awareness and collaboration
- **Disabled**: Privacy-focused workplace, competitive environment

**Documentation**: See `COLLEAGUE_VISIBILITY.md`, `LIVE_COLLEAGUE_FEED.md`

---

### 5. Required Work Hours

**Purpose**: Set expected shift duration for employees

**Settings:**

**Required Work Hours:**
- 4.0 hours
- 4.5 hours
- 5.0 hours
- 5.5 hours
- 6.0 hours
- 6.5 hours
- 7.0 hours
- 7.5 hours
- **8.0 hours (default)**
- 8.5 hours
- 9.0 hours
- 9.5 hours
- 10.0 hours
- 10.5 hours
- 11.0 hours
- 11.5 hours
- 12.0 hours

**How It Works:**
- Defines standard work shift length for the company
- Used for tracking if employees meet expected hours
- Applies company-wide to all employees
- Enables overtime tracking and undertime alerts

**Use Cases:**
- **Part-Time (4-6 hours)**: Retail, student workers, flexible schedules
- **Standard (7.5-8 hours)**: Office workers, 9-to-5 schedules
- **Extended (9-12 hours)**: Healthcare, manufacturing, 24/7 operations

**Documentation**: See `REQUIRED_WORK_HOURS.md`

---

### 6. Overtime Tracking

**Purpose**: Log overtime hours when employees exceed required work hours

**Settings:**

**Overtime Tracking:**
- Enabled - Log overtime hours
- Disabled (default) - Don't track overtime

**How It Works:**
- When employee works more than required hours, overtime is calculated
- Overtime duration stored in `overtime_hours` column
- Example: Required 8 hours, worked 10 hours = 2 hours overtime logged
- Overtime data available in search results and reports

**Use Cases:**
- **Enabled**: Track overtime for payroll, compliance, labor cost analysis
- **Disabled**: Don't need overtime tracking

**Database:**
- `overtime_tracking_enabled` in `companies` table
- `overtime_hours` in `<company>_employees_logs` table

**Documentation**: See `REQUIRED_WORK_HOURS.md`

---

### 7. Undertime Alerts

**Purpose**: Alert HR when employees work less than required hours

**Settings:**

**Undertime Alerts:**
- Enabled - Send email alerts to HR
- Disabled (default) - Don't send alerts

**How It Works:**
- When employee clocks out before completing required hours, email sent to HR
- Email includes: employee name, user ID, required hours, actual hours, undertime duration
- Sent to HR email configured in automated reports settings
- Helps identify attendance issues early

**Use Cases:**
- **Enabled**: Monitor compliance, identify attendance problems, ensure minimum hours
- **Disabled**: Don't need undertime monitoring

**Email Example:**
```
Subject: ⚠️ Undertime Alert - Acme Corp

Employee: John Doe (JD1456)
Required Hours: 8 hours
Actual Hours Worked: 6 hours 30 minutes
Undertime: 1 hours 30 minutes
Date: 2025-12-09 14:30:00
```

**Requirements:**
- HR email must be configured in automated reports settings
- SMTP settings must be configured in `.env` file

**Documentation**: See `REQUIRED_WORK_HOURS.md`

---

### 8. Late Arrival Tracking

**Purpose**: Monitor and document employees who clock in after scheduled start time

**Settings:**

**Late Arrival Tracking:**
- Enabled (default) - Track late arrivals and require reasons
- Disabled - Don't track late arrivals

**Late Threshold (Grace Period):**
- 0 minutes (No grace period) - Default
- 5 minutes
- 10 minutes
- 15 minutes
- 20 minutes
- 30 minutes

**How It Works:**
- Employee marked late if clock-in time > (scheduled start time + threshold)
- Example: Scheduled 9:00 AM + 10 min threshold = Late if after 9:10 AM
- When late, employee must provide reason
- Reason stored in `late_reason` column
- Late status marked as 'Late' in `late_status` column
- Admin can view all late arrivals on search page
- Predefined reasons: Traffic, Transportation Delay, Family Emergency, Medical, Car Trouble, Overslept, Weather, Other

**When Disabled:**
- Employees not prompted for late reason
- No late status marked in database
- No late employees shown on search page
- Threshold setting ignored

**Admin Visibility:**
- Late arrivals displayed on `/<company>/search` page
- Orange warning box shows: Employee name, user ID, clock-in time, reason
- Only shows employees late today

**Use Cases:**
- **Enabled with 0 min**: Strict punctuality, no grace period
- **Enabled with 10-15 min**: Standard flexibility, reasonable grace
- **Enabled with 30 min**: High flexibility, focus on major lateness only
- **Disabled**: Flexible start times, no need for late tracking

**Database:**
- `late_tracking_enabled` in `companies` table
- `late_threshold_minutes` in `companies` table
- `late_status` in `<company>_employees_logs` table
- `late_reason` in `<company>_employees_logs` table

**Documentation**: See `LATE_CLOCKIN_TRACKING.md`, `LATE_CLOCKIN_PHASE2.md`, and `LATE_CLOCKIN_PHASE3.md`

---

### 9. Automated Timesheet Reports

**Purpose**: Schedule automatic email reports of employee work logs

**Settings:**

**Report Email:**
- Email address to receive reports
- Can be HR email or any custom address

**Report Frequency:**
- Weekly
- Bi-weekly (every 2 weeks)
- 4-weekly (every 4 weeks)
- Monthly

**Report Day/Date:**
- **Weekly**: Monday-Sunday
- **Bi-weekly**: Monday-Sunday
- **4-weekly**: Monday-Sunday
- **Monthly**: 1-28 (day of month)

**Report Format:**
- Excel (.xlsx)
- CSV (.csv)

**How It Works:**
- System automatically generates reports on schedule
- Includes all employee clock-in/out data
- Emails report as attachment

**Documentation**: See `AUTOMATED_REPORTS.md`

---

## Settings Workflow

### Accessing Settings

1. HR visits `/<company>/admin`
2. Authenticates with HR credentials
3. Clicks "Settings" link in navigation
4. Redirected to `/<company>/settings`

### Updating Settings

1. HR reviews current settings (pre-selected in dropdowns)
2. Changes desired settings
3. Clicks "Save Settings" button at bottom
4. Settings updated immediately
5. Confirmation message displayed
6. Changes apply to all employees

### Settings Persistence

- All settings stored in `companies` table
- Settings persist across sessions
- Each company has independent settings
- No global settings (all company-specific)

## Database Schema

**Table: `companies`**

```sql
-- Employee log access
log_search_days INT DEFAULT 30
require_face_for_logs BOOLEAN DEFAULT TRUE

-- Security
anti_spoofing_enabled BOOLEAN DEFAULT TRUE

-- Inactive tracking
inactive_tracking_enabled BOOLEAN DEFAULT FALSE
inactive_days_threshold INT DEFAULT 7

-- Colleague visibility
colleague_visibility_enabled BOOLEAN DEFAULT TRUE

-- Required work hours
required_work_hours DECIMAL(3,1) DEFAULT 8.0

-- Overtime and undertime
overtime_tracking_enabled BOOLEAN DEFAULT FALSE
undertime_alerts_enabled BOOLEAN DEFAULT FALSE

-- Automated reports
report_email VARCHAR(255)
report_frequency VARCHAR(20)
report_day VARCHAR(10)
report_date VARCHAR(10)
```

**Table: `<company>_employees_logs`**

```sql
-- Overtime tracking
overtime_hours VARCHAR(50)  -- Stored when overtime_tracking_enabled = true
```

## Technical Implementation

### Go Handler

**GET Request:**
```go
func dynamicSettingsHandler(w http.ResponseWriter, r *http.Request) {
    // Extract company slug
    // Call Python functions to get each setting
    // Pass all settings to template
    templates.ExecuteTemplate(w, "settings.html", settingsData)
}
```

**POST Request:**
```go
func dynamicSettingsHandler(w http.ResponseWriter, r *http.Request) {
    // Extract form values
    // Call Python functions to update each setting
    // Redirect back to settings page
}
```

### Python Functions

Each setting has get/update functions:
```python
get_log_search_days(company_slug)
update_log_search_days(company_slug, days)

get_anti_spoofing_enabled(company_slug)
update_anti_spoofing_enabled(company_slug, enabled)

get_required_work_hours(company_slug)
update_required_work_hours(company_slug, hours)
# ... etc
```

### Template

**settings.html:**
- Form with all settings as dropdowns/selects
- Pre-selected values from database
- Submit button to save all settings at once
- Info boxes explaining each setting

## Best Practices

### For Admins

1. **Review Defaults**: Understand default settings before changing
2. **Test Changes**: Verify settings work as expected after updating
3. **Communicate**: Inform employees of setting changes (especially visibility)
4. **Document**: Keep record of why settings were changed
5. **Regular Review**: Periodically review settings for relevance

### Recommended Settings

**High-Security Environment:**
- Anti-Spoofing: Enabled
- Log Access: Face Verification
- Log Range: 30-60 days
- Colleague Visibility: Disabled

**Collaborative Environment:**
- Anti-Spoofing: Enabled
- Log Access: Face Verification or User ID
- Log Range: 90-365 days
- Colleague Visibility: Enabled

**Trusted Small Team:**
- Anti-Spoofing: Disabled (faster login)
- Log Access: User ID Entry
- Log Range: 365 days
- Colleague Visibility: Enabled

## Troubleshooting

### Settings Not Saving

**Possible Causes:**
- Database connection issue
- Invalid values submitted
- Permission error

**Solution:**
- Check server logs for errors
- Verify database connectivity
- Ensure HR is authenticated

### Settings Not Applying

**Possible Causes:**
- Browser cache
- Employee not logged out/in again
- Setting requires page refresh

**Solution:**
- Clear browser cache
- Have employees log out and back in
- Refresh settings page

### Can't Access Settings Page

**Possible Causes:**
- Not authenticated as HR
- Wrong company slug
- Server not running

**Solution:**
- Authenticate at `/<company>/admin` first
- Verify correct company slug in URL
- Ensure server is running

## Related Documentation

- `EMPLOYEE_SELF_SERVICE.md` - Employee log access
- `ANTI_SPOOFING.md` - Security settings
- `INACTIVE_TRACKING.md` - Inactive employee monitoring
- `COLLEAGUE_VISIBILITY.md` - Colleague visibility feature
- `REQUIRED_WORK_HOURS.md` - Work hours configuration
- `AUTOMATED_REPORTS.md` - Report scheduling
- `README.md` - Overall system architecture