---
phase: 03-job-management-core
plan: 03
subsystem: notifications
tags: [email, admin-notification, wp-mail, post-transitions]

# Dependency graph
requires:
  - phase: 03-job-management-core
    provides: [job submission form creating pending posts]
provides:
  - admin-job-notification
  - transition-post-status-pattern
affects: [03-05]

# Tech tracking
tech-stack:
  added: []
  patterns: [transition-post-status-hook, wp-mail-notifications]

key-files:
  created: [includes/class-notifications.php]
  modified: [includes/class-ddhh-job-manager.php, ddhh-job-manager.php]

key-decisions:
  - "Used transition_post_status to detect only initial pending submissions, avoiding spam on updates"
  - "Email sent to admin_email option (WordPress site admin)"
  - "Email includes direct edit link for quick access to moderation"
  - "Error logging for wp_mail failures (common in Local WP dev)"

patterns-established:
  - "Notification pattern: Hook transition_post_status with status guards to trigger on state changes only"
  - "Email content: German text with job details and admin action links"

issues-created: []

# Metrics
duration: 8min
completed: 2026-01-14
---

# Phase 3 Plan 3: Admin Notifications Summary

**German email notification to admin on new job submission with title, provider, location, type, and edit link**

## Performance

- **Duration:** 8 min
- **Started:** 2026-01-14T11:00:00Z
- **Completed:** 2026-01-14T11:08:00Z
- **Tasks:** 2
- **Files modified:** 3

## Accomplishments

- Created automated email notification system for new job submissions
- Email sent to site admin immediately when provider submits job for moderation
- Email includes complete job context: title, author, organization, location, type, submission date
- Direct edit link enables one-click access to moderation interface
- Smart triggering prevents spam on post updates (only new → pending transitions)
- Error logging for debugging email issues in Local WP environment

## Task Commits

Each task was committed atomically:

1. **Task 1: Create notification class with admin alert on job submission** - `7aeecae` (feat)
2. **Task 2: Integrate notifications into plugin initialization** - `943544e` (feat)

## Files Created/Modified

- `includes/class-notifications.php` - DDHH_JM_Notifications class with setup_hooks() and send_admin_new_job_notification() method; hooks transition_post_status with guards for job_offer + new pending status; sends German email via wp_mail() with job details and edit link; logs errors if wp_mail fails
- `includes/class-ddhh-job-manager.php` - Added init action hook for DDHH_JM_Notifications::setup_hooks() following existing pattern (matches Access_Control, Dashboard, etc.)
- `ddhh-job-manager.php` - Added require_once for class-notifications.php

## Email Template

The email sent to admin includes:

**Subject:** Neues Stellenangebot zur Prüfung: {job_title}

**Body:**
```
Ein neues Stellenangebot wurde eingereicht und wartet auf Ihre Prüfung.

Titel: {job_title}
Anbieter: {author_name} ({author_organization})
Standort: {job_location}
Art: {job_type}
Eingereicht am: {submission_date}

Prüfen Sie das Stellenangebot hier:
{edit_link}

---
Diese E-Mail wurde automatisch gesendet.
```

## Technical Details

**Hook Implementation:**
- Hook: `transition_post_status` with priority 10, accepts 3 params ($new_status, $old_status, $post)
- Guards: Only trigger when post_type === 'job_offer' AND new_status === 'pending' AND old_status !== 'pending'
- This prevents email spam when admins save/update pending posts

**Data Extraction:**
- Admin email: `get_option('admin_email')`
- Author org: `get_user_meta($post->post_author, 'ddhh_org_name', true)`
- ACF fields: `get_field('job_location')`, `get_field('job_type')`
- Date: `get_the_date('d.m.Y H:i', $post_id)`
- Edit link: `get_edit_post_link($post_id, '')`

**Email Sending:**
- Function: `wp_mail()`
- Headers: 'Content-Type: text/html; charset=UTF-8'
- Body: Plain text converted to HTML with `nl2br(esc_html())`
- Error handling: Logs to error_log if wp_mail() returns false

## Decisions Made

**transition_post_status vs save_post:** Used transition_post_status because it provides old and new status, enabling precise detection of initial pending submission vs subsequent updates. This prevents duplicate notifications when admins edit pending posts.

**Error logging strategy:** wp_mail() can fail silently in Local WP environments where email is disabled. Added error_log() calls for both missing admin_email and wp_mail() failures so developers can see what's happening during testing.

**Email format:** Used plain text with nl2br() conversion rather than HTML templates. Simpler, more reliable across email clients, and sufficient for admin notification use case.

**Edit link priority:** Made edit link prominent in email (separate line with clear call-to-action text) because quick access to moderation is the primary admin need when notified.

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered

None - implementation proceeded smoothly. wp_mail() and transition_post_status are well-documented WordPress core functions with established patterns.

## Next Phase Readiness

Ready for 03-04 (admin UI enhancements) and 03-05 (job deactivation). Admin notification system is functional and will trigger whenever providers submit new jobs. The notification provides all context needed for efficient moderation workflow.

---
*Phase: 03-job-management-core*
*Completed: 2026-01-14*