ben/upskill-event-manager
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2
upskill-event-manager/docs/TRAINER-ANNOUNCEMENTS-IMPLEMENTATION-PLAN.md
Ben c20b461e7d feat: Implement secure Trainer Announcements system with comprehensive features 
This commit introduces a complete announcement management system for HVAC trainers
with enterprise-grade security, performance optimization, and email notifications.

## Core Features
- Custom post type for trainer announcements with categories and tags
- Role-based permissions (master trainers can create/edit, all trainers can read)
- AJAX-powered admin interface with real-time updates
- Modal popup viewing for announcements on frontend
- Automated email notifications when announcements are published
- Google Drive integration for training resources

## Security Enhancements
- Fixed critical capability mapping bug preventing proper permission checks
- Added content disclosure protection for draft/private announcements
- Fixed XSS vulnerabilities with proper output escaping and sanitization
- Implemented permission checks on all AJAX endpoints
- Added rate limiting to prevent abuse (30 requests/minute)
- Email validation before sending notifications

## Performance Optimizations
- Implemented intelligent caching for user queries (5-minute TTL)
- Added cache versioning for announcement lists (2-minute TTL)
- Automatic cache invalidation on content changes
- Batch email processing to prevent timeouts (50 emails per batch)
- Retry mechanism for failed email sends (max 3 attempts)

## Technical Implementation
- Singleton pattern for all manager classes
- WordPress coding standards compliance
- Proper nonce verification on all AJAX requests
- Comprehensive error handling and logging
- Mobile-responsive UI with smooth animations
- WCAG accessibility compliance

## Components Added
- 6 PHP classes for modular architecture
- 2 page templates (master announcements, trainer resources)
- Admin and frontend JavaScript with jQuery integration
- Comprehensive CSS for both admin and frontend
- Email notification system with HTML templates
- Complete documentation and implementation plans

This system provides a secure, scalable foundation for trainer communications
while following WordPress best practices and maintaining high code quality.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-08-20 13:34:15 -03:00

248 lines
No EOL
7.6 KiB
Markdown
Raw Blame History

# Trainer Announcements Implementation Plan
## Architecture Decision
Based on unanimous consensus from architectural analysis, the system will use **modular architecture with specialized classes** following the Single Responsibility Principle (SRP).
## Class Structure
### Core Classes
1. **HVAC_Announcements_CPT** (`includes/class-hvac-announcements-cpt.php`)
- Register custom post type `hvac_announcement`
- Register taxonomies (categories, tags)
- Define post type supports and capabilities
2. **HVAC_Announcements_Manager** (`includes/class-hvac-announcements-manager.php`)
- Core orchestration and business logic
- Singleton pattern implementation
- Hook registration and initialization
3. **HVAC_Announcements_Ajax** (`includes/class-hvac-announcements-ajax.php`)
- AJAX handlers for CRUD operations
- Modal data processing
- Nonce verification and security
4. **HVAC_Announcements_Email** (`includes/class-hvac-announcements-email.php`)
- Email notification system
- HTML template generation
- Batch processing for large recipient lists
5. **HVAC_Announcements_Display** (`includes/class-hvac-announcements-display.php`)
- Frontend display formatting
- Shortcode handlers
- Template rendering
6. **HVAC_Announcements_Permissions** (`includes/class-hvac-announcements-permissions.php`)
- Role-based access control
- Capability management
- User permission checks
## Implementation Phases
### Phase 1: Core Infrastructure (Day 1)
- [ ] Create `HVAC_Announcements_CPT` class
- Register `hvac_announcement` post type
- Set up taxonomies
- Configure capabilities
- [ ] Create `HVAC_Announcements_Permissions` class
- Add capabilities to roles on activation
- Implement permission check methods
- [ ] Create `HVAC_Announcements_Manager` class
- Singleton implementation
- Initialize all components
- Register hooks
### Phase 2: Master Trainer Interface (Day 1-2)
- [ ] Create master announcements page template
- Path: `templates/page-master-announcements.php`
- Include navigation and breadcrumbs
- Add announcements table structure
- [ ] Implement `HVAC_Announcements_Ajax` class
- `hvac_get_announcements` endpoint
- `hvac_create_announcement` endpoint
- `hvac_update_announcement` endpoint
- `hvac_delete_announcement` endpoint
- [ ] Build modal popup system
- Add/Edit announcement forms
- TinyMCE integration
- Media uploader for featured image
- [ ] Create JavaScript for modal interactions
- File: `assets/js/hvac-announcements-admin.js`
- [ ] Style the interface
- File: `assets/css/hvac-announcements-admin.css`
### Phase 3: Trainer Resources Page (Day 2)
- [ ] Create trainer resources page template
- Path: `templates/page-trainer-resources.php`
- Include navigation and breadcrumbs
- [ ] Add Gutenberg blocks content
- UAGB Post Timeline for announcements
- Google Drive iframe embed
- [ ] Implement `HVAC_Announcements_Display` class
- Format announcement output
- Handle timeline display
- [ ] Ensure proper access control
- Verify trainer/master trainer roles
### Phase 4: Navigation & Integration (Day 2)
- [ ] Update `HVAC_Menu_System` class
- Add "Announcements" to master trainer menu
- Add "Resources" to trainer menu
- [ ] Update breadcrumb configuration
- Add new pages to breadcrumb trail
- [ ] Ensure Astra theme integration
- Force full-width layout
- Remove sidebar
### Phase 5: Email System (Day 3)
- [ ] Implement `HVAC_Announcements_Email` class
- Hook into post status transitions
- Build recipient list (active trainers only)
- Generate HTML email from template
- [ ] Create email template
- Path: `templates/email/announcement-notification.php`
- Include announcement content
- Add branding and footer
- [ ] Implement batch processing
- Use WP-Cron for asynchronous sending
- Add retry mechanism for failures
- [ ] Add email logging
- Track sent emails in post meta
- Log failures for debugging
### Phase 6: Testing & Quality Assurance (Day 3-4)
- [ ] Write unit tests
- Test post type registration
- Test capability assignments
- Test AJAX endpoints
- Test email queue
- [ ] Create Playwright E2E tests
- Test announcement creation workflow
- Test edit/delete operations
- Test access control
- Test email notifications
- Test navigation updates
- [ ] Manual testing checklist
- Verify all user roles
- Test on mobile devices
- Check email rendering
- [ ] Code review with Zen
- Security audit
- Performance review
- Best practices check
### Phase 7: Deployment (Day 4)
- [ ] Pre-deployment checks
- Run `bin/pre-deployment-check.sh`
- Verify all tests pass
- [ ] Deploy to staging
- Use `scripts/deploy.sh staging`
- Test on staging environment
- [ ] Create test data
- Sample announcements
- Test email sends
- [ ] Document any issues
- [ ] Prepare for production
## File Structure
```
hvac-community-events/
├── includes/
│ ├── class-hvac-announcements-cpt.php
│ ├── class-hvac-announcements-manager.php
│ ├── class-hvac-announcements-ajax.php
│ ├── class-hvac-announcements-email.php
│ ├── class-hvac-announcements-display.php
│ └── class-hvac-announcements-permissions.php
├── templates/
│ ├── page-master-announcements.php
│ ├── page-trainer-resources.php
│ └── email/
│ └── announcement-notification.php
├── assets/
│ ├── js/
│ │ └── hvac-announcements-admin.js
│ └── css/
│ └── hvac-announcements-admin.css
└── tests/
├── unit/
│ └── test-announcements.php
└── e2e/
└── test-announcements-workflow.js
```
## Success Criteria
1. **Functionality**
- Master trainers can create, edit, delete announcements
- All trainers can view announcements
- Email notifications sent to active trainers
- Google Drive embedded successfully
2. **User Experience**
- Modal popups work smoothly
- Navigation items appear correctly
- Pages load within 2 seconds
- Mobile responsive design
3. **Security**
- Proper capability checks enforced
- All inputs sanitized
- All outputs escaped
- Nonces verified on all forms
4. **Code Quality**
- Follows WordPress coding standards
- Consistent with existing plugin architecture
- Comprehensive test coverage
- Well-documented code
5. **Performance**
- Efficient database queries
- Proper caching implemented
- Assets loaded conditionally
- Email batch processing works
## Risk Mitigation
1. **Email Delivery Issues**
- Implement retry mechanism
- Add logging for debugging
- Consider email service integration
2. **Permission Conflicts**
- Thorough testing of all role combinations
- Clear capability definitions
- Fallback permission checks
3. **Theme Compatibility**
- Test with Astra theme
- Ensure proper template hierarchy
- Add compatibility checks
4. **Performance Concerns**
- Implement pagination
- Use transient caching
- Optimize database queries
## Timeline
- **Day 1**: Core infrastructure and master trainer interface (50%)
- **Day 2**: Complete interface, trainer resources, navigation
- **Day 3**: Email system and testing
- **Day 4**: Final testing, code review, and deployment
## Dependencies
- WordPress 5.0+ (Gutenberg support)
- Ultimate Addons for Gutenberg (UAGB)
- Astra theme
- Existing HVAC plugin infrastructure
## Notes
- All classes follow singleton pattern
- Use existing HVAC plugin patterns for consistency
- Prioritize security and performance
- Maintain backward compatibility
- Document all public methods
Reference in a new issue View git blame Copy permalink