AutoBangumi 日历视图：基于 Bangumi.tv 的番剧放送日程总览与分组管理指南-平芜编程栈

后端
前端
音视频

【免费下载链接】Auto_Bangumi

AutoBangumi - 全自动追番工具

项目地址：https://gitcode.com/gh_mirrors/au/Auto_Bangumi

自 v3.2 起，AutoBangumi（AB）内置了日历视图（Calendar View）功能，将你订阅的全部番剧按放送星期（周一至周日）整理成一张直观的周历，并借助 Bangumi.tv 的放送表数据自动标注每部番剧的播出时间。本文以仓库内日文版功能文档与中文版功能文档为主体，结合后端日历抓取、标题匹配与前端拖拽交互的源码实现，完整讲解该功能的用法、交互细节与底层原理，读完你即可熟练使用日历视图管理订阅规则、排查"未知"列番剧，并理解放送日数据的来源与刷新机制。

日历视图是什么

日历视图是 AB 在番剧列表之外提供的第二种订阅展示形态：不再以"每条下载规则一行"的表格呈现，而是以放送日为维度将订阅的番剧聚合到一周七天的列中。其设计目标是回答一个非常具体的问题——"今天（本周）有哪些我在追的番要播？"。

从 frontend 组件结构可以看出，日历视图由calendar-board.vue（桌面端周历网格）、calendar-day-column.vue（单日列）、calendar-card.vue（番剧卡片）、calendar-mobile-list.vue（移动端列表）与calendar-rule-list-popup.vue（分组规则弹层）协作渲染，桌面端与移动端共用同一套分组数据模型（types.ts中的BangumiGroup）。

每周时间表：周一到周日 + "未知"列

日历视图的核心展示逻辑是按放送星期（周一至周日）组织番剧：

一周七天各占一列，订阅的番剧按各自的air_weekday（放送星期）落入对应列；
没有放送时间数据的番剧会统一归入"未知"（不明）列，不会从视野中消失；
桌面端支持拖拽番剧卡片在列间移动，移动端则退化为按星期分组的列表。

后端数据模型中，"放送星期"以air_weekday字段存储，取值范围为0-6，依次对应周一至周日，未设置时为None；同时还有一个weekday_locked（放送星期锁定）布尔字段，用于防止自动刷新覆盖用户的手动设置。两个字段定义于 Bangumi 数据模型。

手动调整放送日

除了依赖 Bangumi.tv 自动填充，日历视图还允许用户直接干预放送日：

拖拽：在桌面端把一张番剧卡片拖到其他星期列，前端会为该番剧的所有规则批量调用后端接口写入新的星期值（见 calendar-board.vue 的onDropToDay，逐条调用setWeekday(rule.id, dayIndex)）；
取消（解绑）：将卡片拖出/通过弹层取消放送日，会把weekday置为null，番剧回到"未知"列（onUnpin逻辑见 calendar-board.vue）。

对应的后端接口是PATCH /api/v1/bangumi/{bangumi_id}/weekday，请求体形如{"weekday": 5}（0-6表示周一至周日，null表示重置为未知），越界值会被拒绝并返回 400，见 API 路由定义与接口测试用例。

Bangumi.tv 集成：放送数据的获取与刷新

日历视图的放送数据来源于Bangumi.tv 的放送表（calendar）接口，AB 启动/刷新时拉取当季正在播出的番剧列表，再与本地订阅逐一匹配。

点击"刷新时间表"更新数据

日历页面上提供刷新时间表（スケジュールを更新）按钮，点击后前端调用：

GET /api/v1/bangumi/refresh/calendar

该端点由 bangumi.py 路由暴露，内部委托给TorrentManager.refresh_calendar()，其完整流程见 manager/torrent.py：

调用fetch_bgm_calendar()从 Bangumi.tv 拉取当前放送表；
拉取失败时返回 500 与"从 Bangumi.tv 获取放送表失败"的提示；
遍历本地全部番剧规则，跳过已删除（deleted=True）或已锁定星期（weekday_locked=True）的条目；
用match_weekday()做标题匹配，得到放送日；
若匹配结果与现有air_weekday不同则更新并计数；
有变更时批量写回数据库，返回"放送表已刷新，更新了 N 部番剧"。

放送日数据的解析与转换

fetch_bgm_calendar()实现位于 bgm_calendar.py，核心细节：

请求地址为settings.network.bgm_base_url + "/calendar"，因此可通过配置切换 Bangumi.tv API 的基地址（默认https://api.bgm.tv，见网络配置模型），处于网络受限环境的用户可将其指向可达的镜像站；
Bangumi.tv 返回的数据按星期分组，每个分组带weekday.id，其编号规则是1=周一 … 7=周日，代码中统一转换为 AB 内部使用的0-6（bgm_weekday - 1）；
每个条目提取日文标题name与中文标题name_cn，连同air_weekday一起存入扁平列表。

标题匹配的四级策略

放送表拉回后，match_weekday()（见 bgm_calendar.py）负责把本地订阅的番剧与放送表条目对上号，匹配顺序依次为：

中文标题精确匹配：name_cn == official_title；
日文标题精确匹配：name == title_raw或name == official_title；
中文标题子串匹配（要求标题长度 ≥ 4 字符，双向包含判断，避免误匹配）；
日文标题子串匹配（同样要求 ≥ 4 字符）。

正是这套"先精确、后子串、中英日兼顾"的策略，决定了日历能否把订阅规则正确归到星期列——也直接决定了某些番剧为什么会落入"未知"列（见下文排障节）。

分组显示：多字幕组规则只占一张卡片

v3.2 起，同一部番剧即使配置了多条下载规则（例如多个字幕组），在日历中也只显示一次。这是日历视图与番剧列表最大的交互差异：

同一番剧的所有规则聚合为一个分组卡片，日历因此保持整洁；
点击分组卡片会弹出calendar-rule-list-popup.vue规则列表，列出该番剧所有可用的下载规则；
从弹层中选择特定规则，即可进入该规则的编辑流程（修改保存路径、重命名、订阅等）；
整个分组（含所有规则）也支持拖拽调整放送日。

前端的分组动作由 calendar/types.ts 中的BangumiGroup模型承载——一个分组内含rules数组，前端对分组做"设置星期/取消星期/点击编辑"等操作时，会遍历组内全部规则批量调用后端 API，保证分组视图与规则数据始终一致。

导航：点击海报能做什么

日历中的每张番剧卡片（海报）都是入口，点击后可执行三类操作：

查看番剧详情：查看该番剧的标题、海报、保存路径等订阅信息（对应GET /api/v1/bangumi/get/{id}）；
编辑下载规则：直接修改该番剧的规则配置（对应PATCH /api/v1/bangumi/update/{id}，见 bangumi.py）；
归档 / 禁用：
- 禁用：将规则标记为deleted=True，停止匹配下载但保留配置（POST /api/v1/bangumi/disable/{id}，见 bangumi.py），可通过"启用"恢复；
- 归档：进入归档态，从日常视图移除，但仍可反归档找回（PATCH /api/v1/bangumi/archive/{id}与PATCH /api/v1/bangumi/unarchive/{id}，见 bangumi.py）。

排障：番剧为什么出现在"未知"列

若某部番剧始终停在"未知"列，按官方文档提示与源码逻辑，可能原因有两类：

Bangumi.tv 上没有该番剧的放送数据：fetch_bgm_calendar()只返回"当前放送中"的条目，未开播、已完结或 Bangumi.tv 未收录的番剧自然不在放送表中；
标题无法匹配：本地official_title/title_raw与放送表中的name_cn/name对不上号。结合match_weekday()的匹配规则可以推断，长度不足 4 字符的标题不会参与子串匹配，且精确匹配要求完全一致，所以"简写别名、翻译差异、命名不规范"都容易导致匹配失败。

针对匹配不上的番剧，有两种补救路径：

手动拖拽/设置放送日：通过日历拖拽或PATCH /bangumi/{id}/weekday手动指定星期，注意此时前端写入的weekday_locked相关逻辑会保护该设置不被后续自动刷新覆盖（自动刷新会跳过weekday_locked=True的条目）；
等待刷新：若 Bangumi.tv 数据本身缺失，可在番剧数据更新后点击"刷新时间表"重新拉取匹配。

小结

AB 的日历视图把"订阅管理"从表格里解放出来，用放送星期重构了信息组织方式，其数据链路是：Bangumi.tv 放送表 →bgm_calendar解析与标题匹配 →air_weekday落库 → 前端按星期分组渲染。你可以通过"刷新时间表"保持放送日最新，通过分组卡片一站式管理多字幕组规则，通过拖拽手动修正匹配失败或数据缺失的番剧，再结合归档/禁用快速梳理追番节奏。