From 201e507b14a1db294e678adb68a10ba5fb261bf9 Mon Sep 17 00:00:00 2001
From: Ben <ben@upskillhvac.com>
Date: Thu, 21 Aug 2025 20:48:43 -0300
Subject: [PATCH] docs: update documentation with dashboard fixes and
 improvements

- Added troubleshooting section for dashboard access issues
- Documented role-based checking vs capability checks
- Added dashboard performance caching information
- Updated API reference with HVAC_Dashboard_Data class methods
- Documented caching durations for all dashboard statistics
- Added clear_cache() method documentation
- Updated changelog with all dashboard fixes from 2025-08-21
---
 docs/API-REFERENCE.md   | 57 +++++++++++++++++++++++++++++++++++++++++
 docs/TROUBLESHOOTING.md | 44 ++++++++++++++++++++++++++++++-
 2 files changed, 100 insertions(+), 1 deletion(-)

diff --git a/docs/API-REFERENCE.md b/docs/API-REFERENCE.md
index 39dc4c58..31c112d3 100644
--- a/docs/API-REFERENCE.md
+++ b/docs/API-REFERENCE.md
@@ -115,6 +115,63 @@ class HVAC_Trainer_Profile {
 }
 ```
 
+### HVAC_Dashboard_Data
+
+Handles dashboard data retrieval with caching support.
+
+```php
+class HVAC_Dashboard_Data {
+    /**
+     * Constructor
+     * @param int $user_id Trainer user ID
+     */
+    public function __construct($user_id)
+    
+    /**
+     * Get total events count (cached 1 hour)
+     * @return int Event count
+     */
+    public function get_total_events_count()
+    
+    /**
+     * Get upcoming events count (cached 15 minutes)
+     * @return int Event count
+     */
+    public function get_upcoming_events_count()
+    
+    /**
+     * Get past events count (cached 1 hour)
+     * @return int Event count
+     */
+    public function get_past_events_count()
+    
+    /**
+     * Get total tickets sold (cached 30 minutes)
+     * @return int Ticket count
+     */
+    public function get_total_tickets_sold()
+    
+    /**
+     * Get total revenue (cached 30 minutes)
+     * @return float Revenue amount
+     */
+    public function get_total_revenue()
+    
+    /**
+     * Clear all cached data for this user
+     * @return void
+     */
+    public function clear_cache()
+    
+    /**
+     * Get paginated events table data
+     * @param array $args Query arguments
+     * @return array Events and pagination data
+     */
+    public function get_events_table_data($args)
+}
+```
+
 ### HVAC_Menu_System
 
 Handles navigation menu rendering.
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index a7f41e2e..93a93720 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -12,7 +12,49 @@
 
 ## Common Issues
 
-### 1. Pages Not Found (404 Errors)
+### 1. Dashboard Access and Functionality Issues
+
+#### Incorrect Capability Checks
+**Symptoms:**
+- "Access Denied" errors for valid trainers
+- Users with correct roles can't access dashboard
+
+**Root Cause:**
+- Using capability checks instead of role checks for custom roles
+
+**Solution:**
+```php
+// CORRECT - Check user roles directly
+$user = wp_get_current_user();
+$has_trainer_role = in_array('hvac_trainer', $user->roles) || 
+                    in_array('hvac_master_trainer', $user->roles);
+
+// WRONG - Custom roles are not capabilities!
+if (current_user_can('hvac_trainer')) // This won't work!
+```
+
+#### Dashboard Dropdown Menus Not Working
+**Symptoms:**
+- Dropdown menus don't open on click
+- Navigation appears but isn't interactive
+
+**Root Causes & Solutions:**
+1. **Welcome Popup Interference**: Z-index conflicts blocking clicks
+   - Solution: Disable welcome popup or fix z-index layering
+2. **JavaScript Loading Issues**: Check browser console for errors
+3. **Cache Issues**: Clear all caches after deployment
+
+#### Dashboard Performance Issues
+**Symptoms:**
+- Slow loading statistics
+- Database query timeouts
+
+**Solution (Implemented August 2025):**
+- Added WordPress object caching to all dashboard queries
+- Cache duration: 1 hour for stats, 15-30 minutes for time-sensitive data
+- Clear cache manually: `wp_cache_delete('hvac_dashboard_*', 'hvac_dashboard')`
+
+### 2. Pages Not Found (404 Errors)
 
 **Symptoms:**
 - Trainer pages return 404