chore: add spec-kit and standardize signatures
- 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>
This commit is contained in:
Emanuel Almeida
144
specs/001-wordpress-plugin-para/research.md
Normal file
144
specs/001-wordpress-plugin-para/research.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user