Digital-Dabei-Hamburg-Job-Manager/.planning/quick/002-fix-duplicate-mentor-notifications-on-jo/002-SUMMARY.md

phase, plan, subsystem, tags, requires, provides, affects, tech-stack, key-files, decisions, metrics

phase	plan	subsystem	tags	requires	provides	affects	tech-stack	key-files	decisions	metrics
quick-002	01	notifications	mentor-notifications duplicate-prevention post-meta bug-fix	05-01 05-03	Duplicate notification prevention using post meta One-time mentor notification guarantee per job		added patterns Post meta flags for one-time event tracking Idempotent notification scheduling	created modified includes/class-notifications.php	key context options chosen rationale Use post meta `_ddhh_mentors_notified` for duplicate prevention Need to track whether mentors have been notified for a specific job Post meta flag Custom database table Transient cache Post meta flag Simple, reliable, persists forever, underscore-prefix hides from UI key context options chosen rationale Set meta flag after scheduling, not after emails sent When to mark job as notified After scheduling batch After all emails sent Before scheduling After scheduling batch Scheduling is synchronous and reliable; email sending is async and could fail individually	duration completed 2 2026-01-29

Quick Task 002: Fix Duplicate Mentor Notifications

One-liner: Post meta guard prevents mentor re-notification on job republish after edits

What Was Built

Fixed a bug where mentors received duplicate "new job" notifications when a job was edited and republished.

The Problem: The job lifecycle includes a status reset to pending after provider edits (decision 03-02). This means:

1. Provider submits → pending
2. Admin publishes → pending to publish → mentors notified ✓
3. Provider edits → status reset to pending
4. Admin republishes → pending to publish → mentors notified AGAIN ✗

The existing guard if ( 'publish' === $old_status ) only prevented publish→publish transitions, not pending→publish after edits.

The Solution: Added a post meta flag _ddhh_mentors_notified that:

• Is checked before scheduling notifications (early return if already set)
• Is set after successful batch scheduling
• Persists for the lifetime of the job post
• Uses underscore prefix to hide from WordPress custom fields UI

Technical Implementation

Modified: includes/class-notifications.php

1. Pre-scheduling guard (after line 439):

   • get_post_meta( $post->ID, '_ddhh_mentors_notified', true )
   • If value is '1', log skip message and return early
   • Prevents duplicate scheduling entirely

2. Post-scheduling flag (after line 469):

   • update_post_meta( $post->ID, '_ddhh_mentors_notified', '1' )
   • Sets flag after schedule_mentor_notification_batch() succeeds
   • Ensures future republish attempts skip notification

Why after scheduling, not after sending?

• Scheduling is synchronous and happens immediately
• Email sending is async (Action Scheduler batches)
• Individual emails might fail, but we still don't want re-notifications
• The intent to notify has been recorded, which is what matters

Verification

Syntax Check:

php -l includes/class-notifications.php
# No syntax errors detected

Code Review:

• ✅ get_post_meta check exists before mentor query
• ✅ update_post_meta exists after scheduling
• ✅ No other notification methods modified
• ✅ Existing publish→publish guard preserved
• ✅ Underscore-prefixed meta key (hidden from UI)

Job Lifecycle Flow (After Fix)

1. Initial submission (pending):

   • No notification (job not published yet)
   • _ddhh_mentors_notified = not set

2. First publish (pending → publish):

   • ✅ Mentors notified
   • _ddhh_mentors_notified = '1'

3. Provider edits (publish → pending):

   • No notification (deactivation)
   • _ddhh_mentors_notified = still '1'

4. Republish after edit (pending → publish):

   • ❌ Mentors NOT notified (meta flag prevents it)
   • _ddhh_mentors_notified = still '1'

5. Any future republish:

   • ❌ Mentors NOT notified (meta flag persists)

Impact

Fixed:

• Mentors no longer receive duplicate notifications for the same job
• Reduces notification fatigue and confusion
• Maintains trust in the notification system

Unchanged:

• Admin notifications for edits (still sent, as intended)
• First-time publish notifications (still sent)
• Publish→publish guard (still prevents updates to published jobs)
• Mentor opt-in/opt-out functionality

Edge Cases Handled:

• Job edited multiple times: Only first publish notifies
• Job unpublished and republished: Only first publish notifies
• Job trashed and restored: Meta persists, no re-notification

Deviations from Plan

None - plan executed exactly as written.

Testing Notes

To verify in production:

1. Create test job, submit as provider → status: pending
2. Admin publishes → Check Action Scheduler for mentor notification batches
3. Provider edits job → status: pending
4. Admin republishes → Check Action Scheduler - should see NO new batches
5. Check error_log for: "Skipping mentor notification for job #X - mentors already notified on initial publish"

Manual database check:

SELECT post_id, meta_value
FROM wp_postmeta
WHERE meta_key = '_ddhh_mentors_notified';

Should show '1' for all published jobs that have triggered notifications.

Next Phase Readiness

Blockers: None Dependencies satisfied: Builds on existing notification system (05-01, 05-03) Follow-up needed: None - fix is complete and self-contained

This was a targeted bug fix with no architectural implications. The notification system is now fully idempotent - each job triggers exactly one mentor notification batch in its lifetime.