refactor(subscribe): 统一 lack_episode 语义并暴露 completed_episode 派生字段 (#5817)

app/schemas/subscribe.py

@@ -1,6 +1,8 @@
 from typing import Optional, List, Dict, Any
 
-from pydantic import BaseModel, Field, ConfigDict
+from pydantic import BaseModel, Field, ConfigDict, model_validator
+
+from app.schemas.types import MediaType
 
 
 class Subscribe(BaseModel):
@@ -45,6 +47,8 @@ class Subscribe(BaseModel):
     start_episode: Optional[int] = 0
     # 缺失集数
     lack_episode: Optional[int] = 0
+    # 已完成集数
+    completed_episode: Optional[int] = None
     # 附加信息
     note: Optional[Any] = None
     # 状态：N-新建， R-订阅中
@@ -82,6 +86,37 @@ class Subscribe(BaseModel):
 
     model_config = ConfigDict(from_attributes=True)
 
+    @model_validator(mode="after")
+    def _fill_completed_episode(self) -> "Subscribe":
+        """
+        填充 ``completed_episode`` 派生字段。电视剧订阅按 best_version 分支计算，
+        电影或缺少 total_episode 时保持 None。
+        """
+        if self.completed_episode is not None:
+            # 调用方显式提供过的值不覆盖
+            return self
+        total_episode = self.total_episode or 0
+        if self.type != MediaType.TV.value or not total_episode:
+            return self
+        start_episode = self.start_episode or 1
+        if not self.best_version:
+            lack = self.lack_episode or 0
+            self.completed_episode = max(total_episode - lack, 0)
+            return self
+        # 洗版口径：起始集前视为逻辑完成 + [start, total] 范围内 priority==100 命中。
+        # ``start_episode > total_episode`` 属于异常配置，需把 "起始集前" 偏移截断到 total，
+        # 防止 completed_episode 越过分母 total_episode。
+        episode_priority = self.episode_priority or {}
+        priority_completed = sum(
+            1
+            for ep_key, priority in episode_priority.items()
+            if str(ep_key).isdigit()
+            and start_episode <= int(ep_key) <= total_episode
+            and priority == 100
+        )
+        self.completed_episode = min(max(start_episode - 1, 0), total_episode) + priority_completed
+        return self
+
 
 class SubscribeShare(BaseModel):
     # 分享ID