剧集放送时间与 bangumi-data 缓存

自动和手动同步剧集使用相同的时间合成逻辑。日期仍来自剧集元数据；当季度没有明确的 airTime，且有 Bangumi 条目 ID 时，从 bangumi-data 的作品级时间中补充时分。没有命中则使用 UTC+8 的 23:00。已有明确的季度时分优先，不修改界面和手工剧集。

这里只采用作品的顶层 broadcast（有效时优先）或 begin，并不代表巴哈姆特动画疯或其他平台的实际上架时间。匹配使用 sites 中 site === "bangumi" 的精确 ID；相同 ID、相同日程的多语言条目合并，有冲突则不自动选择候选，未匹配时也不进行标题模糊搜索。

日期、时区和下载偏移

所有时分固定转换为 UTC+8，日期合成不依赖 API 服务所在机器的时区。每次季度同步只读取一次索引，所有剧集使用同一个时分和日期偏移。

Bangumi 的 episodes.airdate 只有日期，凌晨档可能采用前一天的“节目日”。不能一律加一天，也不能只截取 bangumi-data 的时分后直接拼接日期。例如抽样结果：

Bangumi 条目	首集日期	bangumi-data begin	UTC+8 的实际首播
幼馴染とはラブコメにならない	2026-01-05	2026-01-05T15:00:00Z	01-05 23:00，不跨日
東京リベンジャーズ 三天戦争編	2026-10-02	2026-10-02T16:23:00Z	10-03 00:23，跨一天
ネクストシャイン！	2026-01-01	2025-12-31T16:00:00Z	01-01 00:00，日期已经一致

抽样日期为 2026-10-18，Bangumi 日期来自公开 API，时间来自 bangumi-data；这些观察不是对所有条目的日期约定的保证。

实现使用当前条目正片第 1 集的日期作为锚点（使用条目内的集号，不用可能跨季累计的 sort），与 begin 的 UTC+8 日期比较。两者相差不超过一天时，将这个日差应用于本次同步的剧集日期；没有唯一有效首集日期或相差超过一天时，保留原日期。已有季度时分不应用这个修正。先行、停播、特殊篇和后续排播变更不在此规则的精确处理范围内；剧集日期仍以元数据源为准，不根据每周周期重新推算。

最终先生成 rawAirTime，再沿用原有公式：airTime = rawAirTime - downloadOffsetHours。因此正数偏移提前下载，负数偏移延后下载。

缓存和故障处理

• 下载地址为 dist/data.json，所有 GitHub 请求使用 GlobalAxiosService，即 network.proxy.global 对应的全局代理。
• 数据仅保存在进程内存索引和现有 S3 bucket 的 cache/bangumi-data/v1.json 快照中，不新增数据库表或存储原始目录数据。数据库只保存同步流程原本就有的剧集结果时间。
• 启动时异步恢复 S3 快照；没有可用数据时立即尝试下载，不等第一次定时任务。首次同步可等待这次初始化；已有缓存时直接读取。
• 每分钟检查一次刷新时机，成功验证后每 6 小时携带 ETag 条件请求。304 保留原索引，更新验证时间；200 完整解析、验证并建索引后一次性替换。
• 刷新失败保留旧数据，重试从 5 分钟开始倍增，最大 1 小时。空数据、无可用映射、格式错误和异常响应不会覆盖有效缓存。查找未命中不单独发起下载。
• HTTP 请求超时 20 秒，响应上限 32 MiB；S3 操作超时 10 秒。S3 不可用时仍可使用成功下载的内存数据。重叠的初始化和刷新共享进行中的任务。

无需 Prisma 迁移或新增配置。现有 S3 配置需要允许读取和写入上述快照对象。快照包含来源地址、格式版本、ETag、下载和验证时间以及条目数据，便于重启恢复和格式校验。

数据来源和许可

数据来自 bangumi-data 项目贡献者，遵循其 CC BY 4.0 许可声明。本系统从数据中提取 Bangumi 对照和放送时间、进行时区换算并生成缓存索引；不保证作品首播时间等于具体资源或平台的发布时间。