# Team Time Overview (Manager View)

**Date:** 2026-05-31  
**Status:** Draft  
**Spec:** 64  
**Tier:** All tiers  
**Depends on:** `time-management`, `projects-module`, `contractor-payouts`, `foundation-auth-rbac`  
**Referenced by:** `time-management`

---

## Overview

Manager-facing view of the team's current timer state and recent activity. Surfaces who is tracking time right now, what they're working on, and whether anyone has gone idle. Distinct from spec 56 (time reports): reports are historical aggregate; this view is live/near-real-time operational status.

Route: `/time/team` in zync-app (sub-navigation tab within the time module).  
Permission: `time:read` + role OWNER/ADMIN (MEMBERs see only their own `/time`).

---

## Page: `/time/team`

```
┌────────────────────────────────────────────────────────────┐
│  Time · Team Overview                     [Date ◄ ► Today] │
│                                                            │
│  ● Alex Katz         Website Redesign · Homepage design    │
│    ACTIVE            Running: 2h 14m    Today: 6h 30m      │
│                                                            │
│  ⏸ Dana Levi         Mobile App · API integration         │
│    IDLE 23 min       Paused: 0h 45m     Today: 4h 12m      │
│                                                            │
│  ○ Oren Ben-David    —                                     │
│    No timer          Today: 0h 00m                         │
│                                                            │
│  [Contractor] Noa    Internal · Documentation              │
│    ACTIVE            Running: 1h 02m    Today: 3h 15m      │
│                                                            │
│  ── Summary ────────────────────────────────────────────── │
│  Team total today:   13h 57m                               │
│  Active timers:      2     Idle (>15 min):  1              │
└────────────────────────────────────────────────────────────┘
```

Status indicators:
- `●` ACTIVE — timer running, last activity < 15 min ago
- `⏸` IDLE — timer running but no activity for 15–60 min (spec 13 idle detection)
- `○` No timer — no running entry today

Date navigation allows viewing any past day (no live status for historical dates — shows completed entries only).

---

## Team Member Row (expanded)

Click a row to expand:

```
┌────────────────────────────────────────────────────────────┐
│  ● Alex Katz         Website Redesign · Homepage design    │
│    ACTIVE            Running: 2h 14m    Today: 6h 30m      │
│  ──────────────────────────────────────────────────────── │
│  Today's entries:                                          │
│  09:00–11:30   Website Redesign / Homepage design   2h 30m │
│  11:30–13:00   Mobile App / Planning call           1h 30m │
│  14:00–now     Website Redesign / Homepage design   2h 14m │
│                                                            │
│  [View in Time log →]                                      │
└────────────────────────────────────────────────────────────┘
```

"View in Time log →" → `/time?userId={id}&date={date}` (spec 13 time log filtered to that user + date).

---

## Data Freshness

Live status (ACTIVE/IDLE): polled every 60 seconds via `GET /api/time/team/status`. No WebSocket needed — 60s polling sufficient for manager overview use case.

Active timer running time displayed as a client-side counter (increments in JS once initial duration known).

---

## API Endpoints

```
GET  /api/time/team/status
     → current timer status for all team members + contractors
       returns: {
         members: [{
           userId: string | null,
           contractorId: string | null,
           name: string,
           role: string,
           runningEntry: {
             id, projectId, projectName, taskId, taskName,
             startedAt, durationSeconds, idleSince?
           } | null,
           todayTotal: number    // seconds
         }]
       }
     Requires: time:read, OWNER or ADMIN role

GET  /api/time/team/day
     → completed entries for all team members on a given date
       query: date=YYYY-MM-DD
       returns: same structure but with full entry lists, no live status
```

Both endpoints are tenant-scoped (`tenantQuery`). Contractors included when caller is OWNER/ADMIN.

---

## Architecture Decisions

| Decision | Choice | Reason |
|----------|--------|--------|
| Polling (60s) | Not WebSocket | Manager overview doesn't need sub-second freshness; WebSocket would require `DO_REALTIME` for a single low-value read |
| Idle from spec 13 definition | Same 15-min threshold | Consistency with spec 13's auto-pause logic; idle marker comes from `time_entries.idle_since` set by spec 13's beacon handler |
| OWNER/ADMIN only | Not available to MEMBER | MEMBERs should not see colleagues' live timer activity; privacy boundary |
| Contractors in same view | Not a separate tab | Manager needs unified view of everyone working on their tenant's projects |