feat(ingest): parse video refs and fetch detail by bvid

reaction_board/bilibili/client.py

@@ -27,6 +27,7 @@ from .models import (
     FolderInfo,
     InfosResult,
     LoginState,
+    VideoDetail,
     ViewStat,
 )
 
@@ -463,6 +464,53 @@ class BilibiliClient:
         except (TypeError, ValueError) as exc:
             raise BilibiliProtocolError(f"view 解析失败: {exc}") from exc
 
+    def view_detail(
+        self, *, aid: int | None = None, bvid: str | None = None
+    ) -> VideoDetail:
+        """按 aid 或 bvid 取视频完整详情；两者必须且只能提供一个。"""
+        if (aid is None) == (bvid is None):
+            raise ValueError("view_detail 必须且只能提供 aid 或 bvid")
+        if bvid is not None:
+            url = f"{BASE}/x/web-interface/view?bvid={urllib.parse.quote(str(bvid))}"
+        else:
+            url = f"{BASE}/x/web-interface/view?aid={int(aid)}"
+        payload = self.get_json(url)
+        data = payload.get("data")
+        if not isinstance(data, Mapping):
+            raise BilibiliProtocolError("view data 不是对象")
+        try:
+            return VideoDetail.from_api(data)
+        except (TypeError, ValueError) as exc:
+            raise BilibiliProtocolError(f"view 解析失败: {exc}") from exc
+
+    def resolve_short_link(self, url: str, *, max_hops: int = 5) -> str:
+        """跟随 ``b23.tv`` 短链重定向，返回最终 URL。
+
+        只用于把短链还原成含 bvid/aid 的 bilibili 视频链接；不做分页或登录。
+        """
+        current = str(url)
+        for _ in range(max(1, int(max_hops))):
+            host = (urllib.parse.urlparse(current).hostname or "").lower()
+            if not host.endswith("b23.tv"):
+                # 已经不是短链域名（例如已还原到 bilibili.com/video/BV…）直接返回。
+                return current
+            response = self.transport.request(
+                "GET", current, self._headers(False), data=None, timeout=self.timeout
+            )
+            headers = {
+                str(key).lower(): value for key, value in response.headers.items()
+            }
+            location = headers.get("location")
+            if response.status >= 400:
+                raise BilibiliHTTPError(
+                    response.status, response.body.decode("utf-8", "replace")[:200]
+                )
+            if response.status in {301, 302, 303, 307, 308} and location:
+                current = urllib.parse.urljoin(current, location)
+                continue
+            return current
+        return current
+
     def relation_stat(self, mid: int) -> FanStat:
         url = f"{BASE}/x/relation/stat?vmid={int(mid)}"
         payload = self.get_json(url)

reaction_board/bilibili/models.py

@@ -146,6 +146,89 @@ class ViewStat:
         )
 
 
+@dataclass(frozen=True)
+class VideoDetail:
+    """``x/web-interface/view`` 的完整元数据 + 七项统计。
+
+    比 :class:`ViewStat` 多出 UP、时长、分 P 数、封面等字段，供手动入库建库使用。
+    """
+
+    aid: int
+    bvid: str | None
+    title: str
+    up_mid: int | None
+    up_name: str | None
+    pubdate: int
+    duration: int
+    pages: int | None
+    cover: str | None
+    stat: ViewStat
+
+    def metrics(self) -> dict[str, int]:
+        return self.stat.metrics()
+
+    @classmethod
+    def from_api(cls, item: Mapping[str, Any]) -> "VideoDetail":
+        stat = ViewStat.from_api(item)
+        owner = item.get("owner") or {}
+        if not isinstance(owner, Mapping):
+            owner = {}
+        raw_mid = owner.get("mid")
+        up_mid = (
+            raw_mid
+            if isinstance(raw_mid, int) and not isinstance(raw_mid, bool)
+            else None
+        )
+        up_name = owner.get("name")
+        if not isinstance(up_name, str) or not up_name:
+            up_name = None
+
+        raw_duration = item.get("duration")
+        duration = (
+            raw_duration
+            if isinstance(raw_duration, int)
+            and not isinstance(raw_duration, bool)
+            and raw_duration >= 0
+            else 0
+        )
+
+        pages: int | None = None
+        raw_pages = item.get("pages")
+        if isinstance(raw_pages, list) and raw_pages:
+            pages = len(raw_pages)
+        else:
+            raw_videos = item.get("videos")
+            if (
+                isinstance(raw_videos, int)
+                and not isinstance(raw_videos, bool)
+                and raw_videos > 0
+            ):
+                pages = raw_videos
+
+        raw_pubdate = item.get("pubdate") or item.get("ctime")
+        pubdate = (
+            raw_pubdate
+            if isinstance(raw_pubdate, int) and not isinstance(raw_pubdate, bool)
+            else 0
+        )
+        cover = item.get("pic")
+        if not isinstance(cover, str) or not cover:
+            cover = None
+
+        return cls(
+            aid=stat.aid,
+            bvid=stat.bvid,
+            title=stat.title,
+            up_mid=up_mid,
+            up_name=up_name,
+            pubdate=pubdate,
+            duration=duration,
+            pages=pages,
+            cover=cover,
+            stat=stat,
+        )
+
+
 @dataclass(frozen=True)
 class FanStat:
     mid: int