Designing an explainable sync ledger for watch state across media servers

说明与用途

跨媒体服务器的观看状态同步因不同的标识符、库重建和重复观看而变得复杂。解决方案是创建一个规范事件记录、每个目标的交付日志，并使用操作账本来解释每个结果并支持恢复。

问题

Synchronizing watch state across multiple media servers is complicated by differing provider identities, library rebuilds, delayed webhooks, and repeated watches, making a simple watched flag insufficient.

结果

The system now provides transparent, recoverable watch state synchronization across multiple media servers, with clear evidence for each delivery outcome and a robust recovery workflow.

工作流

• 1. Create a stable internal identity for each media item to decouple from provider-specific IDs.
• 2. Record a canonical watch event with explicit lifecycle states (new, repeated, partial, completed, corrected).
• 3. For each destination, log a delivery record containing source event, destination, outcome, reason, attempt time, and retry context.
• 4. When conflicts arise, preserve evidence, identify the stronger signal, and document the decision.
• 5. Handle rewatches with distinct event semantics to avoid duplicate imports.
• 6. For library rebuilds, perform conservative matching, surface uncertainty, and require manual review before bulk changes.
• 7. Back up the system before major changes, test with a small library, and expand after verifying Sync Activity results.
• 8. Run integration tests covering onboarding, manual review, retries, backups, metadata, and visible reasons for each outcome.
• 9. Use AI assistance during development to generate changes, but not at runtime.
• 10. Provide documentation for recovery steps and provider actions that are irreversible.

证据

A boolean watched flag is not enough to explain what happened.

来源

The sync layer needs a stable internal identity and an explicit review path when a match is uncertain.

来源

The record is the basis of Plembfin's Sync Activity view.

来源