# Feature Test Scenario Guide: Construction Project Financials & Timeline Fixes

## 1. Feature Overview
This update refactors the construction project financial calculations, fixes timeline mapping bugs, automates actual dates tracking, and implements daily penalty calculations for delayed items.

## 2. Technical Changes
- **Database**: Added `actual_start_date`, `actual_end_date`, and `penalty_amount` to `item_phases`.
- **Observer**: `ItemPhaseObserver` now tracks status transitions to record actual dates.
- **Service**: `ContractorInvoiceService` now enforces contract-defined rates (VAT, Retention) and unit prices.
- **Service**: `ItemService` progress report now includes penalty data and relaxed project filters.
- **Command**: `items:update-status` now runs daily to recalculate delays and penalties.

## 3. Test Scenarios

### Scenario 1: Invoice Financial Accuracy
**Pre-conditions**: A contract exists with specific `vat_percentage` and `retention_percentage`.
**Steps**:
1. Create a contractor invoice for items linked to this contract.
2. Verify that `gross_amount` matches (contract_unit_price * quantity).
3. Verify that `tax_value` is calculated using `contract.vat_percentage`.
4. Verify that `retention_amount` is calculated from the gross amount using `contract.retention_percentage`.
5. Verify that `net_amount` (amount_due) correctly subtracts retention and advance payment.

### Scenario 2: Timeline Mapping & Actual Dates
**Pre-conditions**: An item has `planned_start_date` and `planned_end_date` null, but `start_date` and `end_date` populated.
**Steps**:
1. Call `/project/{id}/timeline`.
2. Verify `planned_start_date` and `planned_end_date` in the response are populated from `start_date` and `end_date`.
3. Update item status to `in_progress`.
4. Verify `actual_start_date` is automatically set to today.
5. Update item status to `completed`.
6. Verify `actual_end_date` is set and `delay_days` is calculated correctly.

### Scenario 3: Daily Penalty Calculation
**Pre-conditions**: An item is `in_progress` and past its `planned_end_date`.
**Steps**:
1. Run `php artisan items:update-status`.
2. Verify `delay_days` incremented.
3. Verify `penalty_amount` calculated as (`delay_days` * `contract.penalty_per_day`).

### Scenario 4: Progress Report Visibility
**Pre-conditions**: A project exists with an approved cost estimate.
**Steps**:
1. Call `/project/items-progress-report`.
2. Verify the report is no longer empty.
3. Verify `penalty_amount`, `actual_start_date`, and `actual_end_date` are included for each item.

## 4. Manual Verification Checklist
- [ ] Run migrations: `php artisan migrate`
- [ ] Verify `item_phases` table schema.
- [ ] Test invoice creation via API.
- [ ] Check timeline endpoint response.
- [ ] Check progress report endpoint response.