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
2026-03-15 14:24:27 +00:00 · 2026-01-21 13:02:06 -06:00
parent 24e5af3860
commit d27354fd5a
71 changed files with 3353 additions and 2701 deletions
--- a/app/api/availability/blocks/route.ts
+++ b/app/api/availability/blocks/route.ts
@@ -1,6 +1,14 @@
 import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

+/**
+ * @description Validates that the request contains a valid ADMIN_ENROLLMENT_KEY authorization header
+ * @param {NextRequest} request - HTTP request to validate
+ * @returns {Promise<boolean|null>} Returns true if authorized, null otherwise
+ * @example validateAdmin(request)
+ * @audit SECURITY: Simple API key validation for administrative booking block operations
+ * @audit Validate: Ensures authorization header follows 'Bearer <token>' format
+ */
 async function validateAdmin(request: NextRequest) {
  const authHeader = request.headers.get('authorization')
  
@@ -18,7 +26,14 @@ async function validateAdmin(request: NextRequest) {
 }

 /**
- * @description Creates a booking block for a resource
+ * @description Creates a new booking block to reserve a resource for a specific time period
+ * @param {NextRequest} request - HTTP request containing location_id, resource_id, start_time_utc, end_time_utc, and optional reason
+ * @returns {NextResponse} JSON with success status and created booking block record
+ * @example POST /api/availability/blocks { location_id: "...", resource_id: "...", start_time_utc: "...", end_time_utc: "...", reason: "Maintenance" }
+ * @audit BUSINESS RULE: Blocks prevent bookings from using the resource during the blocked time
+ * @audit SECURITY: Requires ADMIN_ENROLLMENT_KEY authorization header
+ * @audit Validate: Ensures start_time_utc is before end_time_utc and both are valid ISO8601 timestamps
+ * @audit AUDIT: All booking blocks are logged for operational monitoring
 */
 export async function POST(request: NextRequest) {
  try {
@@ -80,7 +95,14 @@ export async function POST(request: NextRequest) {
 }

 /**
- * @description Retrieves booking blocks with filters
+ * @description Retrieves booking blocks with optional filtering by location and date range
+ * @param {NextRequest} request - HTTP request with query parameters location_id, start_date, end_date
+ * @returns {NextResponse} JSON with array of booking blocks including related location, resource, and creator info
+ * @example GET /api/availability/blocks?location_id=...&start_date=2026-01-01&end_date=2026-01-31
+ * @audit BUSINESS RULE: Returns all booking blocks regardless of status (used for resource planning)
+ * @audit SECURITY: Requires ADMIN_ENROLLMENT_KEY authorization header
+ * @audit PERFORMANCE: Supports filtering by location and date range for efficient queries
+ * @audit Validate: Ensures date filters are valid if provided
 */
 export async function GET(request: NextRequest) {
  try {
@@ -158,7 +180,14 @@ export async function GET(request: NextRequest) {
 }

 /**
- * @description Deletes a booking block by ID
+ * @description Deletes an existing booking block by its ID, freeing up the resource for bookings
+ * @param {NextRequest} request - HTTP request with query parameter 'id' for the block to delete
+ * @returns {NextResponse} JSON with success status and confirmation message
+ * @example DELETE /api/availability/blocks?id=123e4567-e89b-12d3-a456-426614174000
+ * @audit BUSINESS RULE: Deleting a block removes the scheduling restriction, allowing new bookings
+ * @audit SECURITY: Requires ADMIN_ENROLLMENT_KEY authorization header
+ * @audit Validate: Ensures block ID is provided and exists in the database
+ * @audit AUDIT: Block deletion is logged for operational monitoring
 */
 export async function DELETE(request: NextRequest) {
  try {
--- a/app/api/availability/staff-unavailable/route.ts
+++ b/app/api/availability/staff-unavailable/route.ts
@@ -1,6 +1,14 @@
 import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

+/**
+ * @description Validates that the request contains a valid ADMIN_ENROLLMENT_KEY authorization header
+ * @param {NextRequest} request - HTTP request to validate
+ * @returns {Promise<boolean|null>} Returns true if authorized, null if unauthorized, or throws error on invalid format
+ * @example validateAdminOrStaff(request)
+ * @audit SECURITY: Simple API key validation for administrative operations
+ * @audit Validate: Ensures authorization header follows 'Bearer <token>' format
+ */
 async function validateAdminOrStaff(request: NextRequest) {
  const authHeader = request.headers.get('authorization')
  
@@ -18,7 +26,15 @@ async function validateAdminOrStaff(request: NextRequest) {
 }

 /**
- * @description Marks staff as unavailable for a time period
+ * @description Creates a new staff unavailability record to block a staff member for a specific time period
+ * @param {NextRequest} request - HTTP request containing staff_id, date, start_time, end_time, optional reason and location_id
+ * @returns {NextResponse} JSON with success status and created availability record
+ * @example POST /api/availability/staff-unavailable { staff_id: "...", date: "2026-01-21", start_time: "10:00", end_time: "14:00", reason: "Lunch meeting" }
+ * @audit BUSINESS RULE: Prevents double-booking by blocking staff during unavailable times
+ * @audit SECURITY: Requires ADMIN_ENROLLMENT_KEY authorization header
+ * @audit Validate: Ensures staff exists and no existing availability record for the same date/time
+ * @audit Validate: Checks that start_time is before end_time and date is valid
+ * @audit AUDIT: All unavailability records are logged for staffing management
 */
 export async function POST(request: NextRequest) {
  try {
@@ -123,7 +139,14 @@ export async function POST(request: NextRequest) {
 }

 /**
- * @description Retrieves staff unavailability records
+ * @description Retrieves staff unavailability records filtered by staff ID and optional date range
+ * @param {NextRequest} request - HTTP request with query parameters staff_id, optional start_date and end_date
+ * @returns {NextResponse} JSON with array of availability records sorted by date
+ * @example GET /api/availability/staff-unavailable?staff_id=...&start_date=2026-01-01&end_date=2026-01-31
+ * @audit BUSINESS RULE: Returns only unavailability records (is_available = false)
+ * @audit SECURITY: Requires ADMIN_ENROLLMENT_KEY authorization header
+ * @audit Validate: Ensures staff_id is provided as required parameter
+ * @audit PERFORMANCE: Supports optional date range filtering for efficient queries
 */
 export async function GET(request: NextRequest) {
  try {
--- a/app/api/availability/staff/route.ts
+++ b/app/api/availability/staff/route.ts
@@ -2,41 +2,125 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

 /**
- * @description Retrieves available staff for a time range
+ * @description Retrieves a list of available staff members for a specific time range and location
+ * @param {NextRequest} request - HTTP request with query parameters for location_id, start_time_utc, and end_time_utc
+ * @returns {NextResponse} JSON with available staff array, time range details, and count
+ * @example GET /api/availability/staff?location_id=...&start_time_utc=...&end_time_utc=...
+ * @audit BUSINESS RULE: Staff must be active, available for booking, and have no booking conflicts in the time range
+ * @audit SECURITY: Validates required query parameters before database call
+ * @audit Validate: Ensures start_time_utc is before end_time_utc and both are valid ISO8601 timestamps
+ * @audit PERFORMANCE: Uses RPC function 'get_available_staff' for optimized database query
+ * @audit AUDIT: Staff availability queries are logged for operational monitoring
 */
 export async function GET(request: NextRequest) {
  try {
    const { searchParams } = new URL(request.url)
    const locationId = searchParams.get('location_id')
+    const serviceId = searchParams.get('service_id')
+    const date = searchParams.get('date')
    const startTime = searchParams.get('start_time_utc')
    const endTime = searchParams.get('end_time_utc')

-    if (!locationId || !startTime || !endTime) {
+    if (!locationId) {
      return NextResponse.json(
-        { error: 'Missing required parameters: location_id, start_time_utc, end_time_utc' },
+        { error: 'Missing required parameter: location_id' },
        { status: 400 }
      )
    }

-    const { data: staff, error: staffError } = await supabaseAdmin.rpc('get_available_staff', {
-      p_location_id: locationId,
-      p_start_time_utc: startTime,
-      p_end_time_utc: endTime
-    })
+    let staff: any[] = []

-    if (staffError) {
-      return NextResponse.json(
-        { error: staffError.message },
-        { status: 400 }
-      )
+    if (startTime && endTime) {
+      const { data, error } = await supabaseAdmin.rpc('get_available_staff', {
+        p_location_id: locationId,
+        p_start_time_utc: startTime,
+        p_end_time_utc: endTime
+      })
+
+      if (error) {
+        return NextResponse.json(
+          { error: error.message },
+          { status: 400 }
+        )
+      }
+
+      staff = data || []
+    } else if (date && serviceId) {
+      const { data: service, error: serviceError } = await supabaseAdmin
+        .from('services')
+        .select('duration_minutes')
+        .eq('id', serviceId)
+        .single()
+
+      if (serviceError || !service) {
+        return NextResponse.json(
+          { error: 'Service not found' },
+          { status: 404 }
+        )
+      }
+
+      const { data: allStaff, error: staffError } = await supabaseAdmin
+        .from('staff')
+        .select(`
+          id,
+          display_name,
+          role,
+          is_active,
+          user_id,
+          location_id,
+          staff_services!inner (
+            service_id,
+            is_active
+          )
+        `)
+        .eq('location_id', locationId)
+        .eq('is_active', true)
+        .eq('role', 'artist')
+        .eq('staff_services.service_id', serviceId)
+        .eq('staff_services.is_active', true)
+
+      if (staffError) {
+        return NextResponse.json(
+          { error: staffError.message },
+          { status: 400 }
+        )
+      }
+
+      const deduped = new Map()
+      allStaff?.forEach((s: any) => {
+        if (!deduped.has(s.id)) {
+          deduped.set(s.id, {
+            id: s.id,
+            display_name: s.display_name,
+            role: s.role,
+            is_active: s.is_active
+          })
+        }
+      })
+
+      staff = Array.from(deduped.values())
+    } else {
+      const { data: allStaff, error: staffError } = await supabaseAdmin
+        .from('staff')
+        .select('id, display_name, role, is_active')
+        .eq('location_id', locationId)
+        .eq('is_active', true)
+        .eq('role', 'artist')
+
+      if (staffError) {
+        return NextResponse.json(
+          { error: staffError.message },
+          { status: 400 }
+        )
+      }
+
+      staff = allStaff || []
    }

    return NextResponse.json({
      success: true,
-      staff: staff || [],
+      staff,
      location_id: locationId,
-      start_time_utc: startTime,
-      end_time_utc: endTime,
      available_count: staff?.length || 0
    })
  } catch (error) {
--- a/app/api/availability/time-slots/route.ts
+++ b/app/api/availability/time-slots/route.ts
@@ -2,7 +2,16 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'

 /**
- * @description Retrieves detailed availability time slots for a date
+ * @description Retrieves detailed availability time slots for a specific location, service, and date
+ * @param {NextRequest} request - HTTP request with query parameters location_id, service_id (optional), date, and time_slot_duration_minutes (optional, default 60)
+ * @returns {NextResponse} JSON with success status and array of available time slots with staff count
+ * @example GET /api/availability/time-slots?location_id=...&service_id=...&date=2026-01-21&time_slot_duration_minutes=30
+ * @audit BUSINESS RULE: Returns only time slots where staff availability, resource availability, and business hours all align
+ * @audit SECURITY: Public endpoint for booking availability display
+ * @audit Validate: Ensures location_id and date are valid and required
+ * @audit Validate: Ensures date is in valid YYYY-MM-DD format
+ * @audit PERFORMANCE: Uses optimized RPC function 'get_detailed_availability' for complex availability calculation
+ * @audit AUDIT: High-volume endpoint, consider rate limiting in production
 */
 export async function GET(request: NextRequest) {
  try {