ahmido
e15d80cca5
## Summary - implement Spec 224 findings notifications and escalation v1 on top of the existing alerts and Filament database notification infrastructure - add finding assignment, reopen, due soon, and overdue event handling with direct recipient routing, dedupe, and optional external alert fan-out - extend alert rule and alert delivery surfaces plus add the Spec 224 planning bundle and candidate-list promotion cleanup ## Validation - `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingsNotificationEventTest.php tests/Feature/Findings/FindingsNotificationRoutingTest.php` - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Alerts/FindingsAlertRuleIntegrationTest.php tests/Feature/Alerts/SlaDueAlertTest.php tests/Feature/Notifications/FindingNotificationLinkTest.php` ## Filament / Platform Notes - Livewire v4.0+ compliance is preserved - provider registration remains unchanged in `apps/platform/bootstrap/providers.php` - no globally searchable resource behavior changed in this feature - no new destructive action was introduced - asset strategy is unchanged and the existing `cd apps/platform && php artisan filament:assets` deploy step remains sufficient ## Manual Smoke Note - integrated-browser smoke testing confirmed the new alert rule event options, notification drawer entries, alert delivery history row, and tenant finding detail route on the active Sail host - local notification deep links currently resolve from `APP_URL`, so a local `localhost` vs `127.0.0.1:8081` host mismatch can break the browser session if the app is opened on a different host/port combination Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #261
106 lines
5.2 KiB
Markdown
106 lines
5.2 KiB
Markdown
# Quickstart: Findings Notifications & Escalation v1
|
||
|
||
## Prerequisites
|
||
|
||
1. Start the local platform stack.
|
||
|
||
```bash
|
||
cd apps/platform && ./vendor/bin/sail up -d
|
||
```
|
||
|
||
2. Work with a workspace that has at least one tenant, two tenant users, and existing findings data.
|
||
|
||
3. Ensure you can create or edit alert rules and inspect alert deliveries in the admin panel.
|
||
|
||
4. Remember that Filament database notification polling is intentionally disabled in this repo, so reload the page or reopen the notification drawer after each trigger when validating manually.
|
||
|
||
## Automated Validation
|
||
|
||
Run formatting and the narrowest proving suites for this feature:
|
||
|
||
```bash
|
||
cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
|
||
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingsNotificationEventTest.php tests/Feature/Findings/FindingsNotificationRoutingTest.php
|
||
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Alerts/FindingsAlertRuleIntegrationTest.php tests/Feature/Alerts/SlaDueAlertTest.php tests/Feature/Notifications/FindingNotificationLinkTest.php
|
||
```
|
||
|
||
## Manual Validation Flow
|
||
|
||
### 1. Confirm alert-rule event types are available
|
||
|
||
1. Open the admin panel alert-rule create or edit form.
|
||
2. Verify the event selector contains:
|
||
- `Finding assigned`
|
||
- `Finding reopened`
|
||
- `Finding due soon`
|
||
- `Finding overdue`
|
||
3. Save a rule that targets one of the new event types and confirm the Alert deliveries viewer can filter and label it correctly.
|
||
|
||
### 1b. Validate admin alert-surface RBAC semantics
|
||
|
||
1. As a workspace member with `ALERTS_VIEW` but without `ALERTS_MANAGE`, confirm the existing alert-rule and alert-delivery read surfaces open successfully while alert-rule mutation stays forbidden.
|
||
2. As an in-scope workspace member without `ALERTS_VIEW`, confirm the existing alert-rule and alert-delivery view surfaces return `403`.
|
||
3. As a non-member or wrong-workspace user, confirm the existing alert-rule and alert-delivery surfaces return `404`.
|
||
|
||
### 2. Validate direct assignment notification
|
||
|
||
1. Start with an open finding that has no assignee or a different assignee.
|
||
2. Assign the finding to a new entitled operator.
|
||
3. Reload the shell and open the database notification drawer.
|
||
4. Confirm the new assignee receives exactly one notification with:
|
||
- the finding vocabulary
|
||
- an explanation that the finding was assigned to them
|
||
- one `Open finding` action
|
||
5. Confirm owner-only changes, assignee clears, and no-op saves emit no assignment notification.
|
||
|
||
### 3. Validate automatic reopen notification
|
||
|
||
1. Start with a terminal finding that still has an assignee or owner.
|
||
2. Trigger the existing system path that reopens the finding through recurring detection.
|
||
3. Reload the shell and confirm one `Finding reopened` notification reaches the current assignee, or the current owner if no assignee exists.
|
||
4. Confirm manual reopen remains silent in v1.
|
||
|
||
### 4. Validate due-soon and overdue direct delivery
|
||
|
||
1. Prepare two open findings:
|
||
- one with `due_at` inside the next 24 hours
|
||
- one with `due_at` already in the past
|
||
2. Run the existing alert-evaluation command for the target workspace.
|
||
|
||
```bash
|
||
cd apps/platform && ./vendor/bin/sail artisan tenantpilot:alerts:dispatch --workspace=<workspace-id>
|
||
```
|
||
|
||
3. Reload the notification drawer.
|
||
4. Confirm:
|
||
- due soon goes to the current assignee, else the current owner
|
||
- overdue goes to the current owner, else the current assignee
|
||
- if owner and assignee are the same user, only one direct notification is created
|
||
5. Run the same command again without changing `due_at` or reopening the finding and confirm no duplicate due-soon or overdue direct notification is created for the current cycle.
|
||
6. Recalculate the due cycle through the existing lifecycle contract, then rerun evaluation and confirm one fresh due notification can emit for the new cycle.
|
||
|
||
### 5. Validate optional external copies through existing alert rules
|
||
|
||
1. Enable an alert rule for one of the new finding event types with a real destination.
|
||
2. Trigger the corresponding event again.
|
||
3. Confirm the direct responsible-user notification still appears.
|
||
4. Confirm one or more `Alert deliveries` rows are created only when a matching enabled rule exists.
|
||
5. Confirm the existing tenant-level aggregate `sla_due` alert behavior remains unchanged.
|
||
|
||
### 6. Validate entitlement-safe deep links
|
||
|
||
1. Create a direct finding notification for an entitled recipient.
|
||
2. Remove that user’s tenant membership or findings-view capability.
|
||
3. Open the notification action URL.
|
||
4. Confirm the existing route behavior remains authoritative:
|
||
- hidden tenant or record paths stay `404`
|
||
- in-scope but unauthorized access stays `403`
|
||
5. Confirm the notification title and body never broaden disclosure beyond the existing finding summary vocabulary.
|
||
|
||
## Reviewer Notes
|
||
|
||
- The feature is Livewire v4.0+ compatible and stays on existing Filament v5 primitives.
|
||
- Provider registration remains unchanged in `apps/platform/bootstrap/providers.php`.
|
||
- No globally searchable resource behavior changes in this feature.
|
||
- No new destructive action is introduced, so no new confirmation flow is required.
|
||
- Asset strategy is unchanged: no new panel or shared assets, and the existing deploy `filament:assets` step remains sufficient. |