care-book-block-ultimate/.specify/specs/wordpress-plugin-kivicare-appointment-control.md

WordPress Plugin for KiviCare Appointment Control

📋 Overview

WordPress plugin avançado que permite controlo granular sobre appointments no plugin KiviCare através de sistema de restrições de médicos e serviços.

Feature Name: Care Book Block Ultimate Status: In Specification Priority: High Estimated Effort: 3-4 weeks

🎯 Business Requirements

Problem Statement

O KiviCare permite que todos os médicos tenham appointments disponíveis para todos os serviços, sem possibilidade de controlo granular. Clínicas precisam de:

• Restringir médicos específicos de aparecerem em booking forms
• Controlar quais serviços cada médico pode oferecer
• Ocultar médicos temporariamente sem os desativar permanentemente
• Manter performance otimizada mesmo com milhares de médicos/serviços

Success Criteria

• Redução de appointments incorretos em >90%
• Interface administrativa intuitiva (<30s learning curve)
• Zero impacto na performance existente do KiviCare
• 100% compatibilidade com futuras atualizações do KiviCare

User Stories

• Como administrador clínico, quero poder ocultar médicos específicos do booking form para que apenas médicos disponíveis sejam exibidos
• Como gestor de clínica, quero controlar quais serviços cada médico pode oferecer para evitar appointments incorretos
• Como rececionista, quero ver apenas médicos e serviços relevantes para acelerar o processo de booking
• Como paciente, quero ver apenas opções válidas para não perder tempo com combinações inválidas

🔧 Technical Requirements

Functional Requirements

• Sistema de restrições médico-específicas
• Controlo de visibilidade por serviços
• Interface administrativa AJAX com toggles
• Filtragem em tempo real no booking form
• Sistema de cache inteligente para performance
• Backup/restore de configurações
• Logs de alterações para auditoria
• Export/import de configurações

Non-Functional Requirements

• Performance: <5% overhead no loading da página de appointments
• Security: Sanitização completa de inputs + nonces + capability checks
• Scalability: Suporte para >1000 médicos e >500 serviços
• Compatibility: WordPress 5.0+, PHP 7.4+, KiviCare 3.0.0+

🏗️ Technical Design

Architecture Overview

CSS-First Approach: Injeção de CSS para ocultar elementos imediatamente, seguida de hooks PHP para filtragem de dados como camada secundária.

Data Model

-- wp_care_booking_restrictions
CREATE TABLE wp_care_booking_restrictions (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    doctor_id BIGINT UNSIGNED NOT NULL,
    service_id BIGINT UNSIGNED NULL, -- NULL = restriction applies to all services
    restriction_type ENUM('hide_doctor', 'hide_service', 'hide_combination') NOT NULL,
    is_active TINYINT(1) DEFAULT 1,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    created_by BIGINT UNSIGNED,
    
    INDEX idx_doctor_service (doctor_id, service_id),
    INDEX idx_active_restrictions (is_active, restriction_type),
    FOREIGN KEY (doctor_id) REFERENCES wp_kc_doctors(id) ON DELETE CASCADE
);

API Design

WordPress AJAX Endpoints:

• wp_ajax_care_toggle_doctor_restriction - Toggle doctor visibility
• wp_ajax_care_toggle_service_restriction - Toggle service restriction
• wp_ajax_care_bulk_update_restrictions - Bulk operations
• wp_ajax_care_export_restrictions - Export configurations

WordPress Hooks:

• care_booking_before_doctor_list - Filter doctors before display
• care_booking_before_service_list - Filter services before display

Integration Points

• KiviCare Plugin: Hooks into appointment booking forms
• WordPress Admin: Custom admin interface
• WordPress Database: Custom table + WordPress options
• WordPress Transients: Caching layer

📊 Implementation Plan

Phase 1: Foundation (Week 1)

• Plugin structure setup (PSR-4 autoloading)
• Database table creation and migrations
• Basic WordPress admin interface
• Core restriction model classes
• PHPUnit testing framework setup

Phase 2: Core Features (Week 2)

• CSS injection system for immediate hiding
• WordPress hooks for KiviCare integration
• AJAX endpoints for admin interface
• Caching layer with WordPress Transients
• Basic restriction CRUD operations

Phase 3: Enhancement (Week 3-4)

• Bulk operations interface
• Export/import functionality
• Audit logging system
• Performance optimization
• Comprehensive testing suite
• Documentation and user guides

🧪 Testing Strategy

Unit Tests

• Restriction model validation
• Cache invalidation logic
• Database query optimization
• Input sanitization functions

Integration Tests

• WordPress hook integration
• KiviCare compatibility
• Admin interface functionality
• AJAX endpoint responses

User Acceptance Tests

• Admin can hide/show doctors via toggle
• Booking form reflects restrictions immediately
• Bulk operations work correctly
• Export/import preserves all settings

Performance Tests

• Page load time impact <5%
• AJAX response time <200ms
• Cache hit/miss ratios >90%
• Database query efficiency

📈 Metrics & Monitoring

Key Metrics

• Appointment booking success rate
• Admin interface usage patterns
• Cache performance (hit/miss ratios)
• Database query execution times

Monitoring

• WordPress debug.log for errors
• Custom error logging for plugin issues
• Performance monitoring via Query Monitor
• User activity logs for audit trail

🚨 Risk Assessment

Technical Risks

• KiviCare Updates: Mitigação via hooks/filters (não modificar core)
• Performance Impact: CSS-first approach + caching agressivo
• Database Growth: Índices apropriados + cleanup automático
• Plugin Conflicts: Namespace isolation + defensive programming

Business Risks

• User Adoption: Interface intuitiva + documentação clara
• Data Loss: Backup automático + export/import robusto

📚 Documentation Requirements

User Documentation

• Admin interface guide
• Setup and configuration manual
• Troubleshooting guide
• Best practices document

Technical Documentation

• Plugin architecture overview
• Database schema documentation
• Hook/filter reference
• Developer API documentation

🔄 Dependencies

External Dependencies

• WordPress 5.0+ (hooks, AJAX, admin interface)
• KiviCare 3.0.0+ (appointment booking system)
• MySQL 5.7+ (JSON support, performance features)
• PHP 7.4+ (type declarations, performance)

Internal Dependencies

• WordPress $wpdb for database operations
• WordPress Transients for caching
• WordPress Admin interface components
• WordPress security functions (nonces, sanitization)

📅 Timeline

Phase	Start Date	End Date	Deliverables
Phase 1	Week 1	Week 1	Foundation setup, database, basic admin
Phase 2	Week 2	Week 2	Core features, CSS injection, hooks
Phase 3	Week 3	Week 4	Enhancement, optimization, documentation

✅ Acceptance Criteria

Definition of Done

• All functional requirements implemented and tested
• Performance requirements met (<5% overhead, <200ms AJAX)
• Security requirements satisfied (sanitization, nonces, capabilities)
• KiviCare integration working without core modifications
• Comprehensive test suite with >80% coverage
• User and technical documentation complete
• Code review completed and approved
• Compatible with WordPress 5.0+ and KiviCare 3.0.0+

---

Created: 2025-09-12
Last Updated: 2025-09-12
Author: AikTop
Branch: feature/wordpress-plugin-kivicare-appointment-control