# Owner Revenue Backend Fixes — Design

## Goal
Close the backend gaps identified in the owner-revenue review so the API returns consistent, complete data and supports the deferred features that require BE work.

## Scope
Backend-only changes inside this Laravel API repo. Frontend concerns (UI notes, `formatCurrency`, nav hiding) remain out of scope because no frontend layer exists here.

## Changes

### 1. Type consistency — cast all monetary amounts to numbers
`Transaction` and `Invoice` models cast decimal columns as strings. `RevenueController` already casts summary/chart totals to `float`, but `TransactionResource` and `InvoiceResource` return strings.

**Fix:** Cast every monetary field in `TransactionResource` and `InvoiceResource` to `float` so consumers receive numbers consistently.

### 2. Currency code on revenue responses
The API returns amounts with no currency.

**Fix:**
- Add `currency()` relation to `Building`.
- Eager-load `invoice.reservation.unit.building.currency` in revenue queries.
- Include `currency_code` in:
  - Summary top-level response.
  - Chart top-level response.
  - Each ledger row.
  - Each row in `by-building` and `by-unit` reports.
- Currency is resolved from the filtered building when `building_id` is provided, otherwise from the owner’s first building that has a currency. If buildings use mixed currencies, `currency_code` is `null`.

### 3. Employee `revenue.view` permission
Revenue routes currently live under `role:owner`, so employees always get 403.

**Fix:**
- Add `'revenue' => 'Revenue'` to `config/permissions.php` resources so `PermissionCatalog` generates `revenue.view`.
- Move revenue routes to the shared `role:owner|employee` group.
- In `RevenueController`, authorize each action:
  - Owner: always allowed.
  - Employee: allowed only if active, has `revenue.view`, and the requested building(s) are in their assigned buildings.
- Scope every revenue query to the employee’s assigned building IDs when the caller is an employee.

### 4. Revenue by building
**New endpoint:** `GET /api/v1/owner/revenue/by-building`

Returns one row per building owned by (or assigned to) the caller:
```json
{
  "data": [
    {
      "building_id": 1,
      "building_name": "...",
      "collected": 500.0,
      "refunds": 50.0,
      "net": 450.0,
      "outstanding": 100.0,
      "transactions_count": 5,
      "currency_code": "USD"
    }
  ]
}
```
Outstanding is computed from `invoices.remaining_amount` filtered by the same date/building scope as the transaction totals.

### 5. Revenue by unit
**New endpoint:** `GET /api/v1/owner/revenue/by-unit?building_id=...`

Returns one row per unit, optionally filtered by `building_id`:
```json
{
  "data": [
    {
      "unit_id": 1,
      "unit_name": "...",
      "building_id": 1,
      "building_name": "...",
      "collected": 500.0,
      "refunds": 50.0,
      "net": 450.0,
      "outstanding": 100.0,
      "transactions_count": 5,
      "currency_code": "USD"
    }
  ]
}
```

### 6. Chart aggregation (week/month/year)
**New query parameter:** `group_by` on `GET /api/v1/owner/revenue/chart`
- Allowed values: `day`, `week`, `month`, `year`.
- Default: `day`.
- SQL date bucketing changes per database driver (sqlite/pgsql/mysql) to match the existing daily implementation.

### 7. Customer/building/unit on ledger rows
**Fix:** Create a dedicated `RevenueTransactionResource` used only by the revenue ledger endpoint. It includes:
- transaction fields (with `amount` as `float`)
- `customer`: `{ id, name }` from `invoice.reservation.customer`
- `building`: `{ id, name }` from `invoice.reservation.unit.building`
- `unit`: `{ id, name_or_number }` from `invoice.reservation.unit`
- `currency_code`

## Files to change
- `app/Http/Resources/TransactionResource.php`
- `app/Http/Resources/InvoiceResource.php`
- `app/Http/Resources/RevenueTransactionResource.php` (new)
- `app/Models/Building.php`
- `app/Http/Controllers/Api/Owner/RevenueController.php`
- `app/Http/Requests/Owner/IndexRevenueRequest.php`
- `app/Services/Filter/FilterService.php`
- `config/permissions.php`
- `routes/api.php`
- `tests/Feature/Owner/RevenueTest.php`

## Testing
- Add/update tests for amount type casting.
- Add tests for currency code presence.
- Add employee-access tests (with and without `revenue.view`, with building scoping).
- Add tests for `by-building`, `by-unit`, and chart `group_by`.
- Add tests for customer/building/unit fields in ledger.
- Run the full `RevenueTest.php` suite and confirm all pass.