# Sales Objectives Setup Guide

## Overview
This guide explains how to set up sales objectives for the Sales Dashboard Performance Tracking system.

## Objectives Sheet Structure

You need to create a new sheet tab in your Google Sheets called **"Objetivos"** with the following columns:

### Required Columns:
1. **Comercial** - Sales representative name (e.g., "Jose Amor", "Helder Oliveira")
2. **Cliente** - Client name, or "Total" for overall objectives
3. **Target_Valor** - Revenue target (€) as a number
4. **Target_Urnas** - URNAS (quantity) target as a number
5. **Period** - Optional: "Monthly", "Quarterly", "Annual"

### Example Setup:

```
Comercial          | Cliente           | Target_Valor | Target_Urnas | Period
Jose Amor          | Total             | 50000        | 1000         | Annual
Jose Amor          | Client A          | 15000        | 300          | Annual
Jose Amor          | Client B          | 20000        | 400          | Annual
Jose Amor          | Client C          | 15000        | 300          | Annual
Helder Oliveira    | Total             | 45000        | 900          | Annual
Helder Oliveira    | Client D          | 22000        | 450          | Annual
Helder Oliveira    | Client E          | 23000        | 450          | Annual
```

## Column Details

### Comercial
- Must match exactly with sales rep names in your data
- Example values: "Jose Amor", "Helder Oliveira"

### Cliente
- Client name as it appears in your main sales data
- Use "Total" for overall sales targets (summarizes all clients for that comercial)
- Must match your sales data client names exactly

### Target_Valor (€)
- Revenue target in euros
- Enter as number only (no currency symbol)
- Examples: 50000, 15000.50

### Target_Urnas
- Target quantity for URNAS product family
- Enter as whole number
- Examples: 1000, 300

### Period (Optional)
- Helps organize objectives by time period
- Values: "Annual", "Quarterly", "Monthly"
- Used for future filtering capabilities

## How to Create the Sheet

1. Open your Google Sheets spreadsheet
2. Click the "+" button at the bottom to create a new sheet
3. Rename the sheet to **"Objetivos"**
4. Add headers in the first row:
   - A1: Comercial
   - B1: Cliente
   - C1: Target_Valor
   - D1: Target_Urnas
   - E1: Period

5. Enter your objective data starting from row 2

## Performance Tracking

Once objectives are set up, the dashboard will automatically:

### On the Performance Dashboard (`/performance`):
- Show total revenue target vs actual for each comercial
- Show total URNAS target vs actual for each comercial
- Display achievement percentage (0-150%+)
- Show color-coded status badges:
  - 🟢 **Excellent**: ≥ 100% achievement
  - 🔵 **Good**: 80-99% achievement
  - 🟡 **Warning**: 60-79% achievement
  - 🔴 **Below Target**: < 60% achievement

### Performance by Client:
- Individual metrics for each client
- Revenue achievement % by client
- URNAS achievement % by client

### Performance Report (`/performance-report/<comercial>`):
- Detailed report for specific comercial
- Printable format (press Ctrl+P or click Print button)
- Summary metrics and by-client breakdown
- PDF export ready

## Important Notes

1. **Exact Matching**: Comercial and Cliente names must match exactly (case-sensitive) with your sales data
2. **Column Names**: Header row names must match exactly as shown above
3. **Data Type**: Targets should be numbers only (no currency symbols, no commas)
4. **Updates**: Changes to objectives are reflected immediately in the dashboard

## Troubleshooting

### Objectives Not Appearing
- Verify sheet is named "Objetivos" (exact spelling)
- Check column headers match exactly
- Ensure comercial and client names match your sales data

### Performance Shows 0%
- Check if comercial name matches exactly in both sheets
- Verify client names are spelled identically
- Confirm data has been recorded for that comercial

### Wrong Achievement %
- Verify target values are numbers (not text)
- Check for extra spaces in comercial/client names
- Ensure formula is calculating correct period

## Advanced Usage

### Multiple Time Periods
Add multiple rows for the same comercial/client combination with different periods:

```
Jose Amor | Client A | 5000  | 100 | Monthly (01/2025)
Jose Amor | Client A | 15000 | 300 | Quarterly (Q1 2025)
Jose Amor | Client A | 60000 | 1200| Annual (2025)
```

### Target Adjustments
- Simply update the Target_Valor or Target_Urnas numbers
- Dashboard updates automatically on refresh

## Access Control

- **Admin**: Can see all comercials' objectives and performance
- **Viewer**: Can see all comercials' objectives and performance
- **Comercial**: Can only see their own performance

## Performance Routes

- `/performance` - Main performance dashboard showing all comercials
- `/performance-report/<comercial>` - Detailed report for specific comercial (printable)

---

**Last Updated**: February 2025
**Version**: 1.0