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

<!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