mirror/TimeTracker
1
0
Fork 0
mirror of https://github.com/DRYTRIX/TimeTracker.git synced 2026-01-06 03:30:25 -06:00
Code Issues Packages Projects Releases Wiki Activity

feat: Add comprehensive project dashboard with analytics and visualizations

Browse Source 
Implement a feature-rich project dashboard that provides visual analytics
and key performance indicators for project tracking and management.

Features:
- Individual project dashboard route (/projects/<id>/dashboard)
- Key metrics cards: Total Hours, Budget Used, Tasks Complete, Team Size
- Budget vs. Actual bar chart with threshold warnings
- Task status distribution doughnut chart
- Team member contributions horizontal bar chart (top 10)
- Time tracking timeline line chart
- Team member details with progress bars
- Recent activity feed (last 10 activities)
- Period filtering (All Time, 7/30/90/365 Days)
- Responsive design with dark mode support
- Navigation button added to project view page

Technical Implementation:
- New route: project_dashboard() in app/routes/projects.py
- Template: app/templates/projects/dashboard.html with Chart.js 4.4.0
- Data aggregation for budget, tasks, team contributions, and timeline
- Optimized database queries with proper filtering
- JavaScript escaping handled with |tojson filters and autoescape control

Testing:
- 20 comprehensive unit tests (test_project_dashboard.py)
- 23 smoke tests (smoke_test_project_dashboard.py)
- Full test coverage for all dashboard functionality

Documentation:
- Complete feature guide (docs/features/PROJECT_DASHBOARD.md)
- Implementation summary (PROJECT_DASHBOARD_IMPLEMENTATION_SUMMARY.md)
- Usage examples and troubleshooting guide

Fixes:
- JavaScript syntax errors from HTML entity escaping
- Proper use of |tojson filter for dynamic values in JavaScript
- Autoescape disabled for script blocks to prevent operator mangling

This dashboard provides project managers and team members with valuable
insights into project health, progress, budget utilization, and resource
allocation at a glance.
This commit is contained in:
Dries Peeters
2025-10-30 10:43:31 +01:00
parent 4f9e6ec696
commit 0da5ac0077
6 changed files with 2044 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

496
docs/features/PROJECT_DASHBOARD.md Normal file
View File

@@ -0,0 +1,496 @@
# Project Dashboard Feature
## Overview
The Project Dashboard provides a comprehensive, visual overview of project performance, progress, and team contributions. It aggregates key metrics and presents them through interactive charts and visualizations, making it easy to track project health at a glance.
## Features
### 1. Key Metrics Overview
- **Total Hours**: Real-time tracking of all logged hours on the project
- **Budget Used**: Visual representation of consumed budget vs. allocated budget
- **Task Completion**: Percentage of tasks completed with completion rate
- **Team Size**: Number of team members actively contributing to the project
### 2. Budget vs. Actual Visualization
- **Budget Tracking**: Compare budgeted amount against actual consumption
- **Hours Comparison**: Estimated hours vs. actual hours worked
- **Threshold Warnings**: Visual alerts when budget threshold is exceeded
- **Remaining Budget**: Calculate and display remaining budget
- **Interactive Bar Chart**: Visual representation using Chart.js
### 3. Task Status Distribution
- **Status Breakdown**: Visual pie chart showing tasks by status (Todo, In Progress, Review, Done, Cancelled)
- **Completion Rate**: Overall task completion percentage
- **Overdue Tasks**: Count and highlight overdue tasks
- **Color-coded Status**: Easy-to-understand visual indicators
### 4. Team Member Contributions
- **Hours Breakdown**: Time contributed by each team member
- **Percentage Distribution**: Visual representation of team effort distribution
- **Entry Counts**: Number of time entries per team member
- **Task Assignments**: Number of tasks assigned to each member
- **Interactive Horizontal Bar Chart**: Compare team member contributions
### 5. Time Tracking Timeline
- **Daily Hours Tracking**: Line chart showing hours logged over time
- **Period Filtering**: View timeline for different time periods
- **Trend Analysis**: Visualize work patterns and project velocity
- **Interactive Line Chart**: Hover to see specific day details
### 6. Recent Activity Feed
- **Activity Log**: Real-time feed of recent project activities
- **User Actions**: Track who did what and when
- **Entity-specific Actions**: Project, task, and time entry activities
- **Timestamp Display**: Clear chronological ordering of events
- **Icon Indicators**: Visual icons for different activity types
### 7. Time Period Filtering
- **All Time**: View entire project history
- **Last 7 Days**: Focus on recent week's activities
- **Last 30 Days**: Monthly project view
- **Last 3 Months**: Quarterly overview
- **Last Year**: Annual performance review
## Dashboard Sections
### Top Navigation
- **Back to Project**: Easy navigation back to project detail page
- **Project Name & Code**: Clear project identification
- **Period Filter**: Dropdown to select time period
### Metrics Cards (4 Cards)
1. **Total Hours Card**
- Large number display of total hours
- Estimated hours comparison
- Blue clock icon
2. **Budget Used Card**
- Budget consumption amount
- Percentage of total budget
- Green/Red indicator based on threshold
- Dollar sign icon
3. **Tasks Complete Card**
- Completed vs. total tasks
- Completion percentage
- Purple tasks icon
4. **Team Members Card**
- Number of contributing members
- Orange users icon
### Visualization Charts
#### Budget vs. Actual Chart
- **Type**: Bar Chart
- **Data**: Budget, Consumed, Remaining
- **Colors**: Blue for budget, Green/Red for consumed, Green/Red for remaining
- **Shows**: When budget is exceeded with visual warnings
#### Task Status Distribution Chart
- **Type**: Doughnut Chart
- **Data**: Count of tasks by status
- **Colors**:
- Gray: Todo
- Blue: In Progress
- Orange: Review
- Green: Done
- Red: Cancelled
- **Legend**: Bottom position with status labels
#### Team Contributions Chart
- **Type**: Horizontal Bar Chart
- **Data**: Hours per team member
- **Colors**: Purple theme
- **Shows**: Top 10 contributors
#### Time Tracking Timeline Chart
- **Type**: Line Chart
- **Data**: Daily hours over selected period
- **Colors**: Blue with gradient fill
- **Shows**: Work pattern and trends
### Team Member Details Section
Shows detailed breakdown for each team member:
- Name and total hours
- Number of time entries
- Number of assigned tasks
- Percentage of total project time
- Visual progress bar
### Recent Activity Section
Displays up to 10 recent activities:
- User avatar/icon
- Action description
- Timestamp
- Color-coded by action type
## Navigation
### Accessing the Dashboard
1. **From Project View**
- Navigate to any project
- Click the purple "Dashboard" button in the header
- Located next to the "Edit Project" button
2. **Direct URL**
- `/projects/<project_id>/dashboard`
### Permissions
- All authenticated users can view project dashboards
- No special permissions required
- Same access level as project view
## Usage Examples
### Scenario 1: Project Manager Monitoring Progress
A project manager wants to check if the project is on track:
1. Navigate to project dashboard
2. Check key metrics cards for overview
3. Review budget chart for financial health
4. Check task completion chart for progress
5. Review timeline to ensure consistent work pace
6. Check team contributions for resource utilization
### Scenario 2: Client Reporting
Preparing a client report:
1. Open project dashboard
2. Select "Last Month" from period filter
3. Screenshot key metrics
4. Export budget vs. actual chart
5. Document team member contributions
6. Include recent activity highlights
### Scenario 3: Sprint Planning
Planning next sprint based on team capacity:
1. View team contributions section
2. Analyze each member's current workload
3. Check timeline for work patterns
4. Review task completion rates
5. Allocate tasks based on contribution percentages
### Scenario 4: Budget Review
Monitoring budget utilization:
1. Check budget used percentage in metrics card
2. Review budget vs. actual chart
3. Calculate remaining budget
4. Check if threshold is exceeded
5. Review timeline to understand burn rate
## Technical Implementation
### Route
```python
@projects_bp.route('/projects/<int:project_id>/dashboard')
@login_required
def project_dashboard(project_id):
"""Project dashboard with comprehensive analytics and visualizations"""
```
### Data Aggregation
#### Budget Data
```python
budget_data = {
'budget_amount': float(project.budget_amount),
'consumed_amount': project.budget_consumed_amount,
'remaining_amount': budget_amount - consumed_amount,
'percentage': (consumed_amount / budget_amount) * 100,
'threshold_exceeded': project.budget_threshold_exceeded,
'estimated_hours': project.estimated_hours,
'actual_hours': project.actual_hours,
'remaining_hours': estimated_hours - actual_hours,
'hours_percentage': (actual_hours / estimated_hours) * 100
}
```
#### Task Statistics
```python
task_stats = {
'total': count of all tasks,
'by_status': dictionary of status counts,
'completed': count of done tasks,
'in_progress': count of in-progress tasks,
'todo': count of todo tasks,
'completion_rate': (completed / total) * 100,
'overdue': count of overdue tasks
}
```
#### Team Contributions
```python
team_contributions = [
{
'username': member username,
'total_hours': hours worked,
'entry_count': number of entries,
'task_count': assigned tasks,
'percentage': (member_hours / project_hours) * 100
}
]
```
### Frontend Libraries
#### Chart.js 4.4.0
Used for all visualizations:
- Budget chart (Bar)
- Task status (Doughnut)
- Team contributions (Horizontal Bar)
- Timeline (Line)
#### Tailwind CSS
Responsive layout with dark mode support:
- Grid system for responsive cards
- Dark mode classes
- Hover effects and transitions
### Database Queries
Dashboard performs optimized queries to fetch:
1. Project details and budget info
2. All tasks with status counts
3. Time entries grouped by user
4. Time entries grouped by date
5. Recent activities filtered by project
### Performance Considerations
- Data is aggregated on the backend
- Charts render client-side with Chart.js
- Caching recommended for large projects
- Pagination considered for large activity lists
## API Response Format
While the dashboard is primarily a web view, the underlying data structure is:
```json
{
"project": {
"id": 1,
"name": "Example Project",
"code": "EXAM"
},
"budget_data": {
"budget_amount": 5000.0,
"consumed_amount": 3500.0,
"remaining_amount": 1500.0,
"percentage": 70.0,
"threshold_exceeded": false
},
"task_stats": {
"total": 20,
"completed": 12,
"in_progress": 5,
"todo": 3,
"completion_rate": 60.0,
"overdue": 1
},
"team_contributions": [
{
"username": "john_doe",
"total_hours": 45.5,
"entry_count": 23,
"task_count": 8,
"percentage": 35.2
}
],
"timeline_data": [
{
"date": "2024-01-15",
"hours": 8.5
}
]
}
```
## Best Practices
### For Project Managers
1. **Regular Monitoring**: Check dashboard daily or weekly
2. **Budget Tracking**: Set up budget thresholds appropriately
3. **Team Balance**: Monitor contribution distribution
4. **Early Warnings**: Act on budget threshold warnings
5. **Documentation**: Export charts for reports
### For Team Leads
1. **Resource Planning**: Use contribution data for allocation
2. **Velocity Tracking**: Monitor timeline patterns
3. **Task Management**: Keep task statuses updated
4. **Team Health**: Ensure balanced workload distribution
### For Developers
1. **Data Updates**: Ensure time entries are logged consistently
2. **Task Updates**: Keep task statuses current
3. **Budget Awareness**: Check budget consumption regularly
## Troubleshooting
### Dashboard Shows No Data
**Issue**: Dashboard displays empty states for all charts
**Solutions**:
- Verify project has time entries
- Check that tasks are created
- Ensure budget is set (if using budget features)
- Verify period filter isn't excluding all data
### Budget Chart Not Displaying
**Issue**: Budget section shows "No budget set"
**Solutions**:
- Edit project and set budget_amount
- Set hourly_rate if using hourly billing
- Ensure budget_threshold_percent is configured
### Team Contributions Empty
**Issue**: No team members shown
**Solutions**:
- Verify time entries exist for the project
- Check that time entries have end_time (completed)
- Ensure user assignments are correct
### Charts Not Rendering
**Issue**: Canvas elements visible but no charts
**Solutions**:
- Check browser console for JavaScript errors
- Verify Chart.js is loading correctly
- Check browser compatibility (modern browsers required)
- Clear browser cache
### Period Filter Not Working
**Issue**: Selecting different periods shows same data
**Solutions**:
- Check URL parameter is changing (?period=week)
- Verify date filtering logic in backend
- Ensure time entry dates are within selected period
## Future Enhancements
### Planned Features
1. **Export Functionality**: Export dashboard as PDF report
2. **Custom Date Ranges**: Allow custom start/end date selection
3. **Milestone Tracking**: Visual milestone progress indicators
4. **Cost Integration**: Include project costs in visualizations
5. **Comparative Analysis**: Compare against similar projects
6. **Predictive Analytics**: Project completion date estimation
7. **Alerts & Notifications**: Configurable dashboard alerts
8. **Widget Customization**: Allow users to customize dashboard layout
9. **Mobile Optimization**: Enhanced mobile dashboard view
10. **Real-time Updates**: WebSocket-based live data updates
### Enhancement Requests
To request new dashboard features, please:
1. Open an issue on GitHub
2. Describe the use case
3. Provide mockups if possible
4. Tag with "feature-request" and "dashboard"
## Related Features
- [Project Management](PROJECT_COSTS_FEATURE.md)
- [Task Management](../TASK_MANAGEMENT_README.md)
- [Time Tracking](../QUICK_REFERENCE_GUIDE.md)
- [Team Collaboration](FAVORITE_PROJECTS_FEATURE.md)
- [Reporting](../QUICK_WINS_UI.md)
## Testing
### Unit Tests
Location: `tests/test_project_dashboard.py`
- Dashboard access and authentication
- Data calculation accuracy
- Period filtering
- Edge cases (no data, missing budget)
### Smoke Tests
Location: `tests/smoke_test_project_dashboard.py`
- Dashboard loads successfully
- All sections render
- Charts display correctly
- Navigation works
- Period filter functions
### Running Tests
```bash
# Run all dashboard tests
pytest tests/test_project_dashboard.py -v
# Run smoke tests only
pytest tests/smoke_test_project_dashboard.py -v
# Run with coverage
pytest tests/test_project_dashboard.py --cov=app.routes.projects
```
## Accessibility
### Features
- **Keyboard Navigation**: Full keyboard support
- **Screen Reader Support**: Proper ARIA labels
- **Color Contrast**: WCAG AA compliant
- **Focus Indicators**: Clear focus states
- **Alternative Text**: Descriptive alt text for visualizations
### Recommendations
- Use screen reader to announce chart data
- Provide data table alternatives for charts
- Ensure all interactive elements are keyboard accessible
## Browser Compatibility
### Supported Browsers
- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+
### Required Features
- ES6 JavaScript support
- Canvas API for Chart.js
- CSS Grid and Flexbox
- Fetch API
## Security Considerations
### Authentication
- Dashboard requires login
- Project access follows existing permissions
- No special dashboard permissions
### Data Privacy
- Only project team members see dashboard
- Activity feed respects privacy settings
- No external data sharing
### Performance
- Query optimization for large datasets
- Client-side rendering for charts
- Caching strategies for repeated access
## Support
For issues or questions:
- Check [Troubleshooting](#troubleshooting) section
- Review [GitHub Issues](https://github.com/yourusername/TimeTracker/issues)
- Contact project maintainers
- Review test files for examples
## Changelog
### Version 1.0.0 (2024-10)
- Initial release of Project Dashboard
- Budget vs. Actual visualization
- Task status distribution chart
- Team member contributions
- Time tracking timeline
- Recent activity feed
- Period filtering
- Responsive design with dark mode
---
**Last Updated**: October 2024
**Feature Status**: ✅ Active
**Requires**: TimeTracker v1.0+