﻿# ADR 0003 — Brand-Scoped Used-Battery Rate (T-B02, T-B05, T-B06)

Date: 2026-09-11
Status: Accepted
Refs: T-B02, T-B05, T-B06, EXECUTION_ROADMAP.md §4

## Context

The system originally used a single global `used_battery_rate` for all brands
when calculating the credit given to a customer who trades in a used battery.
This meant a premium brand (e.g., Varta) and a budget brand got the same rate,
which was incorrect and led to customer disputes.

## Decision

Used-battery rates are now **resolved per brand** via `BrandRateService::getUsedBatteryRate(int $brandId, ?int $productId)`.

Resolution order (from most to least specific):
1. Product-specific rate override (if exists in `brand_rate_overrides`)
2. Brand-level rate (from `brand_rates` table)
3. Global fallback rate (from `used_battery_rates` / `settings` table)

This logic is centralised exclusively in `BrandRateService`. SQL duplicates
that queried `used_battery_rates` directly were removed from `OrderRepository`,
`OrderCommandService`, `CartValidationService`, and `UsedBatteryControllerHandler`.

## Consequences

- `BrandRateService::getUsedBatteryRate()` must never be called with `$brandId = 0`
  except when intentionally requesting the global fallback.
- All three entry points (cart, order creation, used-battery intake) now produce
  consistent rates for the same brand/product.
- T-F08 verifies no stray SQL against `used_battery_rates` remains outside
  `BrandRateService` and `AdminUsedBatteryControllerHandler`.
