38bb926742
- Added GitHub spec-kit for development workflow - Standardized file signatures to Descomplicar® format - Updated development configuration 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
144 lines
6.7 KiB
Markdown
144 lines
6.7 KiB
Markdown
# Research: WordPress Plugin para Controlo Seguro de Agendamentos KiviCare
|
|
|
|
**Feature**: WordPress Plugin para Controlo Seguro de Agendamentos KiviCare
|
|
**Date**: 2025-09-10
|
|
**Research Phase**: Technical decisions and best practices
|
|
|
|
## Key Technical Decisions
|
|
|
|
### 1. CSS-First Approach vs PHP Filtering
|
|
**Decision**: Hybrid approach - CSS-first for immediate hiding, PHP hooks for data filtering
|
|
**Rationale**: Previous versions failed due to shortcode conflicts. CSS provides immediate visual hiding while PHP hooks ensure clean data without conflicts
|
|
**Alternatives considered**:
|
|
- Pure CSS approach (insufficient - doesn't prevent form submissions)
|
|
- Pure PHP hooks (caused instability in previous versions)
|
|
- Theme modification (not portable across themes)
|
|
|
|
### 2. Database Storage Strategy
|
|
**Decision**: Custom WordPress table `wp_care_booking_restrictions`
|
|
**Rationale**: Clean separation from KiviCare data, survives plugin updates, optimized indexes
|
|
**Alternatives considered**:
|
|
- WordPress options table (not scalable for large datasets)
|
|
- KiviCare database modification (breaks on updates)
|
|
- External database (adds complexity)
|
|
|
|
### 3. WordPress Integration Pattern
|
|
**Decision**: Standard WordPress plugin with hooks and filters
|
|
**Rationale**: Follows WordPress best practices, compatible with plugin ecosystem
|
|
**Alternatives considered**:
|
|
- Must-use plugin (too intrusive)
|
|
- Theme functions (not portable)
|
|
- Custom solution outside WordPress (breaks ecosystem)
|
|
|
|
### 4. KiviCare Integration Strategy
|
|
**Decision**: Hook into KiviCare's WordPress filters and actions, not direct database access
|
|
**Rationale**: Maintains compatibility with KiviCare updates, respects plugin boundaries
|
|
**Alternatives considered**:
|
|
- Direct database queries (brittle to schema changes)
|
|
- KiviCare code modification (impossible to maintain)
|
|
- API interception (complex and fragile)
|
|
|
|
### 5. Admin Interface Framework
|
|
**Decision**: Native WordPress admin with AJAX for real-time updates
|
|
**Rationale**: Consistent with WordPress UX, no additional dependencies, familiar to users
|
|
**Alternatives considered**:
|
|
- React admin interface (overkill for this functionality)
|
|
- Custom framework (reinventing wheel)
|
|
- Third-party admin framework (additional dependency)
|
|
|
|
### 6. Performance Optimization Strategy
|
|
**Decision**: WordPress transients for caching with selective invalidation
|
|
**Rationale**: Built-in WordPress caching, automatic expiration, integrates with object cache
|
|
**Alternatives considered**:
|
|
- File-based caching (not portable across hosting)
|
|
- Redis/Memcached direct (not always available)
|
|
- No caching (performance impact)
|
|
|
|
### 7. Error Handling and Recovery
|
|
**Decision**: Graceful degradation with detailed WordPress debug logging
|
|
**Rationale**: System continues working if KiviCare is unavailable, detailed logs for troubleshooting
|
|
**Alternatives considered**:
|
|
- Hard failures (breaks website)
|
|
- Silent failures (difficult to debug)
|
|
- External error tracking (additional dependency)
|
|
|
|
## WordPress-Specific Best Practices Research
|
|
|
|
### Plugin Architecture
|
|
- **Activation/Deactivation hooks**: For database table creation/cleanup
|
|
- **Uninstall hook**: For complete data removal when plugin is deleted
|
|
- **WordPress coding standards**: PSR-4 autoloading, proper sanitization
|
|
- **Security**: Nonces for forms, capability checks, prepared statements
|
|
|
|
### Database Schema Design
|
|
- **Indexes**: Primary key on id, composite index on (restriction_type, target_id)
|
|
- **WordPress prefixes**: Use $wpdb->prefix for table names
|
|
- **Data types**: WordPress-compatible field types and constraints
|
|
- **Migration strategy**: Version checks and schema updates
|
|
|
|
### Frontend Integration
|
|
- **wp_enqueue_script/style**: Proper asset loading with dependencies
|
|
- **wp_localize_script**: For passing PHP data to JavaScript
|
|
- **WordPress AJAX**: wp_ajax_* actions for admin interface
|
|
- **Conditional loading**: Only load admin assets in admin, frontend assets on frontend
|
|
|
|
### Caching Strategy
|
|
- **WordPress Transients API**: set_transient/get_transient for temporary data
|
|
- **Object Cache**: Integration with wp_cache_* functions
|
|
- **Cache invalidation**: Clear related caches when restrictions change
|
|
- **Plugin compatibility**: Works with popular caching plugins
|
|
|
|
## Performance Considerations
|
|
|
|
### Database Optimization
|
|
- **Query optimization**: Use WordPress $wpdb with prepared statements
|
|
- **Index strategy**: Optimize for common query patterns
|
|
- **Batch operations**: For bulk restriction updates
|
|
- **Connection pooling**: Rely on WordPress database connection management
|
|
|
|
### Frontend Performance
|
|
- **Asset minification**: Minified CSS/JS for production
|
|
- **Conditional loading**: Load assets only when needed
|
|
- **Cache-friendly**: Generate cache-friendly CSS selectors
|
|
- **No render blocking**: Non-critical CSS loaded asynchronously
|
|
|
|
## Security Analysis
|
|
|
|
### WordPress Security Best Practices
|
|
- **Data sanitization**: sanitize_text_field, intval for all inputs
|
|
- **Data validation**: Validate all form inputs before database operations
|
|
- **Capability checks**: current_user_can for all admin actions
|
|
- **Nonces**: wp_nonce_field for all forms, wp_verify_nonce for validation
|
|
- **SQL injection prevention**: Always use $wpdb->prepare
|
|
|
|
### KiviCare Integration Security
|
|
- **Hook priorities**: Use appropriate priorities to avoid conflicts
|
|
- **Data filtering**: Filter data, don't modify KiviCare's database
|
|
- **Capability respect**: Respect KiviCare's user capabilities
|
|
- **Plugin detection**: Check if KiviCare is active before integration
|
|
|
|
## Compatibility Analysis
|
|
|
|
### WordPress Version Compatibility
|
|
- **Minimum version**: WordPress 5.0+ for block editor and modern APIs
|
|
- **PHP version**: PHP 7.4+ for modern syntax and performance
|
|
- **MySQL version**: MySQL 5.7+ for modern database features
|
|
|
|
### KiviCare Plugin Compatibility
|
|
- **Version support**: KiviCare 3.0.0+ for stable hook system
|
|
- **Hook compatibility**: Use documented hooks where available
|
|
- **Graceful degradation**: Handle missing hooks gracefully
|
|
- **Update resilience**: Avoid depending on internal KiviCare functions
|
|
|
|
### Theme and Plugin Compatibility
|
|
- **Popular caching plugins**: WP Rocket, W3 Total Cache, WP Super Cache
|
|
- **Popular themes**: Compatibility with major WordPress themes
|
|
- **Page builders**: Elementor, Gutenberg, classic editor
|
|
- **Other healthcare plugins**: Avoid conflicts with similar functionality
|
|
|
|
## Research Conclusions
|
|
|
|
All technical unknowns have been resolved with specific implementation strategies that address the critical stability requirements learned from previous versions. The hybrid CSS-first + PHP hooks approach provides both immediate visual feedback and robust data filtering while maintaining system stability.
|
|
|
|
**Status**: ✅ All NEEDS CLARIFICATION items resolved
|
|
**Next Phase**: Phase 1 - Design & Contracts |