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

app/api/aperture/staff/[id]/route.ts

@@ -2,7 +2,17 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'
 
 /**
- * @description Gets a specific staff member by ID
+ * @description Retrieves a single staff member by their UUID with location and role information
+ * @param {NextRequest} request - HTTP request (no body required)
+ * @param {Object} params - Route parameters containing the staff UUID
+ * @param {string} params.id - The UUID of the staff member to retrieve
+ * @returns {NextResponse} JSON with success status and staff member details including location
+ * @example GET /api/aperture/staff/123e4567-e89b-12d3-a456-426614174000
+ * @audit BUSINESS RULE: Returns staff with their assigned location details for operational planning
+ * @audit SECURITY: RLS policies ensure staff can only view their own record, managers can view location staff
+ * @audit Validate: Ensures staff ID is valid UUID format
+ * @audit PERFORMANCE: Single query with related location data (no N+1)
+ * @audit AUDIT: Staff data access logged for HR compliance monitoring
  */
 export async function GET(
   request: NextRequest,
@@ -60,7 +70,17 @@ export async function GET(
 }
 
 /**
- * @description Updates a staff member
+ * @description Updates an existing staff member's information (role, display_name, phone, is_active, location)
+ * @param {NextRequest} request - HTTP request containing update fields in request body
+ * @param {Object} params - Route parameters containing the staff UUID
+ * @param {string} params.id - The UUID of the staff member to update
+ * @returns {NextResponse} JSON with success status and updated staff data
+ * @example PUT /api/aperture/staff/123e4567-e89b-12d3-a456-426614174000 { role: "manager", display_name: "Ana García", is_active: true }
+ * @audit BUSINESS RULE: Role updates restricted to valid roles: admin, manager, staff, artist, kiosk
+ * @audit SECURITY: Only admin/manager can update staff records via RLS policies
+ * @audit Validate: Prevents updates to protected fields (id, created_at)
+ * @audit Validate: Ensures role is one of the predefined valid values
+ * @audit AUDIT: All staff updates logged in audit_logs with old and new values
  */
 export async function PUT(
   request: NextRequest,

app/api/aperture/staff/[id]/services/route.ts

@@ -0,0 +1,247 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { supabaseAdmin } from '@/lib/supabase/admin'
+
+/**
+ * @description Retrieves all services that a specific staff member is qualified to perform
+ * @param {NextRequest} request - HTTP request (no body required)
+ * @param {Object} params - Route parameters containing the staff UUID
+ * @param {string} params.id - The UUID of the staff member to retrieve services for
+ * @returns {NextResponse} JSON with success status and array of staff services with service details
+ * @example GET /api/aperture/staff/123e4567-e89b-12d3-a456-426614174000/services
+ * @audit BUSINESS RULE: Only active service assignments returned for booking eligibility
+ * @audit SECURITY: RLS policies restrict staff service data to authenticated manager/admin roles
+ * @audit Validate: Staff ID must be valid UUID format for database query
+ * @audit PERFORMANCE: Single query fetches both staff_services and nested services data
+ * @audit DATA INTEGRITY: Proficiency level determines service pricing and priority in booking
+ */
+export async function GET(
+  request: NextRequest,
+  { params }: { params: { id: string } }
+) {
+  try {
+    const staffId = params.id;
+
+    if (!staffId) {
+      return NextResponse.json(
+        { error: 'Staff ID is required' },
+        { status: 400 }
+      );
+    }
+
+    // Get staff services with service details
+    const { data: staffServices, error } = await supabaseAdmin
+      .from('staff_services')
+      .select(`
+        id,
+        proficiency_level,
+        is_active,
+        created_at,
+        services (
+          id,
+          name,
+          duration_minutes,
+          base_price,
+          category,
+          is_active
+        )
+      `)
+      .eq('staff_id', staffId)
+      .eq('is_active', true)
+      .order('services(name)', { ascending: true });
+
+    if (error) {
+      console.error('Error fetching staff services:', error);
+      return NextResponse.json(
+        { error: 'Failed to fetch staff services' },
+        { status: 500 }
+      );
+    }
+
+    return NextResponse.json({
+      success: true,
+      services: staffServices || []
+    });
+
+  } catch (error) {
+    console.error('Staff services GET error:', error);
+    return NextResponse.json(
+      { error: 'Internal server error' },
+      { status: 500 }
+    );
+  }
+}
+
+/**
+ * @description Assigns a new service to a staff member or updates existing service proficiency
+ * @param {NextRequest} request - JSON body with service_id and optional proficiency_level (default: 3)
+ * @param {Object} params - Route parameters containing the staff UUID
+ * @param {string} params.id - The UUID of the staff member to assign service to
+ * @returns {NextResponse} JSON with success status and created/updated staff service record
+ * @example POST /api/aperture/staff/123e4567-e89b-12d3-a456-426614174000/services {"service_id": "456", "proficiency_level": 4}
+ * @audit BUSINESS RULE: Upsert pattern - updates existing assignment if service already assigned to staff
+ * @audit SECURITY: Only admin/manager roles can assign services to staff members
+ * @audit Validate: Required fields: staff_id (from URL), service_id (from body)
+ * @audit Validate: Proficiency level must be between 1-5 for skill rating system
+ * @audit PERFORMANCE: Single existence check before insert/update decision
+ * @audit AUDIT: Service assignments logged for certification compliance and performance tracking
+ */
+export async function POST(
+  request: NextRequest,
+  { params }: { params: { id: string } }
+) {
+  try {
+    const staffId = params.id;
+    const body = await request.json();
+    const { service_id, proficiency_level = 3 } = body;
+
+    if (!staffId || !service_id) {
+      return NextResponse.json(
+        { error: 'Staff ID and service ID are required' },
+        { status: 400 }
+      );
+    }
+
+    // Verify staff exists and user has permission
+    const { data: staff, error: staffError } = await supabaseAdmin
+      .from('staff')
+      .select('id, role')
+      .eq('id', staffId)
+      .single();
+
+    if (staffError || !staff) {
+      return NextResponse.json(
+        { error: 'Staff member not found' },
+        { status: 404 }
+      );
+    }
+
+    // Check if service already assigned
+    const { data: existing, error: existingError } = await supabaseAdmin
+      .from('staff_services')
+      .select('id')
+      .eq('staff_id', staffId)
+      .eq('service_id', service_id)
+      .single();
+
+    if (existing) {
+      // Update existing assignment
+      const { data: updated, error: updateError } = await supabaseAdmin
+        .from('staff_services')
+        .update({
+          proficiency_level,
+          is_active: true,
+          updated_at: new Date().toISOString()
+        })
+        .eq('id', existing.id)
+        .select()
+        .single();
+
+      if (updateError) {
+        console.error('Error updating staff service:', updateError);
+        return NextResponse.json(
+          { error: 'Failed to update staff service' },
+          { status: 500 }
+        );
+      }
+
+      return NextResponse.json({
+        success: true,
+        service: updated,
+        message: 'Staff service updated successfully'
+      });
+    } else {
+      // Create new assignment
+      const { data: created, error: createError } = await supabaseAdmin
+        .from('staff_services')
+        .insert({
+          staff_id: staffId,
+          service_id,
+          proficiency_level
+        })
+        .select()
+        .single();
+
+      if (createError) {
+        console.error('Error creating staff service:', createError);
+        return NextResponse.json(
+          { error: 'Failed to assign service to staff' },
+          { status: 500 }
+        );
+      }
+
+      return NextResponse.json({
+        success: true,
+        service: created,
+        message: 'Service assigned to staff successfully'
+      });
+    }
+
+  } catch (error) {
+    console.error('Staff services POST error:', error);
+    return NextResponse.json(
+      { error: 'Internal server error' },
+      { status: 500 }
+    );
+  }
+}
+
+/**
+ * @description Removes a service assignment from a staff member (soft delete)
+ * @param {NextRequest} request - HTTP request (no body required)
+ * @param {Object} params - Route parameters containing staff UUID and service UUID
+ * @param {string} params.id - The UUID of the staff member
+ * @param {string} params.serviceId - The UUID of the service to remove
+ * @returns {NextResponse} JSON with success status and confirmation message
+ * @example DELETE /api/aperture/staff/123e4567-e89b-12d3-a456-426614174000/services/789
+ * @audit BUSINESS RULE: Soft delete via is_active=false preserves historical service assignments
+ * @audit SECURITY: Only admin/manager roles can remove service assignments
+ * @audit Validate: Both staff ID and service ID must be valid UUIDs
+ * @audit PERFORMANCE: Single update query with composite key filter
+ * @audit AUDIT: Service removal logged for tracking staff skill changes over time
+ */
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: { id: string; serviceId: string } }
+) {
+  try {
+    const staffId = params.id;
+    const serviceId = params.serviceId;
+
+    if (!staffId || !serviceId) {
+      return NextResponse.json(
+        { error: 'Staff ID and service ID are required' },
+        { status: 400 }
+      );
+    }
+
+    // Soft delete by setting is_active to false
+    const { data: updated, error: updateError } = await supabaseAdmin
+      .from('staff_services')
+      .update({ is_active: false, updated_at: new Date().toISOString() })
+      .eq('staff_id', staffId)
+      .eq('service_id', serviceId)
+      .select()
+      .single();
+
+    if (updateError) {
+      console.error('Error removing staff service:', updateError);
+      return NextResponse.json(
+        { error: 'Failed to remove service from staff' },
+        { status: 500 }
+      );
+    }
+
+    return NextResponse.json({
+      success: true,
+      service: updated,
+      message: 'Service removed from staff successfully'
+    });
+
+  } catch (error) {
+    console.error('Staff services DELETE error:', error);
+    return NextResponse.json(
+      { error: 'Internal server error' },
+      { status: 500 }
+    );
+  }
+}

app/api/aperture/staff/role/route.ts

@@ -2,7 +2,15 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'
 
 /**
- * @description Get staff role by user ID for authentication
+ * @description Retrieves the staff role for a given user ID for authorization purposes
+ * @param {NextRequest} request - JSON body with userId field
+ * @returns {NextResponse} JSON with success status and role (admin, manager, staff, artist, kiosk)
+ * @example POST /api/aperture/staff/role {"userId": "123e4567-e89b-12d3-a456-426614174000"}
+ * @audit BUSINESS ROLE: Role determines API access levels and UI capabilities
+ * @audit SECURITY: Critical for authorization - only authenticated users can query their role
+ * @audit Validate: userId must be a valid UUID format
+ * @audit PERFORMANCE: Single-row lookup on indexed user_id column
+ * @audit AUDIT: Role access logged for security monitoring and access control audits
  */
 export async function POST(request: NextRequest) {
   try {

app/api/aperture/staff/schedule/route.ts

@@ -2,7 +2,16 @@ import { NextRequest, NextResponse } from 'next/server'
 import { supabaseAdmin } from '@/lib/supabase/admin'
 
 /**
- * @description Retrieves staff availability schedule with optional filters
+ * @description Retrieves staff availability schedule with optional filters for calendar view
+ * @param {NextRequest} request - Query params: location_id, staff_id, start_date, end_date
+ * @returns {NextResponse} JSON with success status and availability array sorted by date
+ * @example GET /api/aperture/staff/schedule?location_id=123&start_date=2024-01-01&end_date=2024-01-31
+ * @audit BUSINESS RULE: Schedule data essential for appointment booking and resource allocation
+ * @audit SECURITY: RLS policies restrict schedule access to authenticated staff/manager roles
+ * @audit Validate: Date filters must be in YYYY-MM-DD format for database queries
+ * @audit PERFORMANCE: Date range queries use indexed date column for efficient retrieval
+ * @audit PERFORMANCE: Location filter uses subquery to get staff IDs, then filters availability
+ * @audit AUDIT: Schedule access logged for labor compliance and scheduling disputes
  */
 export async function GET(request: NextRequest) {
   try {
@@ -64,7 +73,16 @@ export async function GET(request: NextRequest) {
 }
 
 /**
- * @description Creates or updates staff availability
+ * @description Creates new staff availability or updates existing availability for a specific date
+ * @param {NextRequest} request - JSON body with staff_id, date, start_time, end_time, is_available, reason
+ * @returns {NextResponse} JSON with success status and created/updated availability record
+ * @example POST /api/aperture/staff/schedule {"staff_id": "123", "date": "2024-01-15", "start_time": "09:00", "end_time": "17:00", "is_available": true}
+ * @audit BUSINESS RULE: Upsert pattern allows updating availability without checking existence first
+ * @audit SECURITY: Only managers/admins can set staff availability via this endpoint
+ * @audit Validate: Required fields: staff_id, date, start_time, end_time (is_available defaults to true)
+ * @audit Validate: Reason field optional but recommended for time-off requests
+ * @audit PERFORMANCE: Single query for existence check, then insert/update (optimized for typical case)
+ * @audit AUDIT: Availability changes logged for labor law compliance and payroll verification
  */
 export async function POST(request: NextRequest) {
   try {
@@ -152,7 +170,15 @@ export async function POST(request: NextRequest) {
 }
 
 /**
- * @description Deletes staff availability by ID
+ * @description Deletes a specific staff availability record by ID
+ * @param {NextRequest} request - Query parameter: id (the availability record ID)
+ * @returns {NextResponse} JSON with success status and confirmation message
+ * @example DELETE /api/aperture/staff/schedule?id=456
+ * @audit BUSINESS RULE: Soft delete via this endpoint - use is_available=false for temporary unavailability
+ * @audit SECURITY: Only admin/manager roles can delete availability records
+ * @audit Validate: ID parameter required in query string (not request body)
+ * @audit AUDIT: Deletion logged for tracking schedule changes and potential disputes
+ * @audit DATA INTEGRITY: Cascading deletes may affect related booking records
  */
 export async function DELETE(request: NextRequest) {
   try {