<?php

namespace App\Notifications;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Notifications\Notification as BaseNotification;

/**
 * Base for every event-class notification in this app.
 *
 * Each concrete event encapsulates: who's the audience (admins-shared /
 * direct-recipient / customers / everyone), what category (info / alert /
 * action), what severity (info / success / warning / error), whether to
 * dedupe (groupKey), what subject it points at (Invoice / Campaign / ...),
 * and the data payload rendered into the UI (title / body / action).
 *
 * Dispatch is via App\Services\Notifications\Notifier, NOT $user->notify().
 * Notifier inspects audience() and routes to either the shared path (1 row,
 * notifiable_type/id null, audience='admins') or the direct path (1 row per
 * recipient via the Notifiable trait + AppDatabaseChannel).
 */
abstract class AppNotification extends BaseNotification
{
    public const AUDIENCE_DIRECT    = 'direct';
    public const AUDIENCE_ADMINS    = 'admins';
    public const AUDIENCE_CUSTOMERS = 'customers';
    public const AUDIENCE_EVERYONE  = 'everyone';

    public const CATEGORY_INFO   = 'info';
    public const CATEGORY_ALERT  = 'alert';
    public const CATEGORY_ACTION = 'action';

    public const SEVERITY_INFO    = 'info';
    public const SEVERITY_SUCCESS = 'success';
    public const SEVERITY_WARNING = 'warning';
    public const SEVERITY_ERROR   = 'error';

    abstract public function audience(): string;
    abstract public function category(): string;
    abstract public function severity(): string;

    /**
     * Stable identifier collapsing repeated occurrences of the same logical
     * event (per recipient when direct, per audience when shared). Return null
     * to disable dedupe.
     *
     * Convention: `<event-key>:<subject-id>` — e.g. `invoice-claim:42`,
     * `geoip-setup`, `plugin-load:athena/evs`.
     */
    public function groupKey(): ?string
    {
        return null;
    }

    /**
     * Optional source object the notification points at (Invoice, Campaign,
     * Customer, ...). Stored polymorphically as subject_type/id so we can
     * later query "all notifications about invoice X" or cascade-dismiss when
     * a subject is resolved.
     */
    public function subject(): ?Model
    {
        return null;
    }

    /**
     * Channels — direct path (audience='direct') flows through the database
     * channel via Notifiable; shared path is INSERT'd by Notifier directly,
     * so via() on shared events is unused (kept for symmetry).
     */
    public function via(object $notifiable): array
    {
        return ['database'];
    }

    /**
     * Render the data payload stored in `notifications.data`.
     *
     * Shape: {title, body, action?: {label, route, params}, meta?}
     *
     * `action.route` is a Laravel route NAME (not a URL) — resolved at view
     * time by App\Model\AppNotification::actionUrl(). This keeps notification
     * rows portable across URL prefix changes.
     */
    abstract public function toArray(object $notifiable = null): array;
}