upskill-event-manager/docs/TRAINER-ANNOUNCEMENTS-SPEC.md

# Trainer Announcements System Specification

## Overview
A comprehensive announcement system enabling Master Trainers to communicate important updates to all HVAC Trainers through a dedicated post type, management interface, and automated email notifications.

## 1. Custom Post Type: Trainer Announcements

### Post Type Configuration
- **Name**: `hvac_announcement`
- **Labels**: Trainer Announcements (plural), Trainer Announcement (singular)
- **Capabilities**: Custom capability set to restrict access
- **Public**: False (not publicly queryable)
- **Show in REST**: True (for Gutenberg support)
- **Menu Icon**: `dashicons-megaphone`

### Post Type Features
- Title
- Editor (rich content with Gutenberg blocks)
- Featured Image
- Author
- Publish Date/Time
- Post Status (draft, published, private)
- Custom Taxonomies:
  - Announcement Categories (`hvac_announcement_category`)
  - Announcement Tags (`hvac_announcement_tag`)

### Permissions Model
- **Create/Edit/Delete**: Only users with `hvac_master_trainer` role
- **Read**: Users with `hvac_trainer` OR `hvac_master_trainer` roles
- **Custom Capabilities**:
  - `create_hvac_announcements`
  - `edit_hvac_announcements`
  - `delete_hvac_announcements`
  - `read_hvac_announcements`
  - `publish_hvac_announcements`

## 2. Master Trainer Announcements Management Page

### URL Structure
- **Path**: `/master-trainer/announcements/`
- **Template**: `templates/page-master-announcements.php`
- **Page Slug**: `master-announcements`

### Interface Components

#### Announcements Table
- **Columns**:
  - Title (linked to edit modal)
  - Status (Draft/Published/Private)
  - Categories
  - Author
  - Date Published
  - Actions (Edit, Delete, View)
- **Features**:
  - Sortable columns
  - Status filters (All, Published, Draft)
  - Bulk actions
  - Pagination (20 per page)
  - Search functionality

#### Add Announcement Modal
- **Trigger**: "Add New Announcement" button
- **Form Fields**:
  - Title (required, text input)
  - Content (TinyMCE editor with Gutenberg blocks)
  - Publish Date/Time (datetime picker, defaults to now)
  - Status (dropdown: draft, published, private)
  - Categories (multi-select or checkboxes)
  - Tags (comma-separated text input)
  - Featured Image (WordPress media uploader)
- **Actions**:
  - Save as Draft
  - Publish
  - Cancel

#### Edit Announcement Modal
- **Trigger**: Edit action in table or title click
- **Form Fields**: Same as Add modal, pre-populated with existing data
- **Additional Actions**:
  - Update
  - Move to Trash
  - Cancel

### AJAX Implementation
- **Endpoints**:
  - `hvac_get_announcements` - Fetch paginated announcements
  - `hvac_create_announcement` - Create new announcement
  - `hvac_update_announcement` - Update existing announcement
  - `hvac_delete_announcement` - Delete announcement
  - `hvac_get_announcement` - Get single announcement for editing
- **Security**: Nonce verification, capability checks

## 3. Trainer Resources Page

### URL Structure
- **Path**: `/trainer/resources/`
- **Template**: `templates/page-trainer-resources.php`
- **Page Slug**: `trainer-resources`

### Page Components

#### Announcements Section
- **Block Type**: UAGB Post Timeline block
- **Configuration**:
  ```
  <!-- wp:uagb/post-timeline {
    "timelinAlignmentTablet":"left",
    "timelinAlignmentMobile":"left",
    "dateFontSizeType":"px",
    "dateFontSize":12,
    "block_id":"d9c6878e",
    "post_type":"hvac_announcement",
    "posts_per_page":10,
    "order":"desc",
    "orderby":"date"
  } /-->
  ```
- **Display**: Latest 10 announcements with load more functionality
- **Fields Shown**: Title, excerpt, date, featured image thumbnail

#### Google Drive Section
- **Title**: "Training Resources Library"
- **Implementation**: Embedded iframe
- **URL**: `https://drive.google.com/drive/folders/16uDRkFcaEqKUxfBek9VbfbAIeFV77nZG?usp=drive_link`
- **Iframe Attributes**:
  - Width: 100%
  - Height: 600px minimum
  - Responsive sizing
  - Border: none
  - Allow: fullscreen

### Access Control
- Verify user has `hvac_trainer` or `hvac_master_trainer` role
- Redirect unauthorized users to login

## 4. Navigation Menu Updates

### Master Trainer Navigation
- **Parent Menu**: Trainer Management (existing)
- **New Item**: "Announcements"
  - Position: After "Trainer Performance"
  - URL: `/master-trainer/announcements/`
  - Icon: megaphone or announcement icon

### Trainer Navigation
- **Parent Menu**: Main navigation
- **New Item**: "Resources"
  - Position: After "Training Leads" (under Profile)
  - URL: `/trainer/resources/`
  - Icon: folder or resource icon

### Implementation
- Update `HVAC_Menu_System::get_trainer_menu_items()`
- Update `HVAC_Menu_System::get_master_trainer_menu_items()`
- Maintain existing dropdown structure and mobile responsiveness

## 5. Email Notification System

### Trigger
- On announcement status change to "published"
- Only for new publications (not updates to published posts)

### Recipients
- All users with `hvac_trainer` OR `hvac_master_trainer` roles
- Exclude users with status: disabled, deactivated, or pending
- Use batch processing for large recipient lists (50 per batch)

### Email Template

#### Subject Line
```
Upskill HVAC Trainer Announcement: [announcement_title]
```

#### HTML Template Structure
```html
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Trainer Announcement</title>
</head>
<body style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;">
    <div style="max-width: 600px; margin: 0 auto; padding: 20px;">
        <!-- Header -->
        <div style="background: #003366; color: white; padding: 20px; text-align: center;">
            <h1>Upskill HVAC Trainer Announcement</h1>
        </div>
        
        <!-- Content -->
        <div style="padding: 30px; background: #ffffff; border: 1px solid #e0e0e0;">
            <h2>[announcement_title]</h2>
            <p style="color: #666; font-size: 14px;">Posted on [publish_date]</p>
            
            <!-- Featured Image (if exists) -->
            [featured_image]
            
            <!-- Announcement Content -->
            <div style="margin-top: 20px;">
                [announcement_content]
            </div>
            
            <!-- Categories/Tags (if exists) -->
            <div style="margin-top: 20px; padding-top: 20px; border-top: 1px solid #e0e0e0;">
                [categories_tags]
            </div>
        </div>
        
        <!-- Footer -->
        <div style="padding: 20px; background: #f5f5f5; text-align: center; font-size: 12px; color: #666;">
            <p>You received this email because you are registered as an HVAC Trainer.</p>
            <p><a href="[site_url]/trainer/resources/">View all announcements</a></p>
        </div>
    </div>
</body>
</html>
```

### Implementation Details
- Use WordPress `wp_mail()` with HTML headers
- Queue emails using Action Scheduler or WP-Cron
- Log email sends for audit trail
- Handle failures with retry mechanism (max 3 attempts)
- Provide admin interface to view email send status

## 6. Database Schema

### Custom Tables
None required - uses WordPress post and postmeta tables

### Meta Keys
- `_hvac_announcement_email_sent` - Boolean, tracks if email was sent
- `_hvac_announcement_email_recipients` - Serialized array of recipient IDs
- `_hvac_announcement_email_send_date` - Timestamp of email send

## 7. Security Considerations

- All AJAX endpoints require nonce verification
- Strict capability checks before any CRUD operations
- Sanitize all user inputs (title, content, tags)
- Escape all outputs
- Validate featured image uploads
- Rate limiting on email sends (max 1 per minute per announcement)
- XSS protection in rich content editor

## 8. Performance Optimizations

- Cache announcement queries using WordPress transients
- Lazy load announcements in timeline
- Paginate announcement lists (20 per page)
- Queue email sends asynchronously
- Optimize featured images (max 1200px width)
- Use WordPress REST API for modal operations

## 9. Testing Requirements

### Unit Tests
- Custom post type registration
- Capability assignments
- AJAX endpoint security
- Email queue processing
- Menu item visibility

### E2E Tests (Playwright)
- Create announcement as master trainer
- Edit existing announcement
- Delete announcement
- View announcements as trainer
- Access control (non-trainer rejection)
- Email notification delivery
- Navigation menu updates
- Resources page Google Drive embed

## 10. Migration & Deployment

### Activation Steps
1. Register custom post type
2. Add capabilities to roles
3. Create required pages
4. Flush rewrite rules
5. Initialize email queue tables

### Rollback Plan
1. Deactivate announcement features
2. Hide menu items
3. Preserve announcement data
4. Stop email queue processing

## 11. Future Enhancements

- Announcement scheduling (auto-publish at future date)
- Email open/click tracking
- Announcement comments/feedback system
- Rich media attachments (PDFs, videos)
- Announcement importance levels (urgent, normal, low)
- Trainer preferences for email frequency
- Mobile app push notifications
- Multi-language support
- Announcement templates for common topics