Timesheet Billing Workflow

type TimesheetStatus = 
  | "draft"      // Being edited
  | "submitted"  // Awaiting approval
  | "approved"   // Manager approved
  | "rejected"   // Needs correction
  | "billed";    // Added to invoice

type TimeEntryCategory = 
  | "regular"      // Standard work hours
  | "overtime"     // OT hours (1.5x)
  | "double_time"  // Holiday/special (2x)
  | "on_call"      // On-call availability
  | "travel"       // Travel time
  | "break";       // Break time (not counted)

interface RateHierarchy {
  // 1. Entry-level override
  entryRate?: number;
  
  // 2. Job-level rate
  jobRate?: number;
  
  // 3. Customer-level rate
  customerRate?: number;
  
  // 4. Employee default rate
  employeeRate: number;
  
  // 5. Team default rate
  teamRate: number;
}

function calculateBillableRate(entry: TimeEntry): number {
  return entry.rate 
    ?? entry.job?.billableRate 
    ?? entry.job?.customer?.defaultRate 
    ?? entry.employee?.billableRate 
    ?? entry.team?.defaultBillableRate;
}

interface OvertimeRules {
  dailyThreshold: number;      // Hours before OT (e.g., 8)
  weeklyThreshold: number;     // Hours before OT (e.g., 40)
  overtimeMultiplier: number;  // 1.5x
  doubleTimeThreshold?: number; // Hours for 2x (e.g., 12/day)
  doubleTimeMultiplier: number; // 2x
}

function calculateWeeklyOvertime(entries: TimeEntry[], rules: OvertimeRules): {
  regular: number;
  overtime: number;
  doubleTime: number;
} {
  const totalHours = entries.reduce((sum, e) => sum + e.duration, 0);
  
  let regular = Math.min(totalHours, rules.weeklyThreshold);
  let overtime = 0;
  let doubleTime = 0;
  
  if (totalHours > rules.weeklyThreshold) {
    overtime = totalHours - rules.weeklyThreshold;
  }
  
  // Apply daily double-time if configured
  if (rules.doubleTimeThreshold) {
    for (const entry of entries) {
      if (entry.duration > rules.doubleTimeThreshold) {
        doubleTime += entry.duration - rules.doubleTimeThreshold;
      }
    }
    overtime -= doubleTime;
  }
  
  return { regular, overtime, doubleTime };
}

interface ApprovalConfig {
  levels: Array<{
    level: number;
    role: string;
    threshold?: number; // Hours threshold for this level
  }>;
  autoApproveUnder?: number; // Auto-approve if under X hours
  requireComments: boolean;
}

// Example: Two-level approval for high hours
const approvalConfig: ApprovalConfig = {
  levels: [
    { level: 1, role: "supervisor" },
    { level: 2, role: "manager", threshold: 50 } // Only for 50+ hours
  ],
  autoApproveUnder: 40,
  requireComments: false
};

async function approveTimesheet(
  timesheetId: string,
  approverId: string,
  options: {
    approved: boolean;
    comments?: string;
    adjustments?: Array<{
      entryId: string;
      newDuration: number;
      reason: string;
    }>;
  }
): Promise<Timesheet> {
  const timesheet = await getTimesheet(timesheetId);
  
  if (options.adjustments) {
    for (const adj of options.adjustments) {
      await updateTimeEntry(adj.entryId, {
        duration: adj.newDuration,
        adjustmentReason: adj.reason,
        adjustedBy: approverId
      });
    }
  }
  
  return db.update(timesheets).set({
    status: options.approved ? "approved" : "rejected",
    approvedBy: approverId,
    approvedAt: new Date().toISOString(),
    approvalComments: options.comments
  }).where(eq(timesheets.id, timesheetId)).returning();
}

async function addTimesheetToInvoice(
  invoiceId: string,
  timesheetId: string
): Promise<void> {
  const timesheet = await getTimesheet(timesheetId);
  const billableEntries = timesheet.entries.filter(e => e.billable);
  
  // Group by rate
  const byRate = groupBy(billableEntries, e => e.rate);
  
  for (const [rate, entries] of Object.entries(byRate)) {
    const totalHours = entries.reduce((sum, e) => sum + e.duration, 0);
    
    await addInvoiceLineItem(invoiceId, {
      description: `Professional Services - ${formatDateRange(entries)}`,
      quantity: totalHours,
      unitPrice: parseFloat(rate),
      total: totalHours * parseFloat(rate)
    });
  }
  
  // Mark timesheet as billed
  await db.update(timesheets)
    .set({ status: "billed", invoiceId })
    .where(eq(timesheets.id, timesheetId));
}

const validTransitions: Record<TimesheetStatus, TimesheetStatus[]> = {
  draft: ["submitted"],
  submitted: ["approved", "rejected"],
  approved: ["billed"],
  rejected: ["draft"],  // Back to draft for corrections
  billed: []            // Terminal
};

interface UtilizationReport {
  period: { start: string; end: string };
  employees: Array<{
    id: string;
    name: string;
    totalHours: number;
    billableHours: number;
    nonBillableHours: number;
    utilization: number; // billable / total %
    target: number;
    variance: number;
  }>;
  summary: {
    avgUtilization: number;
    totalBillable: number;
    totalNonBillable: number;
    totalRevenue: number;
  };
}

interface ProjectCostReport {
  projectId: string;
  projectName: string;
  totalHours: number;
  totalCost: number;
  budget: number;
  remaining: number;
  percentUsed: number;
  byEmployee: Array<{
    name: string;
    hours: number;
    cost: number;
  }>;
}

// Start timer
timeTracker.start({
  jobId?: string,
  description?: string,
  billable: boolean
})

// Stop timer
timeTracker.stop({
  timerId: string,
  description?: string
})

// Manual entry
timeEntries.create({
  date: string,
  startTime: string,
  endTime: string,
  jobId?: string,
  description: string,
  billable: boolean,
  rate?: number
})

// Get weekly timesheet
timesheets.getWeekly({
  userId: string,
  weekStart: string
})

// Submit timesheet
timesheets.submit({ id: string })

// Approve/reject
timesheets.review({
  id: string,
  approved: boolean,
  comments?: string
})

// Export for payroll
timesheets.exportPayroll({
  periodStart: string,
  periodEnd: string,
  format: "csv" | "json"
})

// Dashboard timer state
interface TimerState {
  isRunning: boolean;
  startTime: string | null;
  elapsed: number; // seconds
  currentJob: Job | null;
  description: string;
}

// Timer actions
const timerActions = {
  start: async (jobId?: string) => {
    const timer = await trpc.timeTracker.start.mutate({
      jobId,
      billable: true
    });
    return timer;
  },
  
  stop: async (timerId: string, description: string) => {
    const entry = await trpc.timeTracker.stop.mutate({
      timerId,
      description
    });
    return entry;
  },
  
  pause: async (timerId: string) => {
    // Save current elapsed, stop timer
  },
  
  resume: async (timerId: string) => {
    // Continue from paused state
  }
};

cd apps/workbooks-api
bun test src/__tests__/crud/timesheets.test.ts
bun test src/__tests__/integration/timesheet-billing.test.ts