# Phase 13 — Documents, alerts and notifications

Phase 13 adds airline-scoped centralized document control, immutable document versions, operational alert synchronization, alert lifecycle management, notification preferences, complete in-app delivery, and modular provider boundaries for future email, SMS, and WhatsApp transports.

## Files created

- `database/migrations/2026_07_19_000014_create_documents_alerts_notifications_tables.php`
- `database/seeders/DocumentsAlertsSeeder.php`
- `app/Modules/Documents/Repositories/DocumentAlertRepository.php`
- `app/Modules/Documents/Services/DocumentAlertService.php`
- `app/Modules/Documents/Controllers/DocumentAlertController.php`
- `app/Shared/Notifications/NotificationProvider.php`
- `app/Shared/Notifications/InAppNotificationProvider.php`
- `app/Shared/Notifications/EmailNotificationProvider.php`
- `app/Shared/Notifications/SmsNotificationProvider.php`
- `app/Shared/Notifications/WhatsAppNotificationProvider.php`
- `resources/views/documents/index.php`
- `resources/views/documents/show.php`
- `resources/views/alerts/index.php`
- `resources/views/alerts/notifications.php`
- `docs/PHASE_13_IMPLEMENTATION.md`

## Files modified

- `routes/web.php`
- `database/seeders/RolesAndPermissionsSeeder.php`
- `resources/views/layouts/app.php`
- `tests/run.php`
- `README.md`

## Database migrations added

Migration `2026_07_19_000014` creates `document_categories`, `documents`, `document_versions`, `document_links`, `alert_rules`, `alerts`, `notification_templates`, `notification_preferences`, `notifications`, and `notification_deliveries`.

The seeder adds six document categories, the sixteen requested cross-module alert rules, and an in-app notification template for each alert type and airline.

## Security controls added

- Separate server-side permissions for document viewing, management and approval; alert viewing, management and rule administration; and notification preferences.
- CSRF protection on every Phase 13 mutation.
- Airline ownership validation for document owners and links across aircraft, employees, crew, vendors, work orders, flights, routes, and airports.
- Private file storage, permission-checked downloads, canonical-path confinement, MIME validation, safe filenames, checksums, and `nosniff` download responses.
- Immutable document version records with explicit approval and supersession instead of overwriting approved content.
- Backend validation for dates, version labels, categories, severities, ownership, assignments, resolution notes, preferences, and delivery channels.
- Alert fingerprints prevent duplicate operational alerts; configured warning windows and enabled rules are enforced server-side.
- Acknowledgement, resolution, assignment, rule changes, preference changes, synchronization, and automatic resolution are audited. Status transitions are retained in the shared status history.
- Notification delivery attempts are recorded independently from notifications.

## Tests performed

- PHP syntax validation for the Phase 13 service and repository.
- `php tests/run.php`: **51 passed, 0 failed**.
- Verified immutable document versions, approval and supersession, multi-record links, ownership boundaries, audit and status histories, cross-module alert collection, rule windows, deduplication, lifecycle actions, automatic resolution, immediate in-app delivery, daily in-app summaries, delivery records, preferences, protected routes, and all alert-center views.
- Attempted `php cli migrate:status`; the workspace has no reachable configured MySQL connection, so the migration could not be executed against MySQL here.

## Remaining known limitations

- Email, SMS, and WhatsApp provider interfaces are implemented, but external credentials and transports are intentionally not configured in this phase.
- Alert synchronization and daily-summary generation must be invoked by the protected synchronization action or a deployment scheduler; no background worker is bundled.
- Central document links use validated record type and ID references because one polymorphic foreign key cannot enforce all target tables at the database level.
- Existing module-specific uploaded documents remain available in their original modules; Phase 13 does not destructively migrate or remove those records.
- MySQL migration execution remains pending until a reachable MySQL 8 database is configured.