care-book-block-ultimate/specs/001-wordpress-plugin-para/quickstart.md

# Quickstart Guide: Care Booking Block Plugin

**Feature**: WordPress Plugin para Controlo Seguro de Agendamentos KiviCare  
**Date**: 2025-09-10  
**Purpose**: End-to-end validation scenarios for testing

## Prerequisites Validation

### Environment Setup
```bash
# 1. WordPress 5.0+ installation
wp core version --allow-root
# Expected: 5.0.0 or higher

# 2. KiviCare plugin active
wp plugin status kivicare --allow-root
# Expected: Status: Active

# 3. PHP version check
php -v
# Expected: PHP 7.4+ 

# 4. Database access
wp db check --allow-root
# Expected: Success
```

### Test Data Setup
```sql
-- Ensure test doctors exist in KiviCare
INSERT INTO wp_kc_doctors (id, name, email) VALUES 
(999, 'Test Doctor 1', 'test1@clinic.com'),
(998, 'Test Doctor 2', 'test2@clinic.com');

-- Ensure test services exist
INSERT INTO wp_kc_services (id, name, doctor_id) VALUES
(888, 'Test Service 1', 999),
(887, 'Test Service 2', 999);
```

## Installation & Activation Test

### Step 1: Plugin Installation
```bash
# Upload plugin to WordPress
cp -r care-booking-block/ /wp-content/plugins/

# Activate plugin via WP-CLI
wp plugin activate care-booking-block --allow-root
```

**Expected Outcome**: 
- Plugin activates without errors
- Database table `wp_care_booking_restrictions` created
- Admin menu "Care Booking Control" appears

**Validation**:
```sql
-- Check table creation
DESCRIBE wp_care_booking_restrictions;

-- Check WordPress options
SELECT option_value FROM wp_options WHERE option_name = 'care_booking_plugin_version';
```

### Step 2: Admin Interface Access
```bash
# Navigate to admin interface
# URL: /wp-admin/admin.php?page=care-booking-control
```

**Expected Outcome**:
- Admin page loads without errors
- List of doctors from KiviCare displayed
- Toggle switches for each doctor visible
- No PHP errors in debug.log

## Core Functionality Tests

### Test Scenario 1: Block Doctor from Public Booking

**User Story**: Administrator blocks Dr. Test Doctor 1 from public appointments

**Steps**:
1. Navigate to Care Booking Control admin page
2. Find "Test Doctor 1" in the list
3. Click toggle to block doctor
4. Save changes

**Expected Outcome**:
```json
// AJAX Response
{
    "success": true,
    "data": {
        "message": "Restriction updated successfully",
        "restriction": {
            "restriction_type": "doctor",
            "target_id": 999,
            "is_blocked": true
        }
    }
}
```

**Database Validation**:
```sql
SELECT * FROM wp_care_booking_restrictions 
WHERE restriction_type = 'doctor' AND target_id = 999;
-- Expected: 1 row with is_blocked = 1
```

**Frontend Validation**:
```javascript
// Check if CSS is injected
const hiddenDoctor = document.querySelector('.kivicare-doctor[data-doctor-id="999"]');
const computedStyle = window.getComputedStyle(hiddenDoctor);
console.log(computedStyle.display); // Expected: 'none'
```

### Test Scenario 2: Hide Service for Specific Doctor

**User Story**: Administrator hides "Test Service 2" for "Test Doctor 1"

**Steps**:
1. In admin interface, expand "Test Doctor 1" services
2. Find "Test Service 2" checkbox
3. Uncheck to hide service
4. Save changes

**Expected Outcome**:
```json
// AJAX Response
{
    "success": true,
    "data": {
        "restriction": {
            "restriction_type": "service",
            "target_id": 887,
            "doctor_id": 999,
            "is_blocked": true
        }
    }
}
```

**Frontend Test**:
```php
// KiviCare filter test
$services = apply_filters('kc_get_services_by_doctor', [
    ['id' => 888, 'name' => 'Test Service 1'],
    ['id' => 887, 'name' => 'Test Service 2']
], 999);

// Expected: Only Service 1 in array
assert(count($services) === 1);
assert($services[0]['id'] === 888);
```

### Test Scenario 3: Frontend Booking Form Validation

**User Story**: Patient tries to book appointment and sees filtered options

**Steps**:
1. Navigate to KiviCare booking form on frontend
2. Open doctor selection dropdown
3. Verify blocked doctors not visible
4. Select remaining doctor
5. Check service options for selected doctor

**Expected Outcome**:
- Test Doctor 1 (ID: 999) not in dropdown
- Test Doctor 2 (ID: 998) visible and selectable
- When Test Doctor 1 was selected before blocking, only Test Service 1 visible

**DOM Validation**:
```javascript
// Check doctor dropdown
const doctorOptions = document.querySelectorAll('#doctor-select option');
const blockedDoctorOption = Array.from(doctorOptions)
    .find(option => option.value === '999');
// Expected: undefined (not found)

// Check CSS injection
const injectedCSS = document.querySelector('style[data-care-booking]');
// Expected: Contains .kivicare-doctor[data-doctor-id="999"] { display: none !important; }
```

## Performance Validation

### Response Time Test
```bash
# Test admin AJAX endpoints
time curl -X POST "http://site.com/wp-admin/admin-ajax.php" \
  -d "action=care_booking_get_restrictions&nonce=test_nonce"
# Expected: < 200ms

time curl -X POST "http://site.com/wp-admin/admin-ajax.php" \
  -d "action=care_booking_toggle_restriction&nonce=test_nonce&target_id=999&restriction_type=doctor&is_blocked=true"
# Expected: < 300ms
```

### Page Load Impact Test
```javascript
// Measure frontend page load impact
const startTime = performance.now();
// Load KiviCare booking form page
const loadTime = performance.now() - startTime;
// Expected: < 5% increase over baseline (without plugin)
```

### Cache Validation
```php
// Test cache invalidation
set_transient('care_booking_doctors_blocked', [999], 3600);
// Trigger restriction update
do_action('care_booking_restriction_updated');
// Check cache cleared
$cached = get_transient('care_booking_doctors_blocked');
// Expected: false (cache cleared)
```

## Error Handling Tests

### Test Scenario 4: KiviCare Plugin Deactivated

**Steps**:
1. Deactivate KiviCare plugin
2. Access Care Booking Control admin page
3. Try to access frontend booking form

**Expected Outcome**:
- Admin page shows warning message
- Frontend continues working without errors
- No fatal PHP errors in debug.log

### Test Scenario 5: Database Connection Error

**Steps**:
1. Temporarily block database access
2. Try to load admin interface
3. Try to toggle restriction

**Expected Outcome**:
```json
{
    "success": false,
    "data": {
        "message": "Database error occurred. Please try again.",
        "code": "DB_CONNECTION_ERROR"
    }
}
```

### Test Scenario 6: Invalid Nonce

**Steps**:
1. Send AJAX request with invalid nonce
2. Check response

**Expected Outcome**:
```json
{
    "success": false,
    "data": {
        "message": "Invalid nonce",
        "code": "INVALID_NONCE"
    }
}
```

## Compatibility Tests

### Test Scenario 7: Cache Plugin Compatibility

**Setup**: Install WP Rocket or W3 Total Cache

**Steps**:
1. Enable page caching
2. Block a doctor
3. View frontend booking form
4. Check if changes are visible immediately

**Expected Outcome**:
- Changes visible within cache invalidation timeout
- No cached restrictions shown to users

### Test Scenario 8: Theme Compatibility

**Setup**: Switch to popular WordPress theme

**Steps**:
1. Activate different theme (Twenty Twenty-Three, Astra, etc.)
2. Test admin interface styling
3. Test frontend CSS injection

**Expected Outcome**:
- Admin interface maintains WordPress native styling
- Frontend CSS selectors work across themes

## Success Criteria Validation

### Metrics to Verify
1. **100% restriction compliance**: Blocked doctors/services never appear
2. **<2 minute configuration**: Time administrator to set up restrictions
3. **<5% performance impact**: Page load time increase
4. **Zero critical errors**: No fatal errors in debug.log for 24 hours

### Final Validation Checklist
- [ ] All test scenarios pass
- [ ] Performance targets met
- [ ] Error handling works correctly  
- [ ] Compatibility verified
- [ ] Success metrics achieved
- [ ] Documentation complete

This quickstart guide provides comprehensive validation scenarios to ensure the plugin meets all functional requirements while maintaining system stability.