Jellyfin项目NextUp API调用中首集播放状态丢失问题分析

问题背景

在Jellyfin媒体服务器项目中，NextUp API调用是用户获取"接下来观看"内容的重要接口。近期发现该接口在某些特定情况下会错误地过滤掉剧集的第一集，即使用户已经部分观看了该集内容。

问题现象

当用户同时观看多个剧集时，如果满足以下条件组合：

1. 用户完整观看了剧集X的第一集
2. 用户部分观看了剧集Y的第一集
3. 用户又完整观看了剧集X的下一集

此时NextUp API返回结果中会丢失剧集Y的部分观看记录，导致用户无法继续从上次中断的位置观看。

技术分析

问题根源位于TVSeriesManager.cs文件中的过滤逻辑。该逻辑原本设计目的是为了控制是否显示剧集的第一集，但在特定场景下会产生误判。

关键代码段分析：

var anyFound = false;

return allNextUp
    .Where(i =>
    {
        if (request.DisableFirstEpisode)
        {
            return i.LastWatchedDate != DateTime.MinValue;
        }

        if (alwaysEnableFirstEpisode || (i.LastWatchedDate != DateTime.MinValue && i.LastWatchedDate.Date >= request.NextUpDateCutoff))
        {
            anyFound = true;
            return true;
        }

        return !anyFound && i.LastWatchedDate == DateTime.MinValue;
    })

这段代码存在两个主要问题：

1. 状态变量污染：anyFound变量在整个过滤过程中保持状态，导致后续项的过滤结果依赖于前面项的判断结果。

2. 首集判断逻辑缺陷：对于部分观看的首集，由于LastWatchedDate可能仍为DateTime.MinValue，会被错误地过滤掉。

解决方案

该问题已在项目的新PR中得到修复。新版本主要改进了以下方面：

1. 重构了首集判断逻辑，不再依赖全局状态变量
2. 更精确地区分"从未观看"和"部分观看"的状态
3. 确保部分观看的剧集无论是否为第一集都能正确显示

技术启示

这个问题给开发者带来几个重要启示：

1. 避免有状态的LINQ查询：在LINQ查询中使用可变状态变量容易导致不可预期的行为。

2. 播放状态管理：媒体播放状态的判断应该综合考虑多个因素，包括：

   • 是否完整播放
   • 播放进度百分比
   • 最后播放时间
   • 是否为系列首集

3. 边界条件测试：对于媒体播放这类功能，需要特别注意测试各种边界条件，特别是：

   • 首集部分观看
   • 多剧集交叉观看
   • 长时间暂停后恢复

总结

Jellyfin作为开源媒体服务器，其播放状态管理功能的健壮性直接影响用户体验。这个NextUp API的问题修复不仅解决了一个具体bug，更重要的是完善了播放状态判断的核心逻辑，为后续功能开发奠定了更可靠的基础。开发者在使用类似功能时，应当注意播放状态的多维度判断，避免单一条件导致的误判。