docs: 添加"工作原理"小节

docs/.vitepress/config.mts

@@ -47,6 +47,7 @@ export default defineConfig({
 				items: [
 					{ text: "配置文件", link: "/configuration" },
 					{ text: "命令行参数", link: "/args" },
+					{ text: "工作原理", link: "/design" },
 				],
 			},
 			{

docs/design.md

@@ -0,0 +1,71 @@
+# 工作原理
+
+本节会尽可能简单明了地介绍 `bili-sync` 的工作原理，让用户了解程序的整体执行过程。
+
+## b 站的视频结构
+
+在了解程序工作原理之前，我们需要先对 b 站视频的组织结构有一个大概的了解。简单来说：
+
+- 收藏夹、稍后再看、视频合集、视频列表等结构都是由一系列视频构成的一个列表；
+- 每个视频都有唯一的 bvid，包含了封面、描述和标签信息，并包含了一个或多个分页；
+- 每个分页都有一个唯一的 cid，包含了封面、视频、音频、弹幕。
+
+为了描述方便，在后文会将收藏夹、稍后再看这类结构统称为 video list，将视频称为 video，将分页称为 page。不难看出这三者有着很明显的层级关系：**video list 包含若干 video，video 包含若干 page**。
+
+一个非常容易混淆的点是视频合集/视频列表与多页视频的区别：
+
+> [!NOTE]
+> ![bili_collection](./assets/bili_collection.jpg)
+>
+>![bili_video](./assets/bili_video.jpg)
+
+这两张图中，上图是视频合集，下图是多页视频。这两者在展示上区别较小，但在结构上有相当大的不同。结合上面对 b 站视频结构的介绍，这个区别可以简单总结为：
+
++ **视频合集是由多个仅包含单个 page 的 video 组成的 video list**；
+
++ **多页视频是由多个 page 组成的 video**。
+
+这说明它们是处于两个不同层级的结构，因此程序对其的处理方式也有着相当大的不同。
+
+## 数据库设计
+
+> [!NOTE]
+> 可以[前往此处](https://github.com/amtoaer/bili-sync/tree/main/crates/bili_sync_entity/src/entities)实时查看当前版本的数据库表结构。
+
+既然拥有着明显的层级关系，那数据库表实际上是非常好设计的。为了简化实现，程序没有额外考虑单个 video 被多个 video list 引用的情况（如一个视频同时在收藏夹和稍后再看中）。而是简单的将其设计为了不交叉的层级结构。
+
+### video list 表
+
+从上面的介绍可以看出，video list 并不是一个特定的结构，而是一个抽象的概念。我选择将其特化实现为多张表：
+
+1. favorite：收藏夹；
+2. watch_later：稍后再看；
+3. collection: 视频合集/视频列表；
+4. ....
+
+### video 表
+
+video 表包含了 video 的基本信息，如 bvid、标题、封面、描述、标签等。此外，video 表还包含了与 video list 的关联。
+
+具体来说，每一种 video list 都在 video 表中有一个对应的列，指向 video list 表中的 id，如 favorite_id、collection_id 等。接下来将这些键与 video 的 bvid 绑在一起建立唯一索引，就可以保证 video list 中不会有重复的 video。
+
+### page 表
+
+page 表包含了 page 的基本信息，如 cid、标题、封面等。与 video 类似但更简单，page 表仅包含了与 video 的关联。
+
+## 执行过程
+
+### 初始化
+
+程序启动时会读取配置文件、迁移数据库、初始化日志等操作。如果发现需要的文件不存在，程序会自动创建。
+
+### 扫描 video list
+
+> [!WARNING]
+> b 站实现接口时为了节省资源，通过 video list 获取到的 video 列表通常是分页且不包含详细信息的。
+
+程序会扫描所有配置文件中包含的 video list，获取其中包含的 video 的简单信息并填充到数据库。
+
+在实现时不能每次都将 video 列表全部扫一遍，因此程序会使用视频的 bvid 与 time 字段来检验视频是否已经存在于数据库中。实际拉取时会逐页请求，发现 bvid 与 time 均相同的记录会认为已经到达扫描过的位置，停止拉取。
+
+### 填充 video 详情