# Helpdesk Rating Five Stars

[![Odoo Version](https://img.shields.io/badge/Odoo-18.0-875A7B)](https://www.odoo.com/)
[![License](https://img.shields.io/badge/License-LGPL--3-blue)](https://www.gnu.org/licenses/lgpl-3.0.html)

## Overview

This module extends Odoo 18's Helpdesk application by replacing the standard 3-emoticon rating system with a 5-star rating system. It provides customers with more granular feedback options (1-5 stars instead of 0-3 emoticons) and gives helpdesk managers better insights into customer satisfaction.

## Features

- ⭐ **5-Star Rating System**: Replace emoticons with intuitive star ratings
- 📧 **Email Integration**: Clickable star links in rating request emails
- 🎨 **Interactive Widget**: Beautiful star rating widget with hover effects
- 🔄 **Automatic Migration**: Seamlessly converts existing 0-3 ratings to 0-5 scale
- 📊 **Enhanced Reports**: Updated analytics and statistics using 0-5 scale
- 👁️ **Backend Display**: Star ratings visible in all ticket views
- 📱 **Responsive Design**: Optimized for mobile and desktop
- ♿ **Accessible**: Keyboard navigation and screen reader support
- 🔌 **API Compatible**: Full compatibility with Odoo's rating API

## Requirements

- **Odoo Version**: 18.0 or higher
- **Python**: 3.10+
- **PostgreSQL**: 12+
- **Dependencies**: helpdesk, rating, mail, web

## Installation

### 1. Copy Module

```bash
cp -r helpdesk_rating_five_stars /path/to/odoo/addons/
```

### 2. Update Addons Path

Ensure your `odoo.conf` includes the addons directory:

```ini
[options]
addons_path = /path/to/odoo/addons,/path/to/custom/addons
```

### 3. Restart Odoo

```bash
sudo systemctl restart odoo
```

### 4. Install Module

1. Go to **Apps** menu
2. Click **Update Apps List**
3. Search for "Helpdesk Rating Five Stars"
4. Click **Install**

## Configuration

The module works out of the box with zero configuration required. All existing ratings are automatically migrated during installation.

### Rating Migration Mapping

| Old Rating (0-3) | New Rating (0-5) | Description |
|------------------|------------------|-------------|
| 0 | 0 | No rating |
| 1 (😞) | 3 (⭐⭐⭐) | Neutral |
| 2 (😐) | 4 (⭐⭐⭐⭐) | Good |
| 3 (😊) | 5 (⭐⭐⭐⭐⭐) | Excellent |

## Usage

### Customer Rating Flow

1. **Via Email**: Customer receives rating request email with 5 clickable stars
2. **Via Web Form**: Customer accesses web form with interactive star widget
3. **Selection**: Customer clicks desired star (1-5)
4. **Submission**: Rating is recorded and customer sees confirmation
5. **Display**: Rating appears as stars in backend ticket views

### Backend Views

- **Form View**: Full star display with filled/empty stars
- **List View**: Compact star display in rating column
- **Kanban View**: Star rating on ticket cards
- **Reports**: Analytics using 0-5 scale

## Technical Details

### Module Structure

```
helpdesk_rating_five_stars/
├── __init__.py
├── __manifest__.py
├── README.md
├── models/
│   ├── __init__.py
│   ├── rating_rating.py          # Extended rating model
│   ├── helpdesk_ticket.py         # Extended ticket model
│   └── helpdesk_ticket_report.py  # Extended report model
├── controllers/
│   ├── __init__.py
│   └── rating.py                  # Rating submission controller
├── views/
│   ├── rating_rating_views.xml
│   ├── helpdesk_ticket_views.xml
│   ├── helpdesk_ticket_report_views.xml
│   └── rating_templates.xml
├── data/
│   └── mail_templates.xml
├── static/
│   ├── src/
│   │   ├── js/
│   │   │   └── rating_stars.js
│   │   ├── xml/
│   │   │   └── rating_stars.xml
│   │   └── scss/
│   │       └── rating_stars.scss
│   └── description/
│       ├── index.html
│       ├── icon.svg
│       └── widget_demo.html
├── security/
│   ├── ir.model.access.csv
│   └── helpdesk_rating_security.xml
├── tests/
│   ├── __init__.py
│   ├── test_rating_model.py
│   ├── test_rating_controller.py
│   ├── test_rating_migration.py
│   ├── test_helpdesk_ticket.py
│   ├── test_rating_views.py
│   ├── test_rating_reports.py
│   └── test_rating_security.py
└── hooks.py                       # Post-install migration hook
```

### Key Components

#### Models

- **rating.rating**: Extended to support 0-5 rating scale with validation
- **helpdesk.ticket**: Added computed fields for star display
- **helpdesk.ticket.report**: Updated for 0-5 scale analytics

#### Controllers

- **RatingController**: Handles rating submissions from email links and web forms

#### JavaScript

- **RatingStars**: OWL component for interactive star rating widget

#### Views

- Backend views with star display (form, tree, kanban)
- Web rating form template
- Email rating request template

### Database Schema

No new tables are created. The module extends existing tables:

- Modifies constraints on `rating_rating.rating` field (0 or 1-5)
- Adds computed fields for star display
- Migration updates existing rating values

### API Compatibility

The module maintains full compatibility with Odoo's rating API:

- All standard rating methods work unchanged
- Other modules using rating system continue to function
- No breaking changes to rating model interface

## Development

### Running Tests

```bash
# Run all tests
odoo-bin -c odoo.conf -d test_db -i helpdesk_rating_five_stars --test-enable --stop-after-init

# Run specific test file
odoo-bin -c odoo.conf -d test_db --test-tags helpdesk_rating_five_stars.test_rating_model
```

### Code Style

- Follow Odoo coding guidelines
- Use proper model inheritance patterns
- Document all methods and classes
- Write comprehensive tests

### Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Write/update tests
5. Submit a pull request

## Troubleshooting

### Stars Not Displaying

**Problem**: Stars don't appear in backend views

**Solution**:
- Clear browser cache
- Restart Odoo server
- Check browser console for errors
- Verify static files are served correctly

### Email Links Not Working

**Problem**: Clicking star in email doesn't work

**Solution**:
- Verify base URL in Odoo settings
- Check rating token validity
- Review server logs for errors
- Ensure controller route is accessible

### Migration Issues

**Problem**: Existing ratings not converted

**Solution**:
- Check Odoo logs for migration errors
- Verify database permissions
- Uninstall and reinstall module if needed
- Contact support for data integrity issues

## Security

The module implements several security measures:

- **Token-based authentication** for rating submissions
- **Server-side validation** of all rating values
- **SQL injection prevention** through ORM usage
- **Access control** for rating modifications
- **Audit logging** for rating changes

## Accessibility

The module follows WCAG 2.1 AA standards:

- Keyboard navigation support (arrow keys, Enter)
- ARIA labels for screen readers
- Touch-friendly sizing for mobile
- High contrast colors
- Clear focus indicators

## Performance

Optimizations included:

- Indexed rating field for fast queries
- Computed fields with storage for frequent access
- Batch migration updates (1000 records at a time)
- CSS-based star rendering (no images)
- Lazy loading of JavaScript widget

## Compatibility

Compatible with:

- Odoo 18 Community and Enterprise
- All standard Odoo modules using rating system
- Multi-company configurations
- Multi-language installations
- Custom modules with proper inheritance

## License

This module is licensed under LGPL-3. See LICENSE file for details.

## Support

For support:

- Contact your Odoo administrator
- Review module documentation
- Check Odoo server logs
- Consult source code

## Credits

Developed for Odoo 18 Helpdesk application enhancement.

---

**Version**: 1.0  
**Author**: Custom Development  
**Maintainer**: Odoo Administrator