🔀 自定义映射
当媒体库里的番剧名称和 Bangumi 上的条目对不上时（译名不同、多季合并、特摄/纪录片、续作命名特殊等），程序可能无法自动找到正确的条目。此时可以在 「映射管理」 里为「某个标题」指定对应的 Bangumi 条目 ID，同步时会优先使用这条规则，避免反复匹配失败。
匹配优先级
程序在自动匹配时会按以下顺序查找自定义映射（命中即停止）：
- 季度感知精确映射（指定了季度的条目）
- 简单精确映射（标题完全一致，所有季度共用）
- 正则规则（按规则列表顺序依次尝试）
自定义映射优先于 bangumi-data 与 Bangumi API 搜索，为最高优先级。
三种映射方式
1. 简单精确映射（默认）
- 适用：媒体库标题固定、与 Bangumi 条目一一对应。
- 填写：番剧名称 + Bangumi ID；季度留空。
- 行为：只要同步请求里的标题（或原始标题）与「番剧名称」完全一致即命中，所有季度共用同一个 ID。
2. 季度感知映射
- 适用：同一标题字符串在不同季度应对应 Bangumi 上不同 subject（例如媒体库不按季拆分，但 Bangumi 分季条目）。
- 填写：番剧名称 + Bangumi ID + 季度（正整数）。
- 行为：仅当同步请求的
season与填写的季度一致时才命中；留空季度则视为简单映射，所有季度共用。
3. 正则规则
- 适用：一批标题共享命名规律（续作、系列作、带后缀的变体等），不适合逐条写精确名称。
- 填写：添加映射时类型选 「正则规则」，填写 Python 正则表达式、Bangumi ID，以及可选说明。
- 行为：对同步请求的标题与原始标题依次做匹配；第一条匹配成功的规则生效。页面底部提供 「正则匹配测试」，可先验证表达式再保存。
映射里要填什么
每条映射至少需要：
- 番剧名称 / 正则表达式：精确映射需与同步请求里的标题字符串尽量一致（包括标点、空格、季名等）。不确定时，可到 「同步记录」 查看失败条目实际带入的标题，按日志里的写法填写。
- Bangumi ID：该番在 Bangumi 上的 subject 编号（纯数字）。打开对应条目页面，地址一般为
https://bgm.tv/subject/数字，其中的数字即为 ID。
对于简单精确映射，程序会按「第一季 / 主条目」逻辑使用你填的 ID：一般填系列第一季或主条目的 ID，后续季数由程序根据续集链等逻辑处理，无需为每一季各写一条。若某季在 Bangumi 上是独立 subject 且简单映射对不上，请改用 季度感知映射 分别指定。
批量导入与导出
- 批量导入：粘贴 JSON 或上传
.json文件。可勾选「与现有映射合并」；不勾选则覆盖全部现有映射与规则。 - 导出映射：下载当前映射的完整 JSON，便于备份或迁移。
- 清空所有：删除全部映射与规则（不可撤销，操作前建议先导出备份）。
导入支持两种 JSON 形态：顶层 {"番剧名": "id"} 的简单对象，或带 mappings / rules 字段的完整结构。
与候选确认的关系
自动匹配失败但存在相近搜索结果时，程序会将候选沉淀到 「候选确认」 页面。确认某条候选后，可一键写入自定义映射，无需手填 Bangumi ID。
候选列表按相似度 score 降序展示，最相近的候选排在最前；若候选项均不符合，可点击「手动指定 Bangumi ID」直接输入条目 ID（方案 A），系统会校验 ID 有效性后再写入映射。
确认即补发
确认候选或手动指定 ID 后，若原同步记录状态为 error / queued，会自动触发一次补发同步，无需手动重试。
接下来
- 同步仍失败？看 排错说明 第 4、5 节。
- 想理解程序为何没匹配上？在 「同步记录」 详情查看完整匹配过程（含搜索参数、候选列表、各阶段耗时），或在 「调试工具」 发起测试匹配。
- API 不可达时想仍能匹配新条目？看 🔄 Bangumi Replay 待同步队列补发 与 🗄️ Bangumi Archive 离线查询层。