Annim 元数据仓库

src/05.audio-library/01.protocol.md

@@ -105,7 +105,9 @@ Access-Control-Allow-Origin: *
   "protocol_version": "0.2.1",
   // 音频仓库最近一次数据更新时间
   // 用于客户端缓存 `/albums` 请求结果
-  "last_update": 1639631487
+  "last_update": 1639631487,
+  // 用于提供元数据的 `Annim` 服务器 URL
+  "meta_server": "https://annim.example.com"
 }
 ```
 

src/06.anniv/03.playlist.md

@@ -307,3 +307,23 @@ type PatchedPlaylistInfo = Partial<Omit<PlaylistInfo, "id" | "owner">>;
 | -------- | -------------- |
 | `103002` | 播放列表不存在 |
 | `103003` | 非法修改类型   |
+
+## 搜素播放列表
+
+### Endpoint
+
+`GET /api/playlist/search`
+
+### 请求
+
+#### 请求参数
+
+| 参数名    | 详情           |
+| --------- | -------------- |
+| `keyword` | 搜索关键词     |
+| `limit`   | 最多返回条目数 |
+| `offset`  | 跳过条目数     |
+
+### 响应
+
+返回一个 `PlaylistInfo[]` ，按相关程度降序排序。

src/08.annim/00.readme.md

@@ -0,0 +1,7 @@
+# Annim
+
+> ⚠️️ 目前的 `Annim` 仍处于 `Draft` 状态，尚未完全定稿。欢迎随时提出意见或建议。
+
+> ⚠️️ 目前 `Annim` 协议的版本为 `1`。
+
+`Annim` 是独立的元数据服务，每一个 `Annil` 都需要指定一个对应的 `Annim` 服务提供元数据。

src/08.annim/01.protocol.md

@@ -0,0 +1,105 @@
+# Annim 元数据协议
+
+Annim 元数据协议用于向客户端提供元数据服务。所有接口均使用 [Anni 信息导出格式](../06.anniv/07.export-format.md)。
+
+## 元数据
+
+### 获取 Tag 列表
+
+`GET /tags`
+
+#### 返回
+
+返回包含所有 `Tag` 的数组，类型为 `TagInfo[]` 。
+
+### 专辑信息
+
+通过 `album_id` 获得专辑元数据的接口。支持同时获取多张专辑的元数据信息。
+
+#### Endpoint
+
+`GET /albums`
+
+#### 请求参数
+
+| 参数名 | 说明                         |
+| ------ | ---------------------------- |
+| `id[]` | 待获取元数据的专辑 `ID` 列表 |
+
+#### 返回
+
+返回以 `album_id` 为键，专辑元数据或空为值的 `Object`。
+
+当查询成功时，值为专辑的 `AlbumDetail`，否则为 `null`。
+
+### 按 Tag 检索专辑
+
+通过 Tag 检索归属于该 Tag 下的专辑列表。
+
+该接口属于检索接口，标签使用「向上合并」的语义。即计算专辑标签时，需要取专辑内所有专辑标签、光盘标签和音轨标签的**并集**。具体定义见 [专辑信息 - 标签](../02.metadata-repository/02.album-information.md#标签)。
+
+#### Endpoint
+
+`GET /albums/by-tag`
+
+### 参数
+
+| 参数名      | 类型      | 说明                          |
+| ----------- | --------- | ----------------------------- |
+| `tag`       | `string`  | Tag 名                        |
+| `recursive` | `boolean` | 是否递归检索子 Tag 所包含专辑 |
+
+#### 返回
+
+`AlbumDetail[]`
+
+#### 错误列表
+
+| 错误代码 | 详情         |
+| -------- | ------------ |
+| `902000` | `Tag` 不存在 |
+
+### 获取 Tag 关系
+
+`GET /tag-graph`
+
+#### 返回
+
+返回 `tag` 依赖关系的邻接表，类型表示为 `Record<string, string[]>` 。
+
+`Key-Value` 对应的是标签与其所包含的子标签。字符串格式为 `<EDITION>:<NAME>`，标签类型不可省略。
+
+## 搜索
+
+### Endpoint
+
+`GET /search`
+
+### 请求参数
+
+| 参数名          | 类型     | 说明                     |
+| --------------- | -------- | ------------------------ |
+| `search_albums` | `bool`   | 是否搜索专辑             |
+| `search_tracks` | `bool`   | 是否搜索音轨             |
+| `keyword`       | `string` | 搜索关键字               |
+| `limit`         | `number` | 最多返回条目数           |
+| `offset`        | `number` | 跳过多少条记录，缺省为 0 |
+
+### 返回
+
+返回 `SearchResult` ，结果按 `score` 降序排序。
+
+#### 参数列表
+
+```ts
+interface Result<T> {
+  content: T;
+  // 归一化的 score ，必须为属于 [0, 100] 的浮点数
+  score: number;
+}
+
+interface SerachResult {
+  albums?: Result<AlbumDetail>[];
+  tracks?: Result<TrackInfoWithAlbum>[];
+}
+```

src/08.annim/02.backend.md

@@ -0,0 +1,7 @@
+# Annim 元数据后端
+
+Annim 不仅需要与客户端约定提供元数据的协议，也需要关于元数据来源的约定，这就是 Annim 元数据后端。
+
+## Git repo 后端
+
+使用 git 仓库作为元数据来源，仓库结构应符合[Anni 元数据仓库](../02.metadata-repository/00.readme.md)标准。

src/SUMMARY.md

@@ -52,7 +52,6 @@
   - [Annil Token 管理](./06.anniv/04.credential.md)
   - [信息导出格式](./06.anniv/07.export-format.md)
   - [专辑元数据](./06.anniv/08.meta.md)
-  - [搜索](./06.anniv/09.search.md)
   - [分享管理](./06.anniv/05.share.md)
   - [播放统计](./06.anniv/06.statistics.md)
   - [喜欢](./06.anniv/10.favorite.md)
@@ -62,6 +61,9 @@
     - [两步验证（2fa）](./06.anniv/features/02.2fa.md)
     - [禁止注册（close）](./06.anniv/features/03.close.md)
     - [预构建数据源（metadata-db）](./06.anniv/features/04.metadata-db.md)
+- [Annim 元数据服务](./08.annim/00.readme.md)
+  - [协议](./08.annim/01.protocol.md)
+  - [元数据后端](./08.annim/02.backend.md)
 - [Annisonic](./07.annisonic/00.readme.md)
   - [实现的 API](./07.annisonic/01.apis.md)
   - [已测试的客户端](./07.annisonic/02.clients.md)