feat: Add kiosk management, artist selection, and schedule management

- Add KiosksManagement component with full CRUD for kiosks
- Add ScheduleManagement for staff schedules with break reminders
- Update booking flow to allow artist selection by customers
- Add staff_services API for assigning services to artists
- Update staff management UI with service assignment dialog
- Add auto-break reminder when schedule >= 8 hours
- Update availability API to filter artists by service
- Add kiosk management to Aperture dashboard
- Clean up ralphy artifacts and logs

lib/utils/business-hours.ts

@@ -1,13 +1,37 @@
+/**
+ * @description Business hours utilities for managing location operating schedules
+ * @audit BUSINESS RULE: Business hours stored in JSONB format with day keys (sunday-saturday)
+ * @audit PERFORMANCE: All functions use O(1) lookups and O(n) iteration (max 7 days)
+ */
+
 import type { BusinessHours, DayHours } from '@/lib/db/types'
 
+/** Array of day names in lowercase for consistent key access */
 const DAYS = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday'] as const
+/** Type representing valid day of week values */
 type DayOfWeek = typeof DAYS[number]
 
+/**
+ * @description Converts a Date object to its corresponding day of week string
+ * @param {Date} date - The date to extract day of week from
+ * @returns {DayOfWeek} - Lowercase day name (e.g., 'monday', 'tuesday')
+ * @example getDayOfWeek(new Date('2026-01-21')) // returns 'wednesday'
+ * @audit PERFORMANCE: Uses native getDay() method for O(1) conversion
+ */
 export function getDayOfWeek(date: Date): DayOfWeek {
   return DAYS[date.getDay()]
 }
 
 export function isOpenNow(businessHours: BusinessHours, date = new Date): boolean {
+  /**
+   * @description Checks if the business is currently open based on business hours configuration
+   * @param {BusinessHours} businessHours - JSON object with day-by-day operating hours
+   * @param {Date} date - Optional date to check (defaults to current time)
+   * @returns {boolean} - True if business is open, false if closed
+   * @example isOpenNow({ monday: { open: '10:00', close: '19:00', is_closed: false } }, new Date())
+   * @audit BUSINESS RULE: Compares current time against open/close times in HH:MM format
+   * @audit Validate: Returns false immediately if day is marked as is_closed
+   */
   const day = getDayOfWeek(date)
   const hours = businessHours[day]
 
@@ -29,6 +53,15 @@ export function isOpenNow(businessHours: BusinessHours, date = new Date): boolea
 }
 
 export function getNextOpenTime(businessHours: BusinessHours, from = new Date): Date | null {
+  /**
+   * @description Finds the next opening time within the next 7 days
+   * @param {BusinessHours} businessHours - JSON object with day-by-day operating hours
+   * @param {Date} from - Reference date to search from (defaults to current time)
+   * @returns {Date | null} - Next opening DateTime or null if no opening found within 7 days
+   * @example getNextOpenTime({ monday: { open: '10:00', close: '19:00' }, sunday: { is_closed: true } })
+   * @audit BUSINESS RULE: Scans up to 7 days ahead to find next available opening
+   * @audit PERFORMANCE: O(7) iteration worst case, exits early when found
+   */
   const checkDate = new Date(from)
 
   for (let i = 0; i < 7; i++) {
@@ -56,6 +89,15 @@ export function getNextOpenTime(businessHours: BusinessHours, from = new Date):
 }
 
 export function isTimeWithinHours(time: string, dayHours: DayHours): boolean {
+  /**
+   * @description Validates if a given time falls within operating hours for a specific day
+   * @param {string} time - Time in HH:MM format (e.g., '14:30')
+   * @param {DayHours} dayHours - Operating hours for a single day with open, close, and is_closed
+   * @returns {boolean} - True if time is within operating hours, false otherwise
+   * @example isTimeWithinHours('14:30', { open: '10:00', close: '19:00', is_closed: false }) // true
+   * @audit BUSINESS RULE: Converts times to minutes for accurate comparison
+   * @audit Validate: Returns false immediately if dayHours.is_closed is true
+   */
   if (dayHours.is_closed) {
     return false
   }
@@ -72,6 +114,13 @@ export function isTimeWithinHours(time: string, dayHours: DayHours): boolean {
 }
 
 export function getBusinessHoursString(dayHours: DayHours): string {
+  /**
+   * @description Formats day hours for display in UI
+   * @param {DayHours} dayHours - Operating hours for a single day
+   * @returns {string} - Formatted string (e.g., '10:00 - 19:00' or 'Cerrado')
+   * @example getBusinessHoursString({ open: '10:00', close: '19:00', is_closed: false }) // '10:00 - 19:00'
+   * @audit BUSINESS RULE: Returns 'Cerrado' (Spanish for closed) when is_closed is true
+   */
   if (dayHours.is_closed) {
     return 'Cerrado'
   }
@@ -79,6 +128,13 @@ export function getBusinessHoursString(dayHours: DayHours): string {
 }
 
 export function getTodayHours(businessHours: BusinessHours): string {
+  /**
+   * @description Gets formatted operating hours for the current day
+   * @param {BusinessHours} businessHours - JSON object with day-by-day operating hours
+   * @returns {string} - Formatted hours string for today (e.g., '10:00 - 19:00' or 'Cerrado')
+   * @example getTodayHours(businessHoursConfig) // Returns hours for current day of week
+   * @audit PERFORMANCE: Single lookup using getDayOfWeek on current date
+   */
   const day = getDayOfWeek(new Date())
   return getBusinessHoursString(businessHours[day])
 }