# HVAC Community Events - Project Requirements

This document outlines the original requirements for the HVAC Community Events Management System. It serves as the foundational guide for the project's development and feature set.

## System Purpose

To create a specialized community events platform using WordPress and The Events Calendar (TEC) plugin suite. The system enables independent trainers to manage their own events, sell tickets, and track performance without accessing the WordPress admin panel.

## System Components

### WordPress Core

- WordPress (latest stable version)
- Custom user roles and permissions

### Required Plugins

- The Events Calendar (Free)
- Events Calendar Pro
- Event Tickets
- Event Tickets Plus
- The Events Calendar: Community

### Zoho CRM API Integration (Phase 2)

- The plugin will connect to the Zoho CRM API
- Events will be synced to the Campaigns module

## User Journey for Trainers

1. Trainer registers through the Trainer Registration Page
2. Trainer logs in through the Community Login page
3. Trainer accesses their Dashboard
4. Trainer creates/manages events and views statistics
7. Trainer views order details 
8. Trainer views individual attendee details
9. Trainer communicates with attendees via email
10. Trainer performs a Check In of attendees (using Events Tickets Plus features) 
11. Trainer generates a certificate of completion and sends to the user (phase 3)

## User Journey for Prospective trainees

1. Trainee views Upskill HVAC website home page (already exists)
2. Trainee navigates to Training Events Page (already exists, uses The Events Calendar pregenerated page)
3. Trainee registers for an event (already exists, uses The Events Calendar pregenerated page)
4. Trainee attends event and receives certificate of completion (Phase 3)
5. Trainee logs into their own My Training page (phase 3)
6. Trainee wants more training, so trainee navigates to Request Training Page (phase 3)


## Required Pages

### 1. Community Registration Page

**Purpose:** Provide a branded account registration experience for trainers without exposing the WordPress admin login.

**Features:**

- Form Instructions: By submitting this form, you will be creating an account in the Upskill HVAC online event system. Once approved, you will be able to login to the trainer portal to manage your profile and event listings.
- Upon successful registration, the user will be provided the following message: "Thank you for registering. Your account is currently pending approval. You will receive an email once your account is approved."
- If any of the fields aren't populated during registration, the user will be provided an error message.

**Registration Fields:**

The fields from Wordpress' user profile page will be collected and displayed in the registration form:

- First Name (first_name, text input)
- Last Name (last_name, text input)
- Username (user_login, hidden input, automatically populated from the email address)
- Password (user_pass, password input, with the helper text: "Password must be at least 8 characters long, and include at least one uppercase letter, one lowercase letter, and one number.")
- Email (user_email, email input)
- Display Name (display_name, text input, with the helper text: "This will be the name displayed to other users on the site.")
- Personal Website (user_url, url input, optional)
- LinkedIn Profile URL (user_linkedin, url input, optional)
- Personal Accreditation (personal_accreditation, text input, optional) (with the helper text: "Enter your abbreviated accreditations separated by commas.")
- Biographical Info (description, textarea, with the helper text: "A short bio about yourself. This will be displayed on your profile page.")
- Profile Image (profile_image, image upload, with the helper text: "Please attach a .jpg, .png, .gif or .mpg image. By attaching an image to use as your profile picture you assert that you have rights to use the image and it is not illegal, pornographic or violent in any way. This will be displayed on your profile page.")

The following Custom fields will be added to the registration form. If these don't exist in the database, the plugin will create them as custom fields that will be displayed on the user's profile page:

- Business Name (business_name, text input. This field also gets registered as an _OrganizerOrganizer name in The Events Calendar if it doesn't already exist.)
- Business Phone Number (phone, text input.This field also gets added to the _OrganizerPhone record in The Events Calendar if it doesn't already exist.)
- Business Email (business_email, email input. This field also gets added to the _OrganizerEmail record in The Events Calendar if it doesn't already exist.)
- Business Website (business_website, url input. This field also gets added to the website of the Event Organizer record in The Events Calendar if it doesn't already exist.)
- Business Description (business_description, textarea. This field also gets added to the description of the Event Organizer record in in The Events Calendar if it doesn't already exist.)
- Country (Dropdown) (user_country, dropdown. At the top of the dropdown list, place "United States" and "Canada" first, then a line with "---" (not selectable), and the rest of the world countries in alphabetical order.)
- State / Province (user_state, text input, but shown as a drop down which will populate the text value upon submission. The drop down will contain a list of all US states, Canadian Provinces, and the word "Other" for non US-Canadian entities, which is selected as the default if the user selects a country other than United States or Canada in the user_country field. Once the word "Other" is selected in this field, then a text box appears for the user to populate.)
- City (user_city, text input)
- Zip / PostalCode (user_zip, text input)
- Create Training Venue Profile (create_venue, radio buttons) (with the helper text: "Do you want to create a Training Venue Profile for your business to use when listing your training events? If yes, we will use the address provided above." Options: "Yes" or "No", with "No" as the default)
- Business Type (business_type, dropdown, single select) (with the helper text: "What type of business are you?" and the following options, displayed as checkboxes: "Manufacturer", "Distributor", "Contractor", "Consultant", "Educator", "Government", "Other")
- Training Audience (training_audience, checkboxes) (with the helper text: "Who do you offer training to? (Select all that apply)" and the following options, displayed as checkboxes: "Anyone (open to the public)", "Industry professionals", "Internal staff in my company", "Registered students/members of my org/institution")
- Training Formats (training_formats, checkboxes) (with the helper text: "What formats of training do you offer?" and the following options, displayed as checkboxes: "In-person", "Virtual", "Hybrid", "On-demand")
- Training Locations (training_locations, checkboxes) (with the helper text: "Where are you willing to provide training? (Select all that apply)" and the following options, displayed as checkboxes: "Online", "Local" "Regional Travel", "National Travel", "International Travel")
- Training Resources (training_resources, checkboxes) (with the helper text: "What training resources do you have access to? (Select all that apply)" This will be displayed on your profile page." and the following options, displayed as checkboxes: "Classroom", "Training Lab", "Ducted Furnace(s)", "Ducted Air Handler(s)", "Ducted Air Conditioner(s)", "Ducted Heat Pump(s)", "Ductless Heat Pump(s)", "Training Manuals", "Presentation Slides", "LMS Platform / SCORM Files", "Custom Curriculum", "Other")
- Application Details (application_details, textarea) (with the helper text: "Please explain why you want to create a training account on Upskill HVAC.")
- Annual Revenue Target (annual_revenue_target, number input, optional) (with the helper text: "It's our goal to help you generate revenue through your training. How much revenue are you looking to generate annually though your training on Upskill HVAC?")

**Additional Requirements For Registration Page:** 
- Unless specified as optional, all of the fields above are required. 
- The titles of each field should be in bold.
- Please place a "*" beside all of the required fields, and mark (optional) beside the optional fields.
- Provide hint text for fields which may not be clear.
- Perform input validation on the appropriate fields.
- If the user selects a field but does not meet the input validation requirements, display a message under the field which clearly indicates what the user needs to do.
- Make the form prettier by organizing shorter fields or checkboxes into columns

### 2. Community Login Page

**Purpose:** Provide a branded login experience for trainers without exposing the WordPress admin login.

**Features:**
- Username/email and password fields
- "Remember me" option
- Password reset functionality
- Redirect to Dashboard after successful login
- Error messaging for failed logins

### 3. Trainer Profile Page


**Purpose:** Provide an inferface for an approved trainer to update their own profile information.

**Features:**
- Includes the same fields as the registration form, but with the ability to edit them.
- The profile page will be accessible to logged in users only, and will only show the values that are associated with the current user.
- The profile page will be accessible from the Dashboard.
- The profile page will have a "Save Changes" button that will update the user's profile information.
- The profile page will have a "Change Password" button that will allow the user to change their password.


### 4. Trainer Dashboard

**Purpose:** Provide trainers with a comprehensive overview of their events and performance metrics.

Note: This will leverage functionality from from the The Events Calendar Community Events plugin(s).

**Features:**
- **Navigation:**
  - Create Event button
  - View Trainer Profile button
  - Logout button

- **Overall Statistics Summary:**
  - Total number of events created
  - Number of upcoming events
  - Number of past events
  - Total tickets sold (all events)
  - Total revenue generated (all events) with a comparison to the user specified annual_revenue_target

- **Events Table:** (summarizing stats for individual events)
  - Event Status (with an icon indicating the status of the event (Draft, Published, Pending Review)
  - Event name (including an icon indicating a link to the event page, which opens in a new tab)
  - Event date (highlighted bold if event is coming up in the next 7 days or less)
  - Event organizer
  - Total capacity
  - Tickets sold
  - Total revenue
  - Sorting/filtering capabilities

### 5. Event Summary Page

**Purpose:** Provide detailed information about a specific event, including ticket sales and attendee information.

**Features:**
- **Navigation:**
  - Edit Event button
  - Email Attendees button (Phase 2)
  - Return to Dashboard button

- **Event Details Section:**
  - Time & Date
  - Location
  - Organizers
  - Tickets information
  - Event description

- **Transactions Table:**
  - Purchaser Name (with hyperlink to Order Summary)
  - Purchaser Organization
  - Purchase Date/Time
  - Number of Tickets
  - Total Revenue

### 6. Modify Event Page

**Purpose:** Allow trainers to edit their existing events.

**Features:**
- Instructions section
- Event editing form (leveraging functionality from from the The Events Calendar Community Events plugins)
- Return to Dashboard button

### 7. Create Event Page

**Purpose:** Allow trainers to create new events.

**Features:**
- Instructions section
- Event creation form (leveraging functionality from The Events Calendar Community Events plugin)
- Return to Dashboard button

### 8. Email Attendees Page (Phase 2)

**Purpose:** Enable trainers to communicate with event attendees.

**Features:**
- **Navigation:**
  - View Event Summary button
  - Return to Dashboard button

- **Filtering Options:**
  - Event selector
  - Ticket type filter
  - Attendee filter

- **Email Composition:**
  - CC field
  - Subject line
  - Rich-text editor for email body
  - Send Email button


### 9. Order Summary Page (Phase 3)

**Purpose:** Display detailed information about a specific ticket purchase.

**Features:**
- **Navigation:**
  - View Event Summary button
  - Return to Dashboard button

- **Order Information:**
  - Order Number
  - Purchaser Name and Email
  - Date of Purchase
  - Number of Tickets
  - Total Price

- **Attendee Information:**
  - Details for each ticket purchased
  - Attendee names
  - Ticket types
  - Custom fields collected during event registration


### 10. Certificates Report Page (Phase 3)

**Purpose:** Allows the trainer to generate PDF certificates of completion.

**Features:**
- **Navigation:**
  - Create Certificate button
  - Return To Dashboard Button
  - Logout button

- **Overall Statistics Summary:**
  - Total number of trainees
  - Total number of training classes completed
  - Total number of certificates generated
  - Average certificates per attendee

- **Certificates Table:** (summarizing stats for individual events)
  - Event name (including an icon indicating a link to the event page, which opens in a new tab)
  - Event date (highlighted bold if event is coming up in the next 7 days or less)
  - Number of Attendees
  - Number of generated certificates
  - Button to generate certificates
  - Sorting/filtering capabilities

**Additional Considerations:**
- Certificate features will eventually be addd to other pages
- We will need a way to revoke certificates in the future

### 11. Generate Certificates Page

**Purpose:** Create and preview certificates for completed events

**Features:**
- **Navigation:**
  - breadcrumbs
  - Dashboard button
  - Certificates Report buton
  - Logout button

- **Certificate Generator:**
  A series of dropdowns will help the user in selecting events, as follows:
  1. Ask the user to select an event provides a search field and a filtered list of events, sorted by the most recently completed event
  2. Once a single event is selected, then a table of attendees will come up with checkbox fields, allowing the user to select which users should receive a certificate. These checkboxes will be pre-populated based on whether they've been checked-in using The Events Calendar Tickets Plus extension
  3. Once users are confirmed, then the page will show a preview of the PDF and a collection of fields to edit. These are the following fields which will be available - most will be pre-populated from existing data in the DB:
     1. Event name
     2. Event Date
     3. Training Organization
     4. Attendee Name (First & Last)
     5. Venue Name
     6. Instructor Name
     7. Instructor Signature
  4. Once the fields are confirmed, then the software will generate all of the PDFs, show the links to the PDFs in a list with selectable checkboxes (all pre-checked), then provide an option for the user to either download all certificates, print all certificates, or email all certificates.
  5. If the users selects email, then a new form pops up with an email template with the following fields:
     1. From: [instructor name]
     2. To: [a comma separated list of the attendees]
     3. CC: [empty]
     4. Subject: [A prepopulated subject congradulating the user]
     5. Description: [A prepopulated message thanking the user for attending, awarding them with the new certificate, and advising them of next steps]
     6. Send
  6. A thank you message is provided.

**Additional Considerations:**
- The first iteration of this will use a pre-made PDF template with fillable fields
- Eventually, this will be capable of handing URIs to prepopulate fields when navigating to this page from other pages
- This will utilize the same built-in email capabilities as the rest of the Events Calendar plugins and extensions.


### 12. Request Training Page

**Purpose:** Allow a prospective Trainee to request training

**Features:**
- TBD


### 13. My Training Page

**Purpose:** Allow a Trainee to track their progress.

**Features:**
- TBD


## Development Phases

### Phase 1: Core Functionality (Completed)

- Community Login Page
- Registration Page
- Basic Dashboard with event listing
- Create Event Page
- Modify Event Page
- Event Summary Page

### Phase 2: Integrate Zoho CRM API

- Connect Upskill HVAC to the measureQuick Zoho CRM API
- Create records for each training event in the "Campaigns" table
- Update each Campaign record with ticket sales, attendance & certificate activities

### Phase 3: Enhanced Event Management (Planned)

- Order Summary Page with basic details
- Email Attendees functionality
- Certificate generation
- Reqeust Training Page for prospective trainees
- My Training Page for attendees
- Expanded Dashboard statistics
- Comprehensive transaction reporting
- Advanced filtering and reporting options

## Technical Considerations

- Whenever possible, this project will take advantage of existing functions in wordpress and in the various plugins provided by The Events Calendar. 

### Performance Optimization

- Pagination for data tables
- Optimized database queries

### Security Measures

- Input validation and sanitization
- User capability checking
- Protection against common vulnerabilities

### User Interface Guidelines

- Consistent header with navigation buttons
- Breadcrumb-style navigation on each page
- Clear path back to Dashboard from all pages
- Mobile-friendly, responsive design
- Accessible color choices and contrast
- Haromonized styling which takes advantage of the active wordpress theme
- Generated wordpress pages should be compatible with the gutenberg editor
- Hide the page title to avoid redundent headings

### Testing Framework

The project has successfully migrated from Puppeteer to Playwright for automated testing. The testing framework now includes:

#### Playwright Testing Framework

The testing framework uses Playwright to automate browser interaction and validate form functionality. The migration from Puppeteer to Playwright has been completed with the following improvements:

1. **Better Navigation Handling**: Playwright's auto-waiting mechanism prevents the "Requesting main frame too early!" errors that plagued Puppeteer tests.
2. **Cross-Browser Testing**: Support for Chromium, Firefox, and WebKit browsers.
3. **Mobile Device Emulation**: Testing responsive design on mobile devices.
4. **Enhanced Debugging**: Tracing and video recording for better debugging.
5. **Page Object Model**: Improved code organization and maintainability.
6. **Authentication State Management**: More reliable session handling.

#### Test Events System

A structured system for creating and managing test events:
- Configuration file with predefined event definitions
- Creation script for generating test events
- Cleanup script for removing test events
- Integration with the testing framework

#### Markdown Test Reporting

A custom markdown reporter for Playwright tests that generates LLM-friendly test reports:
- Summary statistics (total tests, passed, failed, skipped)
- Categorized results by test status
- Error details for failed tests
- Attachment references for screenshots, videos, and traces

#### HTML Dumps Parsing System

A system for reducing the size of HTML dumps generated by tests:
- Removes unnecessary elements like scripts, styles, and inline event handlers
- Reduces file sizes by 75-89%
- Improves analysis capabilities by focusing on relevant content

#### Verbosity Control System

Options for controlling the amount of output generated during test runs:
- Five verbosity levels (SILENT, MINIMAL, NORMAL, VERBOSE, DEBUG)
- Control over console output, screenshots, HTML dumps, and file logs
- Command line options for different scenarios (CI/CD, debugging, AI assistance)

#### Screenshot Cleanup Utility

A utility for managing disk space by automatically removing older screenshot files:
- Keeps the 20 most recent entries
- Removes older files and directories
- Integrated with the test runner

#### Running Tests

Tests are located in the `/tests` directory and can be run using the `run-tests.sh` script with various command line options:

```bash
# Run all Playwright tests
./wordpress-dev/bin/run-tests.sh --e2e (Execute from wordpress-dev/ directory)

# Run specific test files (Execute from wordpress-dev/ directory)
./bin/run-tests.sh --e2e --grep @login
./bin/run-tests.sh --e2e --grep @dashboard
./bin/run-tests.sh --e2e --grep @create-event
./bin/run-tests.sh --e2e --grep @event-summary
./bin/run-tests.sh --e2e --grep @modify-event

# Run tests in specific browsers
./run-tests.sh pw:chrome
./run-tests.sh pw:firefox
./run-tests.sh pw:safari

# Run tests on mobile devices
./run-tests.sh pw:mobile

# Debug and tracing
./run-tests.sh pw:debug
./run-tests.sh pw:trace

# Verbosity options
./run-tests.sh pw --silent
./run-tests.sh pw --minimal
./run-tests.sh pw --verbose
./run-tests.sh pw --debug
```

#### User Personas for Testing

The testing framework includes predefined user personas to ensure consistent testing across different user types:

- Canadian Trainers (canadaTrainer1, canadaTrainer2)
- US Trainers (usTrainer1, usTrainer2, usTrainer3)
- International Trainer (intlTrainer1)
- Special test cases (pendingTrainer, subscriberUser)

Each persona includes detailed information about the user, their business, location, and expected behaviors in different test scenarios.

To run tests with specific personas:

```bash
./tests/run-tests.sh persona canadaTrainer1 dashboard
./tests/run-tests.sh persona usTrainer2 create-event
```

#### Test Environment Management

The testing framework includes tools for setting up and managing the test environment:

```bash
# Set up the test environment (create test users)
./tests/run-tests.sh setup

# Verify the test environment
./tests/run-tests.sh verify

# Tear down the test environment (delete test users)
./tests/run-tests.sh teardown --force
```

### Deployment, Revision Management & Documentation

- Deployment scripts are available in the `deploy/` directory with wrapper scripts in the top level project directory. 
- After completing a feature, you will use the following command to upload to the Upskill HVAC Server: `./deploy.sh --config deploy-config.sh`
- You can also run tests after deployment with: `./deploy.sh --config deploy-config.sh --run-tests`
- Alternatively, you can deploy before running specific tests: `./tests/run-tests.sh --deploy dashboard`
- After deployment, update the requirements doc with any modifications to the requirements, and with the status of each page, and add a "Next Steps" section when appropriate.
- After deployment, testing, and documentation, then a git commit should be made with appropriate comments

### Memory Management System

The project includes a memory management system that leverages the memory MCP server to maintain a knowledge graph of the project. This system can be used to track project status, generate action items, and provide context-aware assistance.

#### Memory Management Components

- **memory_manager.py**: Main script that provides the core functionality for checking, updating, and generating action items
- **file_analyzer.py**: Analyzes project files to gather context about the project structure, components, and status
- **entity_manager.py**: Creates and updates entities and relations in the knowledge graph
- **action_items.py**: Generates a summary of outstanding action items based on the knowledge graph
- **deploy-integration.sh**: Provides functions for integrating memory management with deployment and testing

#### Integration with Deployment and Testing

The memory management system is integrated with both the deployment process and the testing suite:

- **Deployment Integration**: The deployment process has been updated to include a new `--update-memory` option that runs the memory update script after deployment:

  ```bash
  # Deploy the plugin and update the knowledge graph
  ./deploy.sh --config deploy-config.sh --update-memory
  ```

- **Testing Integration**: The testing suite has been updated to include a new `--generate-action-items` option that runs the memory action items script after tests are completed:

  ```bash
  # Run tests and generate action items summary
  cd tests && ./run-tests.sh --generate-action-items
  ```

#### Documentation

Comprehensive documentation for the memory management system is available in:

- **memory/README.md**: Documents the memory management system and its components
- **docs/memory-integration.md**: Explains the integration with the deployment process
- **tests/docs/memory-integration.md**: Explains the integration with the testing suite

For more details on the memory management system, see the documentation in the files mentioned above.

---

*This requirements document serves as the foundation for implementing the HVAC Community Events Management System.*