some progress

2026-01-24 12:16:10 +02:00
parent 3665a1d5a3
commit 612cc097f8
51 changed files with 8089 additions and 470 deletions
@@ -0,0 +1,328 @@
+# Multi-Channel Notifications - Quick Start Guide
+
+## What's Been Completed
+
+### ✅ Database Migration
+- Migration created: `database/migrations/2026_01_18_123539_add_notification_channels_to_users_table.php`
+- Adds fields for all notification channels to users table
+- **Run with:** `./vendor/bin/sail artisan migrate`
+
+### ✅ Packages Installed
+```json
+"laravel/slack-notification-channel": "^3.7",
+"laravel-notification-channels/telegram": "^6.0",
+"laravel-notification-channels/discord": "^1.7"
+```
+
+### ✅ User Model Updated
+- Added fillable fields for all notification channels
+- Added `notification_channels` JSON cast
+- Added helper methods:
+  - `getNotificationChannelsFor($alertType)` - Get enabled channels for an alert type
+  - `routeNotificationForSlack()` - Slack webhook routing
+  - `routeNotificationForTelegram()` - Telegram chat ID routing
+  - `routeNotificationForDiscord()` - Discord webhook routing
+
+## Quick Implementation Steps
+
+### Step 1: Run Migration
+```bash
+./vendor/bin/sail artisan migrate
+```
+
+### Step 2: Create Notification Classes
+
+All notification class templates are in `MULTI_CHANNEL_NOTIFICATIONS_GUIDE.md`. Copy them to:
+- `app/Notifications/MonitorAlert.php` (base class)
+- `app/Notifications/UptimeAlert.php`
+- `app/Notifications/SslExpiryAlert.php`
+- `app/Notifications/DomainExpiryAlert.php`
+- `app/Notifications/SitemapAlert.php`
+- `app/Notifications/PerformanceAlert.php`
+
+### Step 3: Create Notification Settings Controller
+
+```bash
+./vendor/bin/sail artisan make:controller NotificationSettingsController
+```
+
+### Step 4: Update Existing Jobs
+
+Example - Update `CheckSitemap` job:
+
+```php
+// Replace the sendAlert method in app/Jobs/CheckSitemap.php
+use App\Notifications\SitemapAlert;
+
+protected function sendAlert(string $message): void
+{
+    // Send via new notification system
+    $this->sitemap->site->user->notify(
+        new SitemapAlert(
+            $this->sitemap->site->name,
+            $this->sitemap->url,
+            $this->sitemap->last_error
+        )
+    );
+}
+```
+
+### Step 5: Add Environment Variables
+
+Add to `.env`:
+```env
+# Telegram Bot (optional)
+TELEGRAM_BOT_TOKEN=your_bot_token
+
+# Twilio SMS (optional)
+TWILIO_SID=your_sid
+TWILIO_TOKEN=your_token
+TWILIO_FROM=+1234567890
+```
+
+## Default Notification Channels Structure
+
+The `notification_channels` JSON field stores preferences like this:
+
+```json
+{
+  "uptime": ["email", "slack"],
+  "ssl": ["email", "telegram", "slack"],
+  "domain_expiry": ["email"],
+  "sitemap": ["database"],
+  "performance": ["slack"],
+  "dns": ["email", "database"],
+  "broken_links": ["database"],
+  "health_check": ["email", "slack"],
+  "tcp_port": ["database"]
+}
+```
+
+## Supported Channels
+
+### Built-in (No Additional Setup)
+- `mail` - Email notifications
+- `database` - Store in notifications table
+
+### Webhook-based (Requires URL)
+- `slack` - Requires `slack_webhook_url`
+- `discord` - Requires `discord_webhook_url`
+- `telegram` - Requires `telegram_chat_id` and bot token
+- `teams` - Requires `teams_webhook_url`
+- `google_chat` - Requires `google_chat_webhook_url`
+- `webhook` - Requires `webhook_url` (custom endpoint)
+
+### API-based (Requires Credentials)
+- `sms` - Requires Twilio/Vonage setup
+- `opsgenie` - Requires `opsgenie_api_key`
+- `pagerduty` - Requires `pagerduty_integration_key`
+
+## Testing Notifications
+
+Create a test route to verify notifications work:
+
+```php
+// In routes/web.php
+Route::get('/test-notification', function () {
+    auth()->user()->notify(
+        new \App\Notifications\UptimeAlert(
+            'Test Site',
+            false, // not down
+            200,
+            'https://example.com',
+            150.5
+        )
+    );
+
+    return 'Notification sent! Check your configured channels.';
+})->middleware('auth');
+```
+
+## Setting Up Notification Channels
+
+### Slack
+1. Go to https://api.slack.com/messaging/webhooks
+2. Create an Incoming Webhook for your workspace
+3. Copy the webhook URL
+4. Save in user settings: `slack_webhook_url`
+
+### Telegram
+1. Talk to @BotFather on Telegram
+2. Create a new bot with `/newbot`
+3. Save the bot token to `.env` as `TELEGRAM_BOT_TOKEN`
+4. Start a chat with your bot
+5. Get your chat ID from @userinfobot
+6. Save in user settings: `telegram_chat_id`
+
+### Discord
+1. Go to Server Settings → Integrations → Webhooks
+2. Create New Webhook
+3. Copy the Webhook URL
+4. Save in user settings: `discord_webhook_url`
+
+### Microsoft Teams
+1. In Teams, go to channel → Connectors
+2. Configure "Incoming Webhook"
+3. Copy the webhook URL
+4. Save in user settings: `teams_webhook_url`
+
+## Notification Settings UI (To Be Created)
+
+Create a settings page where users can:
+1. Enable/disable channels per alert type
+2. Configure webhook URLs and API keys
+3. Test notification delivery
+4. Set quiet hours
+5. Configure notification preferences
+
+## Integration with Existing Monitoring
+
+Update these jobs to send notifications:
+- `app/Jobs/CheckSitePing.php` → Use `UptimeAlert`
+- `app/Jobs/CheckSslCertificate.php` → Use `SslExpiryAlert`
+- `app/Jobs/CheckDomainExpiry.php` → Use `DomainExpiryAlert`
+- `app/Jobs/CheckSitemap.php` → Use `SitemapAlert`
+- `app/Jobs/CheckHealth.php` → Use `PerformanceAlert`
+
+## Queue Configuration
+
+Notifications are queued by default. Ensure queue worker is running:
+
+```bash
+./vendor/bin/sail artisan queue:work
+```
+
+Or configure supervisor in production.
+
+## Notification Flow
+
+```
+Monitor Job Detects Issue
+       ↓
+Creates Notification Object
+       ↓
+User::notify(new Alert(...))
+       ↓
+Laravel checks via()
+       ↓
+Gets enabled channels from user preferences
+       ↓
+Dispatches to each channel
+       ↓
+Queues notification jobs
+       ↓
+Worker processes notifications
+       ↓
+Sends to: Email, Slack, Telegram, etc.
+```
+
+## Security Considerations
+
+1. **Encrypt sensitive fields** - Consider encrypting webhook URLs and API keys
+2. **Rate limiting** - Prevent notification spam
+3. **Validate webhooks** - Verify webhook URLs before saving
+4. **Sanitize data** - Clean user input in notifications
+5. **HTTPS only** - Only allow HTTPS webhook URLs
+
+## Troubleshooting
+
+### Notifications not sending
+1. Check queue worker is running: `ps aux | grep queue`
+2. Check failed jobs: `./vendor/bin/sail artisan queue:failed`
+3. Review logs: `storage/logs/laravel.log`
+4. Verify user has configured channels
+5. Test with simple email notification first
+
+### Channel-specific issues
+
+**Slack:** "Invalid webhook URL"
+- Verify URL format: https://hooks.slack.com/services/...
+- Check workspace hasn't revoked webhook
+
+**Telegram:** "Bad Request: chat not found"
+- Verify chat ID is correct
+- Ensure bot token is valid
+- Start conversation with bot first
+
+**Discord:** "Webhook not found"
+- Check webhook wasn't deleted
+- Verify URL hasn't expired
+
+## Performance Tips
+
+1. **Use queues** - Always queue notifications
+2. **Batch similar alerts** - Group notifications when possible
+3. **Debounce** - Prevent rapid repeated notifications
+4. **Cache user preferences** - Cache notification_channels
+5. **Async webhooks** - Don't wait for webhook responses
+
+## Next Steps
+
+1. **Create UI** - Build notification settings interface
+2. **Add more channels** - Implement Teams, Google Chat, etc.
+3. **Test thoroughly** - Test each channel
+4. **Update docs** - Document for your team
+5. **Monitor** - Track notification success rates
+
+## Example: Full Integration
+
+Here's how to fully integrate with an existing job:
+
+```php
+<?php
+
+namespace App\Jobs;
+
+use App\Models\Site;
+use App\Notifications\UptimeAlert;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\Http;
+
+class CheckSiteUptime implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public function __construct(
+        public Site $site
+    ) {
+    }
+
+    public function handle(): void
+    {
+        $response = Http::timeout(10)->get($this->site->url);
+
+        $isDown = !$response->successful();
+        $statusCode = $response->status();
+        $responseTime = $response->transferStats->getTransferTime() * 1000;
+
+        // Check if status changed
+        $previousStatus = $this->site->latestUptimeCheck->is_online ?? true;
+
+        // Send notification if status changed
+        if ($isDown !== !$previousStatus) {
+            $this->site->user->notify(
+                new UptimeAlert(
+                    $this->site->name,
+                    $isDown,
+                    $statusCode,
+                    $this->site->url,
+                    $responseTime
+                )
+            );
+        }
+
+        // Save check result...
+    }
+}
+```
+
+## Resources
+
+- Laravel Notifications: https://laravel.com/docs/notifications
+- Slack API: https://api.slack.com/
+- Telegram Bot API: https://core.telegram.org/bots/api
+- Discord Webhooks: https://discord.com/developers/docs/resources/webhook