feat: MAJOR - implement webhook-first architecture with database priority

Revolutionary Workflow Changes (v0.7.0):
This fundamentally changes how NFOGuard handles timestamps and processing priority.

Webhooks = Source of Truth:
- First webhook fires → Use current timestamp → Store as permanent database entry
- Subsequent webhooks (upgrades) → Check database → Use original first-seen timestamp
- No more API calls during webhook processing → Webhook timing is ultimate authority
- Movies and TV episodes both use webhook-first approach

Manual Scans = Smart Fallback Logic:
- Priority 1: Our database (webhook timestamps) - database always wins
- Priority 2: Sonarr/Radarr import history (first import only)
- Priority 3: Air date as dateadded (final fallback)

Technical Implementation:
- Enhanced _get_webhook_episode_date() to use current timestamp as source of truth
- Added webhook_mode parameter to process_movie() for separate webhook logic
- All manual scans prioritize database entries before making API calls
- All timestamps converted to container timezone (Eastern Time)
- Enhanced debug logging for database lookups and timestamp decisions

Expected Workflow:
First download at 8:30am → webhook timestamp stored in database
Upgrade at 2:00pm → database entry found → original 8:30am timestamp preserved
Manual scan → database entry found → 8:30am timestamp used

This ensures the first-seen webhook timestamp is the permanent source of truth,
with upgrades and manual scans always preserving the original download time.
This commit is contained in:
2025-09-14 10:52:43 -04:00
parent e188706001
commit df5785e8ad
3 changed files with 97 additions and 36 deletions
+51 -2
View File
@@ -327,6 +327,55 @@ sonarr-nfo-cache | [2025-09-14T09:37:00-04:00] INFO: Batched movie webhook...
---
---
### 🆕 v0.7.0 MAJOR: Webhook-First Architecture & Database Priority (September 2025)
**🎯 Revolutionary Workflow Changes:**
This is a **major architectural change** that fundamentally alters how NFOGuard handles timestamps.
**📡 Webhooks = Source of Truth:**
- **First webhook seen** → Use current timestamp → Store as **permanent source of truth**
- **Subsequent webhooks** (upgrades) → Check database → **Use original first-seen timestamp**
- **No more API calls during webhooks** → Webhook timing is the ultimate authority
**🔍 Manual Scans = Smart Fallback Logic:**
- **Priority 1**: Our database (webhook timestamps) → **Database always wins**
- **Priority 2**: Sonarr/Radarr import history (first import only)
- **Priority 3**: Air date as dateadded (final fallback)
**⚡ Implementation Details:**
- **TV Episodes**: Enhanced `_get_webhook_episode_date()` → uses current timestamp as source of truth
- **Movies**: New webhook mode in `process_movie()` → separate logic for webhooks vs manual scans
- **Database Priority**: Manual scans now **always** check database first before API calls
- **Local Timezone**: All timestamps converted to container timezone (Eastern Time)
**🛠️ Technical Changes:**
- **Webhook Sources**: Episodes/movies show `webhook:first_seen` instead of complex API sources
- **Database Verification**: Added immediate verification logging after database writes
- **Enhanced Debug**: Comprehensive logging shows database lookups and timestamp decisions
- **Clean Separation**: Webhook processing vs manual scan processing use different code paths
**📋 Expected Workflow:**
```
# First Download (8:30am EST)
Webhook fires → Use 8:30am timestamp → Store in database → NFO shows 8:30am
# Upgrade Download (2:00pm EST)
Webhook fires → Check database → Find 8:30am entry → NFO still shows 8:30am
# Manual Scan
Curl scan → Check database → Find 8:30am webhook entry → NFO shows 8:30am
```
**🏆 Benefits:**
- **Consistent Timestamps**: First download time is preserved forever
- **Simplified Logic**: Webhooks don't query APIs, just use current time
- **Performance**: Faster webhook processing with database-first approach
- **Predictable**: Clear hierarchy - database beats everything else
---
**Last Updated:** September 14, 2025
**Version:** v0.6.7
**Status:** Enhanced Production Ready
**Version:** v0.7.0
**Status:** Production Ready - Major Architecture