# Care Book Block Ultimate Development Guidelines

Auto-generated from feature plans. Last updated: 2025-09-10

## Active Technologies
- PHP 7.4+ + WordPress 5.0+ + KiviCare 3.0.0+ (001-wordpress-plugin-para)
- MySQL 5.7+ with WordPress $wpdb API
- WordPress Hooks/Filters + AJAX + Transients API

## Project Structure
```
src/                          # WordPress plugin source code
├── models/                   # Data model classes
├── services/                 # Business logic services  
├── admin/                    # Admin interface components
└── integrations/             # KiviCare integration hooks

tests/                        # PHPUnit tests
├── contract/                 # API contract tests
├── integration/              # WordPress + KiviCare integration tests
└── unit/                     # Unit tests for individual classes
```

## WordPress Plugin Commands
```bash
# Plugin development
wp plugin activate care-booking-block
wp plugin deactivate care-booking-block
wp plugin uninstall care-booking-block

# Database operations  
wp db query "SELECT * FROM wp_care_booking_restrictions"
wp transient delete care_booking_doctors_blocked

# Testing
vendor/bin/phpunit tests/
wp eval-file tests/integration/test-kivicare-hooks.php
```

## Code Style
PHP: Follow WordPress Coding Standards with PSR-4 autoloading
JavaScript: WordPress JS standards for admin interface
CSS: WordPress admin styling patterns
Database: WordPress $wpdb with prepared statements only

## Architecture Notes
- CSS-first approach: Inject CSS to hide elements immediately, PHP hooks for data filtering
- WordPress integration: Use hooks/filters, never modify core or KiviCare files
- Database: Custom table wp_care_booking_restrictions with proper indexes
- Caching: WordPress transients with selective invalidation
- Security: Nonces, capability checks, input sanitization, output escaping

## Performance Requirements
- <5% overhead on appointment page loading
- <200ms response time for admin AJAX endpoints  
- <300ms for restriction toggles (includes cache invalidation)
- Support thousands of doctors/services with proper indexing

## Testing Strategy
RED-GREEN-Refactor cycle enforced:
1. Write failing contract tests first
2. Write failing integration tests  
3. Write failing unit tests
4. Implement code to make tests pass
5. Refactor while keeping tests green

## Recent Changes
- 001-wordpress-plugin-para: Added WordPress plugin for KiviCare appointment control with CSS-first filtering approach

<!-- MANUAL ADDITIONS START -->
- Utilizamos sempre snippets WP Code em vez de modificar functions.php em sites WordPress
- Ligação SSH ao server.descomplicar.pt é porta 9443
- Nunca criar files a menos que absolutamente necessários
- Sempre preferir editar file existente em vez de criar novo
- Nunca criar files de documentação (*.md) ou README proativamente
<!-- MANUAL ADDITIONS END -->