# Database & Schema Discipline

## Rules

- **Never modify existing migrations.** Always create a new migration for schema changes.
- **Every migration must be reversible.** Implement `down()` correctly.
- **Foreign keys must specify `onDelete` behavior** — usually `cascade` or `set null`.
- **Every new feature table must include `co_host_id` or `user_id`** for multi-tenancy scoping.
- **Use `SoftDeletes`** on models where data should be recoverable (reservations, properties, clients).

## Migration File Naming

```
YYYY_MM_DD_HHMMSS_<verb>_<table>_<description>.php

# Examples:
2024_01_15_120000_add_internal_name_to_properties_table.php
2024_02_01_090000_create_reclamations_table.php
```

## If a Migration Fails

1. Do NOT delete the migration file.
2. Roll back: `php artisan migrate:rollback`
3. Fix the migration, then re-run: `php artisan migrate`
4. Dev only (corrupt DB): `php artisan migrate:fresh --seed`

## Critical Models

| Model | Table | Key Relationships |
|---|---|---|
| `User` | `users` | hasMany(Property), hasMany(Reservation), belongsToMany(Role) |
| `Property` | `properties` | belongsTo(User), hasMany(Reservation), hasMany(PropertyBlock) |
| `Reservation` | `reservations` | belongsTo(Property), belongsTo(Client), hasMany(Recovery) |
| `Client` | `clients` | hasMany(Reservation) |
| `Recovery` | `recoveries` | belongsTo(Reservation) |
| `OnboardingFolder` | `onboarding_folders` | belongsTo(Property), hasMany(FolderEvent), belongsTo(OnboardingStatus) |

## Observers (Side Effects)

`OnboardingFolderObserver` and `FolderEventObserver` run automatically on create/update. Be aware of side effects when touching those models.