care-book-block-ultimate/.specify/plan.md

Implementation Plan - Care Book Block Ultimate

Project: WordPress Plugin for KiviCare Appointment Control
Branch: feature/wordpress-plugin-kivicare-appointment-control
Created: 2025-09-12
Context7 MCP: ✅ Active
Web Research: ✅ Completed

---

🚨 CRITICAL COMPATIBILITY UPDATES

Based on Web Research Obrigatória findings:

🔴 SECURITY-CRITICAL UPDATES REQUIRED

• PHP 7.4: EOL since Nov 2022 - UPGRADE to PHP 8.1+ MANDATORY
• MySQL 5.7: EOL since Oct 2023 - UPGRADE to MySQL 8.0+ REQUIRED
• Impact: Current minimum requirements expose to critical vulnerabilities

✅ Updated Tech Stack (Security-Validated)

Production Stack:
  PHP: 8.1+ (LTS) or 8.4+ (Latest - supported until 2028)
  WordPress: 6.8+ (Latest annual release)
  MySQL: 8.0.35+ (Performance + Security)
  KiviCare: 3.6.8+ (Latest security fixes - Feb 2025)
  Composer: Latest (PSR-4 autoloading)

---

🏗️ ARCHITECTURAL DESIGN

Core Architecture Pattern: CSS-First + Hook-Based Integration

graph TB
    A[WordPress Frontend] --> B[CSS Injection Layer]
    B --> C[Visual Element Hiding]
    C --> D[PHP Hook Layer]
    D --> E[Data Filtering]
    E --> F[Cache Layer]
    F --> G[Database Layer]
    
    H[Admin Interface] --> I[AJAX Endpoints]
    I --> J[Restriction Management]
    J --> F
    
    K[KiviCare Plugin] --> D

Database Architecture

-- Updated for MySQL 8.0+ compatibility
CREATE TABLE wp_care_booking_restrictions (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    doctor_id BIGINT UNSIGNED NOT NULL,
    service_id BIGINT UNSIGNED NULL COMMENT 'NULL = applies to all services',
    restriction_type ENUM('hide_doctor', 'hide_service', 'hide_combination') NOT NULL,
    is_active BOOLEAN DEFAULT true,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    created_by BIGINT UNSIGNED,
    metadata JSON NULL COMMENT 'MySQL 8.0+ JSON support for flexible data',
    
    INDEX idx_doctor_service (doctor_id, service_id),
    INDEX idx_active_restrictions (is_active, restriction_type),
    INDEX idx_created_at (created_at),
    FOREIGN KEY (doctor_id) REFERENCES wp_kc_doctors(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

PSR-4 Namespace Structure (2024-2025 Best Practices)

<?php
namespace CareBook\Ultimate\{
    Core\,
    Admin\,
    Models\,
    Services\,
    Integrations\KiviCare\,
    Cache\,
    Security\
}

// Composer autoload configuration
{
  "autoload": {
    "psr-4": {
      "CareBook\\Ultimate\\": "src/"
    }
  },
  "require": {
    "php": ">=8.1"
  }
}

---

📊 IMPLEMENTATION PHASES

Phase 0: Foundation & Security Updates ⭐ NEW

Duration: 2-3 days
Priority: CRITICAL

Tasks:

• Update development environment to PHP 8.1+/8.4
• Update MySQL to 8.0.35+
• Test WordPress 6.8 compatibility
• Verify KiviCare 3.6.8+ integration points
• Setup Composer with PSR-4 autoloading
• Create modern PHP 8+ plugin structure

Deliverables:

• ✅ Security-compliant development environment
• ✅ Modern PSR-4 plugin structure
• ✅ Updated compatibility documentation

---

Phase 1: Core Foundation (Week 1)

Duration: 5 days
Dependencies: Phase 0 complete

Tasks:

• Plugin main file with PHP 8.1+ features

  <?php
  /**
   * Plugin Name: Care Book Block Ultimate
   * PHP Version: 8.1+
   * WordPress Version: 6.0+
   * KiviCare Version: 3.6.8+
   */
  declare(strict_types=1);
  
  namespace CareBook\Ultimate;
  
  if (!defined('ABSPATH')) {
      exit;
  }
  
  require_once __DIR__ . '/vendor/autoload.php';
  

• Database migration system

  • MySQL 8.0+ optimized schema
  • JSON metadata support
  • Proper indexing strategy
  • Migration rollback capability

• WordPress Admin interface foundation

  • Modern admin UI components
  • AJAX-ready architecture
  • Security nonces implementation
  • Capability-based access control

• Core restriction models with PHP 8+ features

  <?php
  declare(strict_types=1);
  
  namespace CareBook\Ultimate\Models;
  
  readonly class Restriction {
      public function __construct(
          public int $id,
          public int $doctorId,
          public ?int $serviceId,
          public RestrictionType $type,
          public bool $isActive = true,
          public ?\DateTimeImmutable $createdAt = null
      ) {}
  }
  
  enum RestrictionType: string {
      case HIDE_DOCTOR = 'hide_doctor';
      case HIDE_SERVICE = 'hide_service';  
      case HIDE_COMBINATION = 'hide_combination';
  }
  

Deliverables:

• ✅ Modern PHP 8+ plugin structure
• ✅ Database schema with MySQL 8.0+ features
• ✅ Admin interface foundation
• ✅ Core domain models

---

Phase 2: Core Features (Week 2)

Duration: 7 days
Dependencies: Phase 1 complete

Tasks:

• CSS injection system

  <?php
  namespace CareBook\Ultimate\Services;
  
  class CssInjectionService {
      public function injectRestrictionStyles(): void {
          $restrictions = $this->getActiveRestrictions();
          $css = $this->generateHidingCss($restrictions);
  
          wp_add_inline_style('kivicare-frontend', $css);
      }
  
      private function generateHidingCss(array $restrictions): string {
          // Generate CSS to immediately hide restricted elements
          return $this->buildSelectorCss($restrictions);
      }
  }
  

• KiviCare integration hooks

  <?php
  namespace CareBook\Ultimate\Integrations\KiviCare;
  
  class HookManager {
      public function registerHooks(): void {
          add_filter('kivicare_available_doctors', [$this, 'filterDoctors'], 10, 2);
          add_filter('kivicare_available_services', [$this, 'filterServices'], 10, 2);
          add_action('kivicare_before_booking_form', [$this, 'injectCss']);
      }
  }
  

• AJAX endpoints with modern security

  <?php
  namespace CareBook\Ultimate\Admin;
  
  class AjaxHandler {
      public function registerEndpoints(): void {
          add_action('wp_ajax_care_toggle_restriction', [$this, 'toggleRestriction']);
          add_action('wp_ajax_care_bulk_update', [$this, 'bulkUpdate']);
      }
  
      public function toggleRestriction(): void {
          $this->validateNonce();
          $this->checkCapabilities();
  
          // Modern PHP 8+ request handling
          $request = $this->validateRequest($_POST);
          $result = $this->restrictionService->toggle($request);
  
          wp_send_json_success($result);
      }
  }
  

• Caching layer with WordPress Transients

  <?php
  namespace CareBook\Ultimate\Cache;
  
  class RestrictionCache {
      private const CACHE_KEY = 'care_booking_restrictions';
      private const CACHE_EXPIRATION = 3600; // 1 hour
  
      public function getRestrictions(): array {
          $cached = get_transient(self::CACHE_KEY);
          if ($cached !== false) {
              return $cached;
          }
  
          $restrictions = $this->loadFromDatabase();
          set_transient(self::CACHE_KEY, $restrictions, self::CACHE_EXPIRATION);
  
          return $restrictions;
      }
  }
  

Deliverables:

• ✅ CSS injection system
• ✅ KiviCare integration hooks
• ✅ AJAX admin interface
• ✅ Intelligent caching system

---

Phase 3: Enhancement & Optimization (Week 3-4)

Duration: 10 days
Dependencies: Phase 2 complete

Tasks:

• Bulk operations interface

• Export/import functionality with JSON

• Audit logging system

• Performance optimization

  • Query optimization for MySQL 8.0
  • Advanced caching strategies
  • CSS minification
  • AJAX request batching

• Modern testing suite

  <?php
  namespace CareBook\Ultimate\Tests;
  
  use PHPUnit\Framework\TestCase;
  use CareBook\Ultimate\Models\Restriction;
  
  class RestrictionTest extends TestCase {
      public function testRestrictionCreation(): void {
          $restriction = new Restriction(
              id: 1,
              doctorId: 123,
              serviceId: null,
              type: RestrictionType::HIDE_DOCTOR
          );
  
          $this->assertEquals(123, $restriction->doctorId);
          $this->assertEquals(RestrictionType::HIDE_DOCTOR, $restriction->type);
      }
  }
  

Deliverables:

• ✅ Advanced admin features
• ✅ Import/export system
• ✅ Performance-optimized code
• ✅ Comprehensive test suite

---

🧪 TESTING STRATEGY (Updated for PHP 8+)

Unit Tests (PHPUnit 10+)

# Modern PHP 8+ testing
composer require --dev phpunit/phpunit:^10.0
composer require --dev mockery/mockery

# Run tests
./vendor/bin/phpunit tests/

Integration Tests

• WordPress 6.6, 6.7, 6.8 compatibility
• KiviCare 3.6.8+ integration
• MySQL 8.0+ query testing
• PHP 8.1/8.4 compatibility testing

Performance Benchmarks

• Page load impact: <5% (target: <2% with modern stack)
• AJAX response: <200ms (target: <100ms with PHP 8+)
• Cache efficiency: >90% hit ratio
• MySQL 8.0 query optimization

---

📈 PERFORMANCE TARGETS (Updated)

With Modern Stack (PHP 8.4 + MySQL 8.0)

• Page Load Overhead: <2% (improved from <5%)
• AJAX Response Time: <100ms (improved from <200ms)
• Database Query Time: <50ms (MySQL 8.0 optimization)
• Cache Hit Ratio: >95% (improved caching strategy)
• Memory Usage: <10MB additional (PHP 8 efficiency)

---

🔒 SECURITY IMPLEMENTATION (PHP 8+ Features)

Input Validation & Sanitization

<?php
namespace CareBook\Ultimate\Security;

class InputValidator {
    public function validateRestrictionRequest(array $data): ValidatedRequest {
        return new ValidatedRequest(
            doctorId: $this->validatePositiveInt($data['doctor_id'] ?? null),
            serviceId: $this->validateOptionalPositiveInt($data['service_id'] ?? null),
            restrictionType: RestrictionType::from($data['type'] ?? ''),
            isActive: $this->validateBoolean($data['is_active'] ?? true)
        );
    }
    
    private function validatePositiveInt(?string $value): int {
        if ($value === null) {
            throw new InvalidArgumentException('Required integer value is missing');
        }
        
        $int = filter_var($value, FILTER_VALIDATE_INT);
        if ($int === false || $int <= 0) {
            throw new InvalidArgumentException('Invalid positive integer');
        }
        
        return $int;
    }
}

Capability-Based Access Control

<?php
namespace CareBook\Ultimate\Security;

class AccessControl {
    public function canManageRestrictions(): bool {
        return current_user_can('manage_care_booking_restrictions') 
            || current_user_can('administrator');
    }
    
    public function validateNonce(string $action): void {
        if (!wp_verify_nonce($_POST['_wpnonce'] ?? '', $action)) {
            wp_die(__('Security check failed', 'care-book-ultimate'), 403);
        }
    }
}

---

🌐 WEB RESEARCH INSIGHTS INTEGRATION

PSR-4 Best Practices (2024-2025)

• ✅ Modern Composer autoloading
• ✅ Namespace organization
• ✅ File naming conventions (ignore WordPress standards for internal classes)
• ✅ Case-sensitive autoloading considerations

WordPress Plugin Development Trends

• ✅ Annual WordPress releases (6.8+ targeting)
• ✅ Modern PHP features adoption
• ✅ Security-first development
• ✅ Performance optimization focus

Technology Compatibility Matrix

Compatible Technologies:
  ✅ WordPress 6.8+ (latest, secure)
  ✅ KiviCare 3.6.8+ (latest, secure)
  ✅ PHP 8.1+/8.4 (secure, performant)
  ✅ MySQL 8.0+ (secure, performant)
  ✅ Composer PSR-4 (industry standard)

Deprecated/EOL (Do Not Use):
  ❌ PHP 7.4 (EOL, vulnerable)
  ❌ MySQL 5.7 (EOL, limited support)
  ❌ WordPress <6.0 (security concerns)
  ❌ KiviCare <3.6.8 (security vulnerabilities)

---

🎯 SUCCESS CRITERIA & VALIDATION

Functional Requirements

• ✅ Doctor/service restrictions working in real-time
• ✅ Admin interface intuitive (<30s learning curve)
• ✅ Zero KiviCare core modifications
• ✅ Bulk operations efficient

Technical Requirements

• ✅ PHP 8.1+ compatibility
• ✅ MySQL 8.0+ optimized
• ✅ WordPress 6.8+ compatible
• ✅ KiviCare 3.6.8+ integrated
• ✅ PSR-4 autoloading implemented
• ✅ Security standards met (nonces, sanitization, capabilities)

Performance Requirements

• ✅ Page load overhead <2% (with modern stack)
• ✅ AJAX response <100ms (PHP 8+ performance)
• ✅ Cache hit ratio >95%
• ✅ Database queries optimized for MySQL 8.0

---

🚨 RISK MITIGATION UPDATED

Security Risks (RESOLVED)

• ✅ PHP 7.4 vulnerabilities: Upgraded to PHP 8.1+
• ✅ MySQL 5.7 EOL: Upgraded to MySQL 8.0+
• ✅ Outdated dependencies: Updated to latest secure versions

Technical Risks

• KiviCare Updates: Hook-based integration (no core modifications)
• Performance Impact: Modern stack + optimized caching
• Plugin Conflicts: Proper namespacing + defensive coding
• PHP 8 Breaking Changes: Comprehensive testing on PHP 8.1/8.4

Migration Risks

• PHP 7.4 → 8.1+ Migration: Code audit + testing required
• MySQL 5.7 → 8.0 Migration: Query compatibility testing
• Compatibility Testing: Multi-version testing matrix

---

📅 UPDATED TIMELINE

Phase	Duration	Focus	Deliverables
Phase 0	2-3 days	Security Updates	Modern dev environment
Phase 1	5 days	Foundation	Plugin structure, database
Phase 2	7 days	Core Features	CSS injection, hooks, AJAX
Phase 3	10 days	Enhancement	Optimization, testing, docs
Total	3-4 weeks	Complete Plugin	Production-ready system

---

✅ NEXT STEPS

1. Execute Phase 0: Update development environment to secure stack
2. Context7 Consultation: Query for architectural recommendations
3. Dify Specialist Review: Validate plan with expert consultation
4. Begin Implementation: Start Phase 1 with modern foundation
5. Continuous Testing: Multi-version compatibility validation

---

Plan Status: ✅ Complete with Security Updates
Web Research: ✅ Technology compatibility validated
Context7 MCP: ✅ Active and ready for consultation
Next Command: /tasks to generate detailed task breakdown