self service

# Employee Self-Service Log Search

## Overview

Employees can view their own work logs (clock-in/clock-out records) without admin assistance. The search range is controlled by admin settings.

## Access

**Endpoint**: `/<companyslug>/mylogs`

**Example**: `/acmecorp/mylogs`

**Access from**: 
- Logged-in dashboard → "View My Work Logs" link (opens in new tab)
- Direct URL access

## How It Works

### For Employees (Face Verification Mode - Default)

1. **After logging in**, you'll see your dashboard with Clock Out button
2. **View colleagues** - See who else is logged in today (first + last names)
3. **Click** "View My Work Logs" (opens in new tab)
4. **Click** "Verify Face & View Logs" button
5. **Complete face verification** via webcam
6. **System automatically identifies you** and displays your logs
7. **See** all your work records within the allowed date range
8. **Close the tab** when done (dashboard remains open)
9. **Return to dashboard tab** to clock out

**Important**: 
- Face verification ensures only you can access your logs
- The logs page opens in a new tab, keeping your dashboard open
- Only closing the dashboard tab will trigger automatic logout
- You can view logs multiple times without affecting your clock-in session

### What Employees See

- **Date**: Work date (DD-MM-YYYY format)
- **Clock In**: Login time (HH:MM:SS)
- **Clock Out**: Logout time or "Still logged in"
- **Hours Worked**: Total hours and minutes (e.g., "8 hours 30 minutes")

Results are sorted by most recent first.

## Admin Configuration

### Setting Search Range

1. **HR logs into** `/<company>/admin`
2. **Clicks** "Settings" link
3. **Selects** search range from dropdown:
   - 30 Days (default)
   - 60 Days
   - 90 Days
   - 6 Months (180 days)
   - 1 Year (365 days)
4. **Selects** log access method:
   - **Face Verification (More Secure)** - Default, requires webcam
   - **User ID Entry (Less Secure)** - Allows manual user ID input
5. **Clicks** "Save Settings"

### Effect

- All employees must use the configured access method
- Search range applies to all employees
- Changes apply immediately
- No individual employee configuration needed

## Use Cases

### Employee Tracking Hours
**Scenario**: John wants to verify his hours for the past week
1. Logs in at `/acmecorp/login` (dashboard opens)
2. Clicks "View My Work Logs" (new tab opens)
3. Clicks "Verify Face & View Logs"
4. Completes face verification via webcam
5. System identifies him as JD1456 and shows his logs
6. Views all records from past 30 days (or admin-configured range)
7. Confirms his work hours
8. Closes logs tab, returns to dashboard to clock out

### Payroll Verification
**Scenario**: Employee needs to verify hours for payroll
1. Admin sets search range to 60 days (covers pay period)
2. Employee accesses mylogs
3. Reviews all clock-in/clock-out records
4. Reports any discrepancies to HR

### Compliance Tracking
**Scenario**: Company needs employees to track their own hours
1. Admin sets search range to 1 year
2. Employees can access full year of records
3. Self-service reduces HR workload

## Technical Details

### Database Query
```sql
SELECT first_name, last_name, login_time, logout_time, hours_worked 
FROM <company>_employees_logs 
WHERE user_id = '<user_id>' 
AND login_time >= CURRENT_DATE - INTERVAL '<days> days'
ORDER BY login_time DESC
```

### Date Range Calculation
- **30 days**: Past month of records
- **60 days**: Past 2 months
- **90 days**: Past 3 months (quarter)
- **180 days**: Past 6 months (half year)
- **365 days**: Past year

### Security
- **Admin-controlled access method**: HR chooses between face verification or user ID entry
- **Face Verification Mode (Default)**:
  - Only the actual employee can view their logs
  - Biometric authentication prevents unauthorized access
  - No credential sharing possible
  - Subject to anti-spoofing detection if enabled
- **User ID Entry Mode**:
  - Less secure but more convenient
  - Requires employee to know their user ID
  - Suitable for environments without webcams
- Admin has full access via separate `/search` endpoint
- Date range prevents unlimited historical access
- Company-specific database isolation

### Session Management
- Logs page opens in new tab (target="_blank")
- Dashboard tab maintains active clock-in session
- Closing logs tab does NOT trigger logout
- Only closing dashboard tab triggers automatic logout
- Employees can view logs multiple times during one session

## Differences from Admin Search

| Feature | Employee Search | Admin Search |
|---------|----------------|--------------|
| **Endpoint** | `/<company>/mylogs` | `/<company>/search` |
| **Access** | Any employee with user ID | HR/Admin only |
| **Search by name** | No | Yes |
| **Date range** | Admin-configured limit | Unlimited |
| **View all employees** | No (own logs only) | Yes |
| **Custom date range** | No | Yes |

## Configuration Examples

### Startup Company (30 days)
```
Default setting - employees see past month
Good for: Small teams, new companies
```

### Established Company (90 days)
```
Quarterly view for employees
Good for: Regular payroll cycles, performance reviews
```

### Enterprise (1 year)
```
Full year access for employees
Good for: Annual reviews, compliance, detailed tracking
```

## Command Line Usage

```bash
# Verify employee face and get user_id
python face_verify_db.py verify_employee_for_logs <company_slug>

# View employee logs (after verification)
python face_verify_db.py search_employee_logs <company_slug> <user_id>

# Get current search range setting
python face_verify_db.py get_log_search_days <company_slug>

# Update search range setting
python face_verify_db.py update_log_search_days <company_slug> <days>
```

**Examples**:
```bash
# Verify John's face (opens webcam, returns user_id)
python face_verify_db.py verify_employee_for_logs acmecorp

# View John's logs (after face verification returns JD1456)
python face_verify_db.py search_employee_logs acmecorp JD1456

# Check current setting
python face_verify_db.py get_log_search_days acmecorp

# Set to 90 days
python face_verify_db.py update_log_search_days acmecorp 90
```

## Migration

Existing databases require migration:

```bash
python migrate_add_log_search_days.py
```

This adds `log_search_days` column to companies table with default value of 30 days.