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/09.search.md

@@ -6,12 +6,12 @@
 
 ## 请求参数
 
-| 参数名             | 类型     | 说明             |
-| ------------------ | -------- | ---------------- |
-| `search_albums`    | `bool`   | 是否搜索专辑     |
-| `search_tracks`    | `bool`   | 是否搜索音轨     |
-| `search_playlists` | `bool`   | 是否搜索播放列表 |
-| `keyword`          | `string` | 搜索关键字       |
+| 参数名             | 类型     | 说明                     |
+| ------------------ | -------- | ------------------------ |
+| `search_albums`    | `bool`   | **已弃用**，是否搜索专辑 |
+| `search_tracks`    | `bool`   | **已弃用**，是否搜索音轨 |
+| `search_playlists` | `bool`   | 是否搜索播放列表         |
+| `keyword`          | `string` | 搜索关键字               |
 
 ## 返回
 

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)标准。