tmdbGetWithRetry 带重试的 TMDb GET 请求 超时后自动重试 1 次（共 2 次尝试），仍然失败则返回错误 每次请求携带随机 User-Agent 和浏览器级请求头，重试间隔 2-4 秒随机化

==================== 缓存 ==================== GetCache 从缓存获取（双层：先查内存，再查持久化存储）

Register 用户注册

Start 启动 UDP 监听。返回 nil 表示成功启动。 已启动时重复调用会被忽略。

addItem 追加脏数据条目

auditFromContext 从 Gin 上下文中提取操作者信息并记录审计日志

broadcastScanEvent 广播扫描事件

cleanJSONResponse 清理 LLM 返回的 JSON（去除 markdown 代码块等）

excludeDuplicates 在前端列表查询里统一过滤掉"同片副本"， 仅保留主版本（duplicate_of 为空）。这是"同片多版本折叠"的核心约束。 注意：仅用于面向用户的列表/海报墙；管理后台、版本切换、扫描器、清理工具 等需要看到全部记录的场景请直接走 r.db。

getRandomUserAgent 从 User-Agent 池中随机选取一个

安全调用 invoke —— 桌面端才有效

joinPath 路径拼接（webdav:// 用正斜杠）

sanitizeFilename 清理文件名中不合法的字符

setupAuthService 创建测试用的AuthService

vfsJoin 拼接路径：对 webdav:// 前缀的路径使用正斜杠，避免 filepath.Join 在 Windows 下把前缀破坏为 webdav:\

AdminOnly 管理员权限中间件

GetOutputDir 获取转码输出目录

ScrapeMedia 为单个媒体刮削元数据 mode: "primary" 表示主数据源（覆盖写入），"supplement" 表示补充源（仅填充缺失字段）

==================== 进度推送 ====================

broadcastDownloadEvent 广播下载事件

broadcastTaskUpdate 广播任务更新

broadcastTranscodeEvent 广播转码事件

collapseWhitespace 把多空白合一并 trim

formatEmbyTime 将 time.Time 转为 Emby 客户端期望的 ISO8601 时间字符串。

getIntQuery 从 query 中读取整数参数，缺省返回 def。

==================== 时间工具函数 ==================== parseVTTTimeMs 解析 VTT 时间戳为毫秒数 支持格式: "HH:MM:SS.mmm" 或 "MM:SS.mmm"

probeMediaInfo 使用FFprobe提取视频元数据（.strm 文件走特殊逻辑）

scanExternalSubtitles 扫描外挂字幕文件

BuildStandardNames 一处渲染，三处共用。规则以一键入库为标准。

GetDirectStreamInfo 获取直接播放的文件路径和MIME类型 对于 STRM 文件，返回特殊标记，由 handler 层走代理逻辑

NormalizeForCompare 归一化标题用于分组 key 匹配（忽略全半角、空白、常见标点差异）。 用途： - 合集名 / 分组 key 的稳定比较 - 避免 "逃学威龙" 与 "逃学威龙 " / "逃学 威龙" / "逃学威龙：" 被误判为不同

NormalizeSeriesTitle 对任意来源的 Series 标题做最后一轮清洗， 用于：入库前 / 搜索前 / 合并前的归一化。 规则： - 去发行组/广告【xxx压制】【Q群xxx】 - 去站点标签 [yyh3d.com] - 去编码/来源噪声 - 剥离末尾季号（S1 / 第一季 /

Register 注册数据源（按优先级自动排序）

==================== 核心方法 ==================== SearchSeries 搜索剧集

==================== Bangumi API 调用 ==================== SearchSubjects 通过 Bangumi API 搜索条目

Type 返回文件系统类型标识

==================== 错误日志 ==================== addErrorLog 添加错误日志

clear 清空缓存（例如文件关闭时）

findOrganizedHardlinkRecord 判断当前源路径是否已经被 AI 整理后的硬链接记录代表。 当 Media.FilePath 已同步为 OrganizeOutputDir 下的路径时，后续扫描源目录不能再把源文件当新媒体入库。

downloadToFile 下载文件到指定路径（带重试）

extractSeasonFromDirName 从目录名中提取季号 例如: "一拳超人 S2" → 2, "Breaking Bad Season 1" → 1, "一拳超人 第二季" → 2

格式化码率为可读格式

格式化编码器名称

==================== 辅助方法 ====================

isVideoExt 判断是否为视频扩展名

mapMediaToItem 将 Media（电影或剧集单集）转成 Emby BaseItemDto。 kind = "Movie" / "Episode" / "Video"。

libmpv2::Error -> anyhow::Error 桥接（libmpv2::Error 未实现 StdError，不能用 .context()）

parseEpisodeInfo 从文件名解析剧集信息 支持的命名格式： 标准格式: [字幕组][剧名][One-Punch Man][01][1280x720][简体] 季集格式: [HYSUB][ONE PUNCH MAN S2][OVA01][GB_MP4][1280X720].mp4

==================== 豆瓣 API 调用 ==================== searchDouban 通过豆瓣搜索API获取结果 使用豆瓣 frodo API（移动端接口，较稳定）

sendDLNAAction 发送DLNA SOAP控制指令

statPath 获取文件信息（支持 webdav://）

GetMediaTask 获取媒体的预处理状态

GetPlanWithItems 取规划任务并预加载条目

IncrTokenVersion 令牌版本号自增（用于吊销所有旧Token）

SearchTMDb 公开的TMDb搜索方法（用于手动元数据匹配）

Start 启动 mDNS 广播服务。

==================== 文件编辑 ==================== UpdateFileInfo 更新文件信息

UpdateMediaCount 更新合集的电影数量和年份范围 media_count 按 version_group 去重（同一部电影的不同版本算 1 部），贴合前端"系列里有几部电影"的语义； file_count 为原始文件总数（每个版本各算一个）。

UpdatePlanFields 部分字段更新

WriteMediaNFO 为普通媒体生成同名 .nfo 文件。 自动刮削路径默认选择 skip，避免覆盖用户已有的手写 NFO。

addOperation 添加操作记录

processOne 处理单个视频文件

buildUserItemData 组装 Emby UserData。

canMediaPlayDirectly 包级判定：判断该媒体是否可在浏览器端零转码播放。 抽成包级函数的原因：PreprocessService 需要在"自动批量提交"路径上据此跳过 已经能直接播放/Remux 的媒体，但 PreprocessService 与 StreamService 之间

* 建立 WebSocket 连接 */