UHD_Media_Tool/docs/porting/moviepilot-episode-groups.md

MoviePilot 剧集组对照(TMDB episode groups)

上游(只读):/tmp/umt-moviepilot-v3-review-20261001(v3.0.10-1);前端 /opt/moviepilot-plus/upstream/MoviePilot-Frontend。使用说明见 docs/runbook/identity.md「剧集组」。

MP	我们	说明
tmdbv3api/objs/tv.py episode_groups(/tv/{id}/episode_groups)	adapters/tmdb/episode-groups.ts fetchEpisodeGroups	id、名称、类型、组数、集数、平台;走同一请求缓存(moviepilot-tmdb-cache.md)
objs/group.py details、tmdbapi.py get_tv_group_seasons(组内 episode_number 按顺序从 1 重排)、get_tv_group_detail(按 order 取组)	fetchEpisodeGroup	组 order = 季号;组内按 TMDB order 排序后编号(MP 用返回顺序,实际一致);重复 order 顺延;保留默认季集号 tmdbSeason/tmdbEpisode;占位名按无标题
MediaInfo.episode_group / _fill_group_season_info(识别时带 episode_group 把季集换成组的)	作品级设置 media_entity.episode_group_id(迁移 0075),季 / 集单元按组生成	MP 每次识别 / 订阅 / 整理各带一个 episode_group;我们存在作品上,季表、映射、订阅、刷新、刮削都读它
_process_episode_groups(没指定组时从 type 6 组取季年份)	不做	我们的季年份来自季单元
api/endpoints/media.py groups/{tmdbid}、group/seasons/{groupId}	GET /media-entities/{id}/episode-groups、GET /media-entities/{id}/episode-structure?groupId=	季卡片额外带本地已入库(按 TMDB 原季集对照)与当前结构下的季单元 id
schemas/subscribe.py episode_group、SubscribeSeasonDialog.vue(剧集组横向轨道 + 季卡片:海报、集数、首播、已入库)	订阅表单 SubscriptionSeasonPicker	订阅不单独存组:选了非当前结构的季要确认改作品设置
scraper.py:NFO / 剧照按 get_tv_group_detail 取季	刮削 NFO 用单元元数据(本来就按组);缺元数据时 scrapeTmdbSeason(…, episodeGroupId) 按组取	季海报 MP 仍取默认季;我们取组内首集所在默认季的海报
schemas/transfer.py episode_group、ReorganizeDialog.vue	整理弹窗「季集结构」:POST /files/organize 的 episodeStructures(createStructureEpisodeMapper)	缺省跟随作品;临时选的结构只这次换算季集与命名,资产覆盖按 TMDB 原季集换回作品结构的单元;可勾「同时设为作品的季集结构」先切换作品。见 runbook/organize.md「整理时指定剧集组」
metabase.py 识别词 g= 指定剧集组	不做	单条资源不指定组;规则的目标季集写组内的即可

我们多出来的:切换结构时已有单元按 TMDB 原季集原地迁移(引用不动,对不上的标临时并列出);集数解析多一步「按 TMDB 默认季集换算」(tmdb_season),发布者按默认季编号时自动换到组内季集;刷新时 TMDB 调整了组内顺序也按原季集挪单元。