# VocaLog 导入整理说明

本站使用统一模板，不代表网易云、QQ 音乐或哔哩哔哩提供原生导出。请将你能够取得的本人记录整理为 CSV 或 JSON；首版没有自动登录、账号绑定或持续同步。

1. 下载模板。CSV 第一行是表头；JSON 是对象数组，模板第一项为空白占位，填写真实信息后才能导入。
2. 按下面的字段与类型整理。保留平台 ID 为文本，不要让表格软件转换成长数字或科学计数法。
3. 上传，查看有效行、错误行、重复项。逐首确认歌曲匹配，或选择“保留原始信息”。
4. 确认后仅新增有效且未重复的记录。错误行可修正后另行上传。撤销只删除该批次实际新增的记录。

## 字段

| 字段 | 含义 |
| --- | --- |
| source | netease / qq / bilibili |
| kind | play / snapshot / view / favorite |
| source_song_id | 平台歌曲 ID，B 站为 BV 或 av 号。与链接至少填一项 |
| source_url | 原平台 HTTPS 歌曲/视频链接，可空。不要填搜索结果或歌单页面 |
| title | 歌曲标题，必填 |
| producer | P 主，可空；不是搬运者或上传者 |
| vocalist | 歌姬，可空 |
| version | 原曲、翻调、Remix 等备注，可空。不同作品使用各自的平台 ID |
| source_record_id | 平台的单条记录 ID，可空；不是歌曲 ID |
| part | B 站分 P，所有 B 站记录必填，单 P 视频填 1 |
| occurred_at | 逐次播放或观看的时间 |
| count | 累计快照次数，非负整数；未知请留空，不能用 0 代替 |
| period_key | 累计周期：all，或 YYYY-MM-DD/YYYY-MM-DD（包含首尾日期） |
| snapshot_at | 平台累计榜的快照时间 |

时间示例：`2026-09-05T10:20:00+08:00`、`2026-09-05T02:20:00Z`。不带时区时按上海时间解释，必须包含时分秒。无效日期会报错。

## 四种口径

- **play**：每行是一条明确的听歌事件，必须有 occurred_at。count 不参与累计，一行不代表多次播放。
- **snapshot**：必须有 count、period_key、snapshot_at。同一份榜单所有歌曲填相同 snapshot_at。每个平台、每个周期采用最新整份快照，不保留新快照缺失的旧歌曲，不相加。撤销最新批次后恢复仍保留的旧快照。一份快照尽量放在同一批次内。
- **view**：仅 bilibili，必须有 occurred_at 和 part。只统计观看事件，不推算完整听完或复听次数。
- **favorite**：歌单/收藏，只需要歌曲信息。用于兴趣推荐，不计入听歌次数。

缺少必要时间或次数的行显示在预览错误列表，不补值或转换类型，仍可保留原文件。没有逐次播放时间的数据不能生成近 7/30 天精确听歌榜。

## 去重与歌曲匹配

优先按来源和单条记录 ID 去重；没有 ID 时按平台、歌曲 ID（或链接）、分 P、规范化时间识别事件。收藏按歌曲身份去重，快照还包括周期和快照时间。同一文件重复上传不增加次数；不同账户互不影响。

自动匹配仅使用已缓存的明确平台 ID + 分 P，以及你自己此前确认的匹配。同名不代表同一首作品。网易云和 QQ 音乐与曲库之间没有可靠的跨平台 ID 映射，需要手动确认或保留原始信息。BV 与 av 未经验证不互相转换。

搜索候选后请核对 P 主、歌姬和原视频。确认仅影响你自己的记录。要修改已经导入的匹配，先撤销该批次，再重新上传确认；重复导入不会覆盖旧记录。

每批最多 1 MB、1000 行；内容过长还可能需要进一步拆分。CSV 为 UTF-8，可带 BOM，支持引号内逗号、双引号和换行。请保存原文件作为备份。