# Bulk Product Manager - Complete Guide

## Overview

The Bulk Product Manager is an **Excel-style interface** that lets you:
- **ADD multiple new products** at once
- **EDIT existing products** in bulk
- **Copy/paste directly from Excel or Google Sheets**
- **Fast data entry** for invoices

**Think of it as Excel, but it saves directly to your database!**

---

## Quick Start - Add Products from Invoice

### Scenario: You received an invoice with 20 products

**Step-by-Step:**

1. **Open your invoice in Excel or Google Sheets**
2. **Select the columns** you need:
   - Product Code
   - Manufacturer Code
   - Product Name
   - Weight (kg)
   - Purchase Price
3. **Copy** (Ctrl+C)
4. **Login to admin → "Bulk Editor" tab**
5. Click **"Add 10 Empty Rows"** (add enough for your products)
6. **Click the first cell** in the grid
7. **Paste** (Ctrl+V)
8. **Review the data** - prices calculated automatically
9. Click **"Save All Changes"**
10. **Done!** All products created instantly

**Time saved:** From 20 minutes (adding one by one) to **2 minutes** (bulk add)!

---

## Features

### ✅ Add New Products
- Click "Add 5 Empty Rows" or "Add 10 Empty Rows"
- Fill in cells directly
- New rows shown with green background and **+** symbol
- Required fields highlighted in yellow

### ✅ Edit Existing Products
- Click "Load Existing Products"
- Edit any cell
- Changes apply when you save

### ✅ Copy/Paste from Excel/Google Sheets
- **Single cell:** Click cell → Paste
- **Multiple cells:** Click starting cell → Paste → Fills multiple cells automatically
- **Entire rows:** Select first cell → Paste rows from Excel
- Supports Tab-delimited data (Excel format)

### ✅ Smart Price Calculation
- Final price auto-calculates as you type
- Formula: `(Purchase + Processing + Transport) × (1 + Markup%)`
- Updates in real-time

### ✅ Tab Navigation
- Press **Tab** to move to next cell
- Press **Shift+Tab** to go back
- Just like Excel!

### ✅ Validation
- Required fields: Product Name, Weight
- System warns you before saving
- Shows exactly which products have errors

---

## Column Explanations

| Column | Required | Description | Example |
|--------|----------|-------------|---------|
| **NEW** | - | Shows "+" for new products, ID for existing | + or 5 |
| **Cod Produs** | No | Your internal product code | CH001 |
| **Cod Producător** | No | Manufacturer's product code | GR-MAN-001 |
| **Product Name** | **YES** | Name of the chocolate product | Dark Chocolate 70% |
| **Weight (kg)** | **YES** | Weight per unit in kilograms | 0.5 |
| **Purchase €** | No | What you pay supplier per unit | 3.50 |
| **Processing €** | No | Processing cost per unit | 0.50 |
| **Transport €** | No | Allocated transport cost | 1.20 |
| **Markup %** | No | Your profit margin (default 30%) | 30 |
| **Final Price** | - | Auto-calculated selling price | €6.93 |
| **Action** | - | Delete button for this row | Delete |

---

## Workflows

### Workflow 1: Add 10 New Products from Google Sheets

**Your supplier sends you a Google Sheet with products:**

```
Product Code    Name                    Weight    Price
CH-001         Dark Chocolate 70%       0.5      3.50
CH-002         Milk Chocolate           0.5      3.20
CH-003         White Chocolate          0.5      3.80
...
```

**Steps:**

1. In Google Sheets, select the 4 columns for all 10 products
2. Ctrl+C (copy)
3. In your app, go to Bulk Editor
4. Click "Add 10 Empty Rows"
5. Click the **"Cod Produs"** cell in the first row
6. Ctrl+V (paste)
7. All 10 products populate automatically!
8. Review → Save

**Result:** 10 products added in 30 seconds!

---

### Workflow 2: Update Prices for Existing Products

**Your supplier changed prices for 15 products:**

1. Click "Load Existing Products"
2. Find your products in the grid (they show ID numbers)
3. Update the **Purchase €** column for each
4. **Final Price** updates automatically
5. Click "Save All Changes"

**Result:** 15 products updated instantly!

---

### Workflow 3: Mix New and Existing

**You have 5 new products and want to update 8 existing ones:**

1. Click "Load Existing Products" (loads existing)
2. Click "Add 5 Empty Rows" (adds new rows at bottom)
3. Fill in the new product rows
4. Edit the existing product rows
5. Click "Save All Changes"

**Result:** System creates 5 new products AND updates 8 existing ones in one operation!

---

## Copy/Paste Details

### Single Cell Paste
```
Click cell → Paste → Value fills that cell
```

### Multiple Cells Paste (Tab-delimited)
```
Excel data:
CH001    Dark Chocolate    0.5    3.50

Paste into first cell → All 4 cells fill automatically
```

### Multi-Row Paste
```
Excel has 3 rows:
CH001    Dark    0.5    3.50
CH002    Milk    0.5    3.20
CH003    White   0.5    3.80

Click first cell → Paste → All 3 rows fill
```

**The system detects:**
- **Tabs** (`\t`) = multiple columns
- **Newlines** (`\n`) = multiple rows
- Automatically fills the grid

---

## Validation & Error Handling

### Required Field Validation
Before saving, system checks:
- ✅ Product Name filled
- ✅ Weight filled

**If missing:** Shows alert with specific error

### Save Process
System shows exactly what it's doing:
```
Saving changes...
✓ Created 5 new products
✓ Updated 12 existing products
```

### If Errors Occur
```
✓ Created 4 new products
✓ Updated 10 existing products

Errors (2):
- "Dark Chocolate": Weight must be positive
- "Milk Chocolate": Name already exists
```

**You can see which specific products failed!**

---

## Visual Cues

### New Products
- **Green background** on entire row
- **+ symbol** in first column
- **Yellow highlight** on required empty fields

### Existing Products
- **White background**
- **ID number** in first column

### Final Price Column
- **Gray background** (read-only)
- **Bold text**
- Updates automatically when you edit costs

---

## Keyboard Shortcuts

| Key | Action |
|-----|--------|
| **Tab** | Move to next cell |
| **Shift+Tab** | Move to previous cell |
| **Ctrl+C** | Copy (in Excel/Google Sheets) |
| **Ctrl+V** | Paste |
| **Enter** | Save cell and move down |
| **Escape** | Cancel cell edit |

---

## Tips & Tricks

### Tip 1: Prepare Your Excel First
Before opening the app:
1. Open your invoice Excel
2. Clean up the data (remove headers, empty rows)
3. Arrange columns in order: Code → Name → Weight → Price
4. Then copy/paste to app

### Tip 2: Use "Add Empty Rows" Generously
- Add more rows than you need
- You can delete unused rows
- Better to have extras than not enough

### Tip 3: Review Before Saving
- Scroll through all rows
- Check Final Price column makes sense
- Look for yellow highlights (missing required fields)

### Tip 4: Save Often
- Save after adding 5-10 products
- Easier to fix errors in small batches
- If something goes wrong, you haven't lost everything

### Tip 5: Export as Backup
- Click "Export CSV" before big changes
- You have a backup if needed
- Can re-import later

---

## Common Mistakes & Solutions

### Mistake 1: Pasting in Wrong Column
**Problem:** Pasted product names into price column

**Solution:**
- Click the correct starting cell (e.g., "Product Name")
- Paste again
- Or use Ctrl+Z in Excel and re-copy correct columns

### Mistake 2: Forgot to Add Empty Rows
**Problem:** Clicked paste but nothing happened

**Solution:**
- You need empty rows first!
- Click "Add 10 Empty Rows"
- Then paste

### Mistake 3: Mixed Up Tab Order
**Problem:** Data in wrong columns after paste

**Solution:**
- In Excel, columns must be in same order as grid
- Grid order: Cod Produs → Cod Producător → Name → Weight → ...
- Rearrange Excel columns to match

### Mistake 4: Forgot to Save
**Problem:** Closed tab and lost all work

**Solution:**
- **Always click "Save All Changes"** before leaving
- Changes are NOT auto-saved
- When you click Save, you see confirmation message

---

## Advanced: Multi-Cell Paste Algorithm

**How it works:**

1. System detects if paste contains `\t` (tab) or `\n` (newline)
2. If yes → Multi-cell paste mode
3. Splits text by newlines to get rows
4. Splits each row by tabs to get cells
5. Maps to grid columns starting from clicked cell
6. Fills as many cells as possible

**Example:**
```javascript
// You paste this text:
"CH001\tDark Chocolate\t0.5\t3.50\nCH002\tMilk Chocolate\t0.5\t3.20"

// System splits into:
Row 1: ["CH001", "Dark Chocolate", "0.5", "3.50"]
Row 2: ["CH002", "Milk Chocolate", "0.5", "3.20"]

// Fills grid rows 0 and 1, starting from clicked cell
```

---

## Comparison: Old Way vs New Way

### Old Way (One-by-One)
1. Click "Add Product"
2. Fill form
3. Upload image
4. Save
5. Repeat 20 times
6. **Time: 20 minutes**

### New Way (Bulk Add)
1. Copy from Excel
2. Click "Add Empty Rows"
3. Paste
4. Save
5. **Time: 2 minutes**

**10x faster!**

---

## Integration with Other Features

### With Cost Calculator
1. Use Bulk Editor to add products (without pricing)
2. Go to Cost Calculator
3. Calculate transport cost distribution
4. Prices update automatically

### With Invoice Upload
1. Upload invoice → Get matched products
2. Go to Bulk Editor
3. Load existing products
4. Update prices from invoice
5. Save

### With Product Codes
- Add **Cod Produs** and **Cod Producător** in bulk
- Makes reordering easier
- Helps match invoices automatically

---

## Technical Details

### Data Structure
Each row in the grid is:
```javascript
{
    id: null,              // null for new, number for existing
    isNew: true,           // true/false flag
    cod_produs: '',
    cod_producator: '',
    name: '',
    weight_kg: '',
    purchase_cost: '0.00',
    processing_cost: '0.00',
    transport_cost: '0.00',
    markup_percentage: '30',
    final_price: '0.00'   // auto-calculated
}
```

### Save Logic
1. Separates rows into: `newProducts` and `existingProducts`
2. **New products:**
   - POST to `/api/products` (creates product)
   - PUT to `/api/products/:id/price` (sets pricing)
3. **Existing products:**
   - POST to `/api/bulk/bulk-update` (batch update)
4. Shows summary: "Created X, Updated Y"

### Price Calculation Formula
```javascript
totalCost = purchase + processing + transport
finalPrice = totalCost × (1 + markup / 100)

// Example:
// Purchase: €3.50
// Processing: €0.50
// Transport: €1.00
// Total: €5.00
// Markup: 30%
// Final: €5.00 × 1.30 = €6.50
```

---

## Troubleshooting

### Issue: "No data to save"
**Cause:** Grid is empty
**Fix:** Click "Add Empty Rows" or "Load Existing Products"

### Issue: "Missing required fields"
**Cause:** Product Name or Weight not filled
**Fix:** Fill in yellow-highlighted cells

### Issue: Paste doesn't work
**Cause:** Not clicking in editable cell first
**Fix:** Click a cell until it gets blue border, then paste

### Issue: Grid looks wrong after paste
**Cause:** Excel columns don't match grid columns
**Fix:** Rearrange Excel columns to match grid order

### Issue: Final price showing €0.00
**Cause:** No costs entered yet
**Fix:** Fill in Purchase, Processing, or Transport cost

---

## Summary

### What You Get
- ✅ Add 10+ products in under 2 minutes
- ✅ Copy/paste directly from Excel/Google Sheets
- ✅ Edit existing products in bulk
- ✅ Real-time price calculation
- ✅ Clear validation and error messages
- ✅ Mix new and existing products in one operation

### Best For
- **Bulk importing** from supplier invoices
- **Price updates** across many products
- **Initial catalog setup** when starting
- **Seasonal imports** with many products

### Not For
- Single product adds (use "Add Product" button)
- Products with images (use individual add)
- Complex products needing descriptions

---

**Your bulk product management is now 10x faster! 🚀**

**Questions?** Review the workflows above or see [NEW_FEATURES.md](NEW_FEATURES.md) for full feature set.