doc: upload guild api doc

docs/guild.md

@@ -0,0 +1,221 @@
+# 频道相关API
+
+> 注意: QQ频道功能目前还在测试阶段, go-cqhttp 也在适配的初期阶段, 以下 `API` `Event` 的字段名可能存在错误并均有可能在后续版本修改/添加/删除.
+> 目前仅供开发者测试以及适配使用
+
+QQ频道相关功能的事件以及API
+
+## 命名说明
+
+API以及字段相关命名均为参考QQ官方命名或相似产品命名规则, 由于QQ频道的账号系统独立于QQ本体, 所以各个 `ID` 并不能和QQ通用.也无法通过 `tiny_id` 获取到 `QQ号`
+
+下表为常见字段命名说明
+
+| 命名         | 说明                 |
+| ------------ | -------------------- |
+| `tiny_id`    | 在频道系统中代表用户ID, 与QQ号并不通用 |
+| `guild_id`   | 频道ID               |
+| `channel_id` | 子频道ID             |
+
+> 所有频道相关事件的 `user_id` 均为 `tiny_id`
+
+## 特殊说明
+
+- 由于频道的限制, 目前无法通过图片摘要查询到频道图片消息的详细信息, 所以通过频道消息收到的图片均会下载完整文件到 `images/guild-images`. (群图片转发不受此限制)
+- 由于无法通过 `GlobalID` 放下频道消息的ID, 所以所有频道消息的 `message_id` 均为 `string` 类型
+- `send_msg` API将无法发送频道消息
+- `get_msg` API暂时无法获取频道消息
+- `at` `reply` 等消息暂不支持解析
+- 所有事件的 `self_id` 均为 BOT 的QQ号. `tiny_id` 将放在 `self_tiny_id` 字段
+
+## API
+
+### 获取频道系统内BOT的资料
+
+终结点: `/get_guild_service_profile`
+
+**响应数据**
+
+| 字段          | 类型  | 说明       |
+| ------------- | ----- | ---------- |
+| `nickname`    | string | 昵称      |
+| `tiny_id`     | uint64 | 自身的ID   |
+| `avatar_url`  | string | 头像链接   |
+
+### 获取频道列表
+
+终结点: `/get_guild_list`
+
+**响应数据**
+
+正常情况下响应 `GuildInfo` 数组, 未加入任何频道响应 `null`
+
+GuildInfo:
+
+| 字段          | 类型  | 说明       |
+| ------------- | ----- | ---------- |
+| `guild_id`    | uint64 | 频道ID      |
+| `guild_name`     | string | 频道名称   |
+| `guild_display_id`  | int64 | 频道显示ID, 公测后可能作为搜索ID使用  |
+
+### 通过访客获取频道元数据
+
+终结点: `/get_guild_meta_by_guest`
+
+**参数**
+
+| 字段       | 类型  | 说明 |
+| ---------- | ----- | ---- |
+| `guild_id` | uint64 | 频道ID |
+
+**响应数据**
+
+| 字段          | 类型  | 说明       |
+| ------------- | ----- | ---------- |
+| `guild_id`    | uint64 | 频道ID      |
+| `guild_name`     | string | 频道名称   |
+| `guild_profile`  | string | 频道简介  |
+| `create_time`  | int64 | 创建时间  |
+| `max_member_count`  | int64 | 频道人数上限  |
+| `max_robot_count`  | int64 | 频道BOT数上限  |
+| `max_admin_count`  | int64 | 频道管理员人数上限  |
+| `member_count`  | int64 | 已加入人数  |
+| `owner_id`  | uint64 | 创建者ID  |
+
+### 获取子频道列表
+
+终结点: `/get_guild_channel_list`
+
+**参数**
+
+| 字段       | 类型  | 说明 |
+| ---------- | ----- | ---- |
+| `guild_id` | uint64 | 频道ID |
+| `no_cache` | bool  | 是否无视缓存 |
+
+**响应数据**
+
+正常情况下响应 `ChannelInfo` 数组, 未找到任何子频道响应 `null`
+
+ChannelInfo:
+
+| 字段          | 类型  | 说明       |
+| ------------- | ----- | ---------- |
+| `owner_guild_id`    | uint64 | 所属频道ID      |
+| `channel_id`     | uint64 | 子频道ID   |
+| `channel_type`     | int32 | 子频道类型   |
+| `channel_name`  | string | 之频道名称  |
+| `create_time`  | int64 | 创建时间  |
+| `creator_id`  | int64 | 创建者QQ号  |
+| `creator_tiny_id`  | uint64 | 创建者ID  |
+| `talk_permission`  | int32 | 发言权限类型  |
+| `visible_type`  | int32 | 可视性类型  |
+| `current_slow_mode`  | int32 | 当前启用的慢速模式Key  |
+| `slow_modes`  | []SlowModeInfo | 频道内可用慢速模式类型列表|
+
+SlowModeInfo:
+
+| 字段          | 类型  | 说明       |
+| ------------- | ----- | ---------- |
+| `slow_mode_key`    | int32 | 慢速模式Key   |
+| `slow_mode_text`     | string | 慢速模式说明   |
+| `speak_frequency`  | int32 | 周期内发言频率限制  |
+| `slow_mode_circle`  | int32 | 单位周期时间, 单位秒 |
+
+已知子频道类型列表
+
+| 类型          |  说明       |
+| ------------- | ---------- |
+| 1    | 文字频道  |
+| 2     | 语音频道  |
+| 5  |  直播频道  |
+
+### 获取频道成员列表
+
+终结点: `/get_guild_members`
+
+**参数**
+
+| 字段       | 类型  | 说明 |
+| ---------- | ----- | ---- |
+| `guild_id` | uint64 | 频道ID |
+
+**响应数据**
+
+> 注意: 类型内无任何成员将返回 `null`
+
+| 字段          | 类型  | 说明       |
+| ------------- | ----- | ---------- |
+| `members`    | []GuildMemberInfo | 普通成员列表      |
+| `bots`     | []GuildMemberInfo | 机器人列表  |
+| `admins`  | []GuildMemberInfo | 管理员列表  |
+
+GuildMemberInfo:
+
+| 字段          | 类型  | 说明       |
+| ------------- | ----- | ---------- |
+| `tiny_id`    | uint64 | 成员ID      |
+| `title`     | string | 成员头衔 |
+| `nickname`  | string | 成员昵称  |
+| `role`  | int32 | 成员权限  |
+
+### 发送信息到子频道
+
+终结点: `/send_guild_channel_msg`
+
+**参数**
+
+| 字段       | 类型  | 说明 |
+| ---------- | ----- | ---- |
+| `guild_id` | uint64 | 频道ID |
+| `channel_id` | uint64 | 子频道ID |
+| `message` | Message | 消息, 与原有消息类型相同 |
+
+**响应数据**
+
+| 字段          | 类型  | 说明       |
+| ------------- | ----- | ---------- |
+| `message_id`    | string | 消息ID     |
+
+## 事件
+
+### 收到频道消息
+
+**上报数据**
+
+| 字段          | 类型   | 可能的值       | 说明           |
+| ------------- | ------ | -------------- | -------------- |
+| `post_type`   | string | `message`       | 上报类型       |
+| `message_type` | string | `guild` | 消息类型       |
+| `sub_type` | string | `channel` | 消息子类型       |
+| `guild_id`    | uint64  |                | 频道ID           |
+| `channel_id`    | uint64  |                | 子频道ID           |
+| `user_id`     | uint64  |                | 消息发送者ID   |
+| `message_id`     | string  |                | 消息ID  |
+| `sender`     | Sender  |                | 发送者  |
+| `message`     | Message  |                | 消息内容  |
+
+### 频道消息表情贴更新
+
+**上报数据**
+
+| 字段          | 类型   | 可能的值       | 说明           |
+| ------------- | ------ | -------------- | -------------- |
+| `post_type`   | string | `notice`       | 上报类型       |
+| `notice_type` | string | `message_reactions_updated` | 消息类型       |
+| `guild_id`    | uint64  |                | 频道ID           |
+| `channel_id`    | uint64  |                | 子频道ID           |
+| `user_id`     | uint64  |                | 操作者ID  |
+| `message_id`     | string  |                | 消息ID  |
+| `current_reactions`     | []ReactionInfo  |                | 当前消息被贴表情列表  |
+
+ReactionInfo:
+
+| 字段       | 类型  | 说明 |
+| ---------- | ----- | ---- |
+| `emoji_id` | string | 表情ID |
+| `emoji_index` | int32 | 表情对应数值ID |
+| `emoji_type` | int32 | 表情类型 |
+| `emoji_name` | string | 表情名字 |
+| `count` | int32 | 当前表情被贴数量 |
+| `clicked` | bool | BOT是否点击 |