Story 1.15a.10: Notifications API Consolidation

PostgreSQL Instance: batbern (dev: batbern_development)
└── Schema: public (DEFAULT - no custom schemas)
    ├── companies (owned by company-user-management-service)
    ├── user_profiles (owned by company-user-management-service)
    ├── events (owned by event-management-service)
    ├── event_tasks (owned by event-management-service) ← Story 5.5
    ├── notifications (owned by event-management-service) ← THIS STORY
    └── ... (all tables in SAME schema)

-- ✅ CORRECT (ADR-003 compliant)
CREATE TABLE notifications (
    recipient_username VARCHAR(100) NOT NULL,  -- Meaningful ID
    event_code VARCHAR(50),                    -- Meaningful ID
    -- NO FOREIGN KEY to user_profiles(id)
    -- NO FOREIGN KEY to events(id)
);

-- ❌ WRONG (violates ADR-003)
CREATE TABLE notifications (
    user_id UUID REFERENCES user_profiles(id),  -- Cross-service FK
    event_id UUID REFERENCES events(id),        -- Within-service FK (acceptable)
);

# Notification Management (Event Management Service)
GET    /api/v1/notifications?username={}&status={}&page={}
GET    /api/v1/notifications/count?username={}&status={}
PUT    /api/v1/notifications/{id}/read
PUT    /api/v1/notifications/batch-read    # Bulk mark as read
DELETE /api/v1/notifications/{id}
DELETE /api/v1/notifications/batch-delete  # Bulk delete

# Delivery History (Event Management Service)
GET    /api/v1/notifications/history?username={}&channel={}

# Preferences (Company-User Management Service - EXISTING)
GET    /api/v1/users/me/preferences
PUT    /api/v1/users/me/preferences

-- Notifications table (follows Task System pattern)
CREATE TABLE IF NOT EXISTS notifications (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),

    -- ADR-003: Meaningful IDs (NOT foreign keys)
    recipient_username VARCHAR(100) NOT NULL,
    event_code VARCHAR(50),  -- Nullable (non-event notifications)

    -- Notification details
    notification_type VARCHAR(50) NOT NULL,  -- SPEAKER_INVITED, DEADLINE_WARNING, etc.
    channel VARCHAR(20) NOT NULL,            -- EMAIL, SMS, WEBHOOK
    priority VARCHAR(20) DEFAULT 'NORMAL',   -- LOW, NORMAL, HIGH, URGENT
    subject VARCHAR(255) NOT NULL,
    body TEXT NOT NULL,

    -- Delivery tracking
    status VARCHAR(20) NOT NULL DEFAULT 'PENDING',  -- PENDING, SENT, FAILED, READ
    sent_at TIMESTAMP,
    read_at TIMESTAMP,
    failed_at TIMESTAMP,
    failure_reason TEXT,

    -- Metadata
    metadata JSONB,  -- Flexible storage (task_id, speaker_id, etc.)

    -- Timestamps
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);

-- Indexes for performance
CREATE INDEX idx_notifications_recipient ON notifications(recipient_username);
CREATE INDEX idx_notifications_event ON notifications(event_code) WHERE event_code IS NOT NULL;
CREATE INDEX idx_notifications_status ON notifications(status);
CREATE INDEX idx_notifications_created ON notifications(created_at DESC);
CREATE INDEX idx_notifications_recipient_created ON notifications(recipient_username, created_at DESC);
CREATE INDEX idx_notifications_recipient_status ON notifications(recipient_username, status);

-- Comment for documentation
COMMENT ON TABLE notifications IS 'Notification delivery tracking (email/SMS audit trail). In-app notifications queried dynamically. Follows Task System pattern (Story 5.5). ADR-003 compliant (meaningful IDs).';

// When sending email, create audit trail record
notificationRepository.save(Notification.builder()
    .recipientUsername("john.doe")
    .eventCode("EVT-2024-Q1")
    .notificationType("EVENT_PUBLISHED")
    .channel("EMAIL")
    .subject("Event BATbern Q1 2024 is now published")
    .body("...")
    .status("PENDING")
    .build());

// Send via AWS SES
emailService.send(notification);

// Update status after delivery
notification.setStatus("SENT");
notification.setSentAt(Instant.now());
notificationRepository.save(notification);

// Don't create rows - query when user opens app
@GetMapping("/api/v1/notifications/in-app")
public List<InAppNotification> getInAppNotifications(@RequestParam String username) {
    // Find events published since user's last login
    Instant lastLogin = userService.getLastLogin(username);

    List<Event> newEvents = eventRepository.findPublishedAfter(lastLogin);

    // Convert to notifications on-the-fly
    return newEvents.stream()
        .map(event -> InAppNotification.builder()
            .type("EVENT_PUBLISHED")
            .title(event.getTitle() + " is now published")
            .eventCode(event.getEventCode())
            .createdAt(event.getPublishedAt())
            .build())
        .collect(Collectors.toList());
}

@Service
@RequiredArgsConstructor
public class NotificationService {

    @EventListener
    @Async
    public void onEventPublished(EventPublishedEvent event) {
        // Get all registered attendees
        List<String> attendees = registrationRepository
            .findUsernamesByEventId(event.getEventId());

        // Create email notifications (audit trail)
        for (String username : attendees) {
            createAndSendNotification(NotificationRequest.builder()
                .recipientUsername(username)
                .eventCode(event.getEventCode())
                .type("EVENT_PUBLISHED")
                .channel("EMAIL")
                .subject("Event " + event.getTitle() + " is now published")
                .body(buildEmailBody(event))
                .build());
        }
    }

    @EventListener
    @Async
    public void onTaskAssigned(TaskAssignedEvent event) {
        // Notify organizer of task assignment
        createAndSendNotification(NotificationRequest.builder()
            .recipientUsername(event.getAssignedUsername())
            .eventCode(event.getEventCode())
            .type("TASK_ASSIGNED")
            .channel("EMAIL")
            .subject("New task assigned: " + event.getTaskName())
            .metadata(Map.of("taskId", event.getTaskId()))
            .build());
    }

    @Transactional
    public void createAndSendNotification(NotificationRequest request) {
        // Check user preferences (via HTTP call to User Service)
        UserPreferences prefs = userServiceClient
            .getPreferences(request.getRecipientUsername());

        if (!shouldSend(prefs, request)) {
            return;  // Skip if user opted out or in quiet hours
        }

        // Create notification record
        Notification notification = notificationRepository.save(
            toEntity(request)
        );

        // Send asynchronously
        notificationSender.sendAsync(notification);
    }
}

@RestController
@RequestMapping("/api/v1/notifications")
@RequiredArgsConstructor
public class NotificationController {

    @GetMapping
    public Page<NotificationResponse> listNotifications(
        @RequestParam String username,
        @RequestParam(required = false) String status,
        Pageable pageable
    ) {
        // Query notifications for user
        Page<Notification> notifications = status != null
            ? notificationRepository.findByRecipientUsernameAndStatus(username, status, pageable)
            : notificationRepository.findByRecipientUsername(username, pageable);

        // Enrich with event/user details via HTTP clients (if needed)
        return notifications.map(this::toResponse);
    }

    @GetMapping("/count")
    public NotificationCountResponse getUnreadCount(
        @RequestParam String username,
        @RequestParam(defaultValue = "unread") String status
    ) {
        long count = notificationRepository.countByRecipientUsernameAndStatus(username, status);
        return NotificationCountResponse.builder().count(count).build();
    }

    @PutMapping("/{id}/read")
    public void markAsRead(@PathVariable UUID id) {
        Notification notification = notificationRepository.findById(id)
            .orElseThrow(() -> new EntityNotFoundException("Notification not found"));

        notification.setStatus("READ");
        notification.setReadAt(Instant.now());
        notificationRepository.save(notification);
    }
}

// When task assigned, create notification
@EventListener
public void onTaskAssigned(TaskAssignedEvent event) {
    notificationService.createNotification(
        recipient: event.getAssignedUsername(),
        type: "TASK_ASSIGNED",
        title: "New task: " + event.getTaskName(),
        metadata: {taskId: event.getTaskId()}
    );
}

// When deadline approaching, create notification
@Scheduled(cron = "0 0 9 * * *")  // Daily at 9 AM
public void checkDeadlines() {
    List<EventTask> upcomingTasks = taskRepository.findDueSoon(3);  // Due in 3 days

    for (EventTask task : upcomingTasks) {
        notificationService.createNotification(
            recipient: task.getAssignedOrganizerUsername(),
            type: "DEADLINE_WARNING",
            title: "Task due soon: " + task.getTaskName(),
            priority: "HIGH"
        );
    }
}