# Building & Unit Photo Handling Design

## Overview

Add photo persistence to the existing `BuildingController` and `UnitController` using Spatie Media Library, which both models already implement.

## Goals

- Save uploaded photos when creating a building or unit.
- Replace all existing photos when updating a building or unit.
- Provide append-only endpoints to add more photos without removing existing ones.
- Keep changes inline in the existing controllers (Approach A).

## Current State

- `Building` and `Unit` models implement `HasMedia` via `InteractsWithMedia`.
- Both models register a media collection named `documents`.
- `BuildingRequest` and `UnitRequest` already validate `photos` as an array of images.
- Controllers create/update models but never touch the `photos` input.

## Design

### 1. Store Behavior

In `BuildingController::store()` and `UnitController::store()`:

1. Create the model as today.
2. Iterate over `$request->file('photos')`.
3. Add each file to the model’s `documents` collection using `$model->addMedia(...)->toMediaCollection('documents')`.

### 2. Update Behavior

In `BuildingController::update()` and `UnitController::update()`:

1. Clear the existing `documents` collection with `$model->clearMediaCollection('documents')`.
2. Update model fields as today.
3. Add the new photos to the `documents` collection.

### 3. Append Endpoints

Add new controller methods and routes:

- `POST /buildings/{building}/photos`
- `POST /units/{unit}/photos`

Each endpoint:

1. Validates `photos` as a required array of images (same rules as store/update).
2. Appends each uploaded file to the `documents` collection without clearing existing media.
3. Returns the updated resource.

### 4. Collection Mime Types

Align accepted mime types with request validation rules:

- `Building`: `image/jpeg`, `image/png`, `image/HEIF`, `image/jpg`
- `Unit`: `image/jpeg`, `image/png`

Keep the collection name as `documents` to avoid breaking any existing media records.

## Files to Modify

- `app/Http/Controllers/BuildingController.php`
- `app/Http/Controllers/UnitController.php`
- `app/Models/Building.php`
- `app/Models/Unit.php`
- `routes/api.php`

## Out of Scope

- Renaming the `documents` collection.
- Deleting individual photos by ID.
- Reordering photos.
- Changing existing request validation rules.