# Upgrade Guide: vendor_payment_diff_amount v1.x to v2.0

## Overview

Version 2.0 introduces a major architectural change: converting from single deduction fields to multiple deduction lines (One2many relationship).

## What Changed

### Database Schema Changes

**Removed/Changed Fields:**
- `account.payment.amount_substract` - Changed from stored field to computed field
- `account.payment.substract_account_id` - Removed (replaced by deduction lines)
- `account.batch.payment.line.amount_substract` - Changed to computed field
- `account.batch.payment.line.substract_account_id` - Removed

**New Model:**
- `payment.deduction.line` - Stores individual deduction entries

**New Fields:**
- `account.payment.deduction_line_ids` (One2many)
- `account.batch.payment.line.deduction_line_ids` (One2many)

### Code Changes

1. **Models:**
   - New model: `payment_deduction_line.py`
   - Updated: `account_payment.py` - uses One2many for deductions
   - Updated: `account_batch_payment.py` - transfers deduction lines

2. **Views:**
   - Payment form: Shows editable tree for deduction lines
   - Batch payment form: Shows deduction lines in line form view

3. **Security:**
   - Added access rights for `payment.deduction.line`

## Upgrade Steps

### 1. Backup Your Database

```bash
# Create a full database backup before upgrading
pg_dump your_database > backup_before_v2_upgrade.sql
```

### 2. Install the Update

```bash
# Update the module
./odoo-bin -u vendor_payment_diff_amount -d your_database
```

### 3. Data Migration (if needed)

If you have existing payments with deductions, you'll need to migrate them. Here's a sample migration script:

```python
# Run this in Odoo shell: ./odoo-bin shell -d your_database

# Find all payments with deductions (old structure)
payments = env['account.payment'].search([
    ('amount_substract', '>', 0),
    ('substract_account_id', '!=', False)
])

print(f"Found {len(payments)} payments with deductions to migrate")

# For each payment, create a deduction line
for payment in payments:
    # Check if already migrated
    if payment.deduction_line_ids:
        print(f"Payment {payment.id} already has deduction lines, skipping")
        continue
    
    # Create deduction line from old fields
    env['payment.deduction.line'].create({
        'payment_id': payment.id,
        'amount_substract': payment.amount_substract,
        'substract_account_id': payment.substract_account_id.id,
        'name': f'Migrated: {payment.substract_account_id.name}',
        'sequence': 10,
    })
    
    print(f"Migrated payment {payment.id}")

env.cr.commit()
print("Migration complete!")
```

### 4. Verify the Migration

After migration, verify:

1. Check a few payments that had deductions
2. Verify the deduction lines are created correctly
3. Check that totals match (amount_substract should equal sum of deduction lines)
4. Test creating new payments with multiple deductions

### 5. Update Custom Code (if any)

If you have custom code that references the old fields:

**Old code:**
```python
payment.amount_substract = 100.0
payment.substract_account_id = account.id
```

**New code:**
```python
env['payment.deduction.line'].create({
    'payment_id': payment.id,
    'amount_substract': 100.0,
    'substract_account_id': account.id,
    'name': 'Withholding Tax',
})
```

**Reading deductions:**

Old:
```python
if payment.amount_substract > 0:
    account = payment.substract_account_id
```

New:
```python
if payment.amount_substract > 0:  # Still works (computed field)
    for deduction in payment.deduction_line_ids:
        account = deduction.substract_account_id
        amount = deduction.amount_substract
```

## Testing After Upgrade

1. **Create a new payment with multiple deductions:**
   - Amount: 1000
   - Deduction 1: Tax - 100
   - Deduction 2: Fee - 50
   - Verify final amount: 850

2. **Post the payment and check journal entry:**
   - Payable: Debit 850
   - Tax Account: Debit 100
   - Fee Account: Debit 50
   - Bank: Credit 1000

3. **Test batch payments:**
   - Create batch payment
   - Add line with multiple deductions
   - Generate payment
   - Verify deductions transferred correctly

## Rollback (if needed)

If you need to rollback:

1. Restore database backup:
```bash
psql your_database < backup_before_v2_upgrade.sql
```

2. Reinstall v1.x of the module

## Support

For issues or questions about the upgrade, contact the module maintainer.

## Compatibility

- **Odoo Version:** 17.0
- **Breaking Changes:** Yes (database schema and API changes)
- **Backward Compatible:** No (requires migration)