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
```sql
-- 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