helpdesk_rating_five_stars/INSTALL.md

# Installation Guide - Helpdesk Rating Five Stars

## Quick Installation

### Prerequisites

Before installing, ensure you have:

- ✅ Odoo 18.0 or higher installed
- ✅ Helpdesk module installed and configured
- ✅ Database backup (recommended)
- ✅ Administrator access to Odoo

### Installation Steps

#### 1. Copy Module Files

Copy the module to your Odoo addons directory:

```bash
# For standard addons directory
sudo cp -r helpdesk_rating_five_stars /opt/odoo/addons/

# For custom addons directory
sudo cp -r helpdesk_rating_five_stars /opt/odoo/custom/addons/
```

Set proper permissions:

```bash
sudo chown -R odoo:odoo /opt/odoo/addons/helpdesk_rating_five_stars
# or
sudo chown -R odoo:odoo /opt/odoo/custom/addons/helpdesk_rating_five_stars
```

#### 2. Update Odoo Configuration

Edit your `odoo.conf` file to include the addons path:

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

#### 3. Restart Odoo Server

```bash
# Using systemd
sudo systemctl restart odoo

# Or using service
sudo service odoo restart

# Or if running manually
./odoo-bin -c /etc/odoo/odoo.conf
```

#### 4. Update Apps List

1. Log in to Odoo as Administrator
2. Navigate to **Apps** menu
3. Click **Update Apps List** (top-right menu)
4. Click **Update** in the confirmation dialog
5. Wait for the list to refresh

#### 5. Install the Module

1. In the **Apps** menu, remove the "Apps" filter
2. Search for "Helpdesk Rating Five Stars"
3. Click the **Install** button
4. Wait for installation to complete (usually 10-30 seconds)
5. You'll see a success notification

#### 6. Verify Installation

Check that the module is working:

- [ ] Go to **Helpdesk → Tickets**
- [ ] Open any ticket with a rating
- [ ] Verify stars are displayed instead of emoticons
- [ ] Check that email templates show 5 stars
- [ ] Test rating submission from a test email

## Detailed Installation

### For Development Environment

```bash
# Clone or copy module
cd /path/to/odoo/custom/addons
cp -r /path/to/helpdesk_rating_five_stars .

# Install in development mode
./odoo-bin -c odoo.conf -d your_database -i helpdesk_rating_five_stars --dev=all

# With test mode
./odoo-bin -c odoo.conf -d test_database -i helpdesk_rating_five_stars --test-enable --stop-after-init
```

### For Production Environment

```bash
# 1. Backup database first!
pg_dump -U odoo -d production_db > backup_$(date +%Y%m%d).sql

# 2. Copy module
sudo cp -r helpdesk_rating_five_stars /opt/odoo/addons/
sudo chown -R odoo:odoo /opt/odoo/addons/helpdesk_rating_five_stars

# 3. Restart Odoo
sudo systemctl restart odoo

# 4. Install via web interface (recommended)
# Or via command line:
./odoo-bin -c /etc/odoo/odoo.conf -d production_db -i helpdesk_rating_five_stars --stop-after-init
```

### For Docker Environment

```dockerfile
# Add to your Dockerfile
COPY helpdesk_rating_five_stars /mnt/extra-addons/helpdesk_rating_five_stars

# Or mount as volume in docker-compose.yml
volumes:
  - ./helpdesk_rating_five_stars:/mnt/extra-addons/helpdesk_rating_five_stars
```

Then:

```bash
# Rebuild and restart container
docker-compose down
docker-compose up -d

# Install module
docker-compose exec odoo odoo -d your_database -i helpdesk_rating_five_stars --stop-after-init
```

## Post-Installation

### Verify Migration

Check that existing ratings were migrated:

```sql
-- Connect to database
psql -U odoo -d your_database

-- Check rating distribution
SELECT rating, COUNT(*) as count
FROM rating_rating
WHERE rating > 0
GROUP BY rating
ORDER BY rating;

-- Expected results: ratings should be in 1-5 range
-- Old 0-3 ratings should be converted to 0, 3, 4, 5
```

### Check Server Logs

```bash
# View recent logs
tail -n 100 /var/log/odoo/odoo-server.log

# Look for migration messages
grep -i "rating migration" /var/log/odoo/odoo-server.log

# Check for errors
grep -i "error" /var/log/odoo/odoo-server.log | grep -i "rating"
```

### Test Functionality

1. **Test Email Rating**:
   - Create a test ticket
   - Close the ticket
   - Send rating request email
   - Click a star in the email
   - Verify rating is recorded

2. **Test Web Rating**:
   - Access rating form via link
   - Hover over stars (should highlight)
   - Click a star to select
   - Submit the form
   - Verify confirmation page

3. **Test Backend Display**:
   - Open ticket with rating
   - Verify stars display correctly
   - Check list view shows stars
   - Check kanban view shows stars

4. **Test Reports**:
   - Go to Helpdesk → Reporting → Ratings
   - Verify average uses 0-5 scale
   - Test filtering by rating
   - Export data and verify values

## Troubleshooting Installation

### Module Not Found

**Problem**: Module doesn't appear in Apps list

**Solution**:
```bash
# Check module is in addons path
ls -la /opt/odoo/addons/helpdesk_rating_five_stars

# Check odoo.conf has correct addons_path
cat /etc/odoo/odoo.conf | grep addons_path

# Restart Odoo
sudo systemctl restart odoo

# Update apps list again
```

### Installation Fails

**Problem**: Error during installation

**Solution**:
```bash
# Check server logs
tail -f /var/log/odoo/odoo-server.log

# Common issues:
# - Missing dependencies: Install helpdesk, rating, mail, web modules first
# - Permission errors: Check file ownership and permissions
# - Database errors: Check PostgreSQL logs
```

### Migration Errors

**Problem**: Existing ratings not converted

**Solution**:
```bash
# Check migration logs
grep -i "migration" /var/log/odoo/odoo-server.log

# Manually run migration if needed
# (Contact administrator or see hooks.py)

# Verify database state
psql -U odoo -d your_database -c "SELECT rating, COUNT(*) FROM rating_rating GROUP BY rating;"
```

### Stars Not Displaying

**Problem**: Stars don't show in backend

**Solution**:
```bash
# Clear browser cache
# Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)

# Check static files are served
curl http://your-odoo-url/helpdesk_rating_five_stars/static/src/js/rating_stars.js

# Restart Odoo with assets rebuild
./odoo-bin -c odoo.conf -d your_database --dev=all

# Check browser console for errors
# Open browser DevTools (F12) and check Console tab
```

## Uninstallation

If you need to uninstall the module:

### Via Web Interface

1. Go to **Apps** menu
2. Remove "Apps" filter
3. Search for "Helpdesk Rating Five Stars"
4. Click **Uninstall**
5. Confirm uninstallation

**Note**: Ratings will remain in 0-5 scale after uninstallation. They will not be automatically converted back to 0-3.

### Via Command Line

```bash
./odoo-bin -c odoo.conf -d your_database -u helpdesk_rating_five_stars --stop-after-init
```

### Complete Removal

```bash
# Uninstall module first (via web or command line)

# Remove module files
sudo rm -rf /opt/odoo/addons/helpdesk_rating_five_stars

# Restart Odoo
sudo systemctl restart odoo
```

## Upgrade

To upgrade to a newer version:

```bash
# 1. Backup database
pg_dump -U odoo -d production_db > backup_before_upgrade.sql

# 2. Replace module files
sudo rm -rf /opt/odoo/addons/helpdesk_rating_five_stars
sudo cp -r helpdesk_rating_five_stars_new_version /opt/odoo/addons/helpdesk_rating_five_stars
sudo chown -R odoo:odoo /opt/odoo/addons/helpdesk_rating_five_stars

# 3. Restart Odoo
sudo systemctl restart odoo

# 4. Upgrade module
./odoo-bin -c odoo.conf -d production_db -u helpdesk_rating_five_stars --stop-after-init

# 5. Test functionality
```

## Support

For installation support:

- **Documentation**: See README.md and USER_GUIDE.md
- **Logs**: Check `/var/log/odoo/odoo-server.log`
- **Administrator**: Contact your Odoo system administrator
- **Community**: Odoo community forums

## Checklist

Use this checklist to ensure proper installation:

- [ ] Prerequisites verified (Odoo 18, Helpdesk installed)
- [ ] Database backed up
- [ ] Module files copied to addons directory
- [ ] File permissions set correctly
- [ ] Odoo configuration updated
- [ ] Odoo server restarted
- [ ] Apps list updated
- [ ] Module installed successfully
- [ ] Migration completed (check logs)
- [ ] Email templates show 5 stars
- [ ] Backend views show stars
- [ ] Reports use 0-5 scale
- [ ] Test rating submission works
- [ ] Mobile responsive design verified
- [ ] Keyboard navigation tested
- [ ] No errors in server logs
- [ ] No errors in browser console

---

**Installation Time**: 5-10 minutes  
**Difficulty**: Easy  
**Required Access**: Administrator

**Version**: 1.0  
**Last Updated**: 2024-11-25