Support actions in responses of post requests

kyubotics · Apr 1, 2017 · e99bf97 · e99bf97
1 parent 65bff6b
commit e99bf97
Show file tree

Hide file tree

Showing 3 changed files with 275 additions and 48 deletions.
diff --git a/docs/Post.md b/docs/Post.md
@@ -1,4 +1,4 @@
-# 上报数据格式
+# 事件上报
 
 ## 上报方式
 
@@ -13,7 +13,7 @@ Authorization: token kSLuTF2GC2Q4q4ugm3
 
 `kSLuTF2GC2Q4q4ugm3` 换成你填写的 token。
 
-## 数据格式
+## 上报数据格式
 
 每次上报的数据中必有的一个字段是 `post_type`，数据类型为字符串，用来指示此次上报的类型，有如下三种：
 
@@ -23,16 +23,40 @@ Authorization: token kSLuTF2GC2Q4q4ugm3
 | `event`   | 群、讨论组变动等非消息类事件 |
 | `request` | 加好友请求、加群请求／邀请  |
 
-其它字段随上报类型不同而有所不同，下面将一一给出。
+其它字段随上报类型不同而有所不同，下面将在事件列表的「上报数据」标题下一一给出。
 
-某些字段的值是一些固定的值，在「可能的值」中给出，如果「可能的值」为空则表示没有固定的可能性。
+某些字段的值是一些固定的值，在表格的「可能的值」中给出，如果「可能的值」为空则表示没有固定的可能性。
 
 另外，每一次上报都有一个 `time` 字段为事件发生的时间戳，数据类型为数字，下面不再列出。
 
+## 上报请求的响应数据格式
+
+从 1.1.0 版本开始支持在上报请求的响应中直接指定一些简单的操作。
+
+如果不需要使用这个特性，返回 HTTP 响应状态码 204，或保持响应正文内容为空；如果需要，则使用 JSON 作为响应正文，`Content-Type` 响应头任意（目前不会进行判断），但设置为 `application/json` 最好，以便减少不必要的升级成本，因为如果以后有需求，可能会加入判断。
+
+响应的 JSON 数据中，支持的操作随事件的不同而不同，会在后面的事件列表中的「响应数据」标题下一一给出。需要指出的是，**响应数据中的每个字段都是可选的**，只有在字段存在（明确要求进行操作）时，才会触发相应的操作，否则将保持对酷 Q 整体运行状态影响最小的行为（比如默认不拦截事件、不回复消息、不处理请求）。
+
+「响应数据」给出的表格中的「允许的值」表示该字段允许的数据值，如果你返回的值不在允许的值范围内，则会采用默认行为，「允许的值」为空表示不限制。
+
+每个事件都有一个共同的支持的操作，即 `block` 字段，数据类型为 boolean，`true` 表示拦截消息（不再让后面的插件处理），否则表示忽略（不拦截），例如：
+
+```json
+{"block": true}
+```
+
+如果你在处理上报请求时，返回上面的 JSON 作为响应，则优先级在酷 Q 之后的其它插件将不会再收到这个事件。
+
+此 `block` 字段后面不再列出。
+
+另外，`post_type` 为 `event` 的上报请求，都只支持响应 `block` 字段，而不支持其它操作。
+
 ## 事件列表
 
 ### 私聊消息
 
+#### 上报数据
+
 | 字段名            | 数据类型   | 可能的值                                     | 说明                                       |
 | -------------- | ------ | ---------------------------------------- | ---------------------------------------- |
 | `post_type`    | string | `"message"`                              | 上报类型                                     |
@@ -41,8 +65,16 @@ Authorization: token kSLuTF2GC2Q4q4ugm3
 | `user_id`      | number | -                                        | 发送者 QQ 号                                 |
 | `message`      | string | -                                        | 消息内容                                     |
 
+#### 响应数据
+
+| 字段名     | 数据类型   | 允许的值 | 说明     |
+| ------- | ------ | ---- | ------ |
+| `reply` | string | -    | 要回复的内容 |
+
 ### 群消息
 
+#### 上报数据
+
 | 字段名              | 数据类型   | 可能的值        | 说明                        |
 | ---------------- | ------ | ----------- | ------------------------- |
 | `post_type`      | string | `"message"` | 上报类型                      |
@@ -53,8 +85,19 @@ Authorization: token kSLuTF2GC2Q4q4ugm3
 | `anonymous_flag` | string | -           | 匿名用户 flag，在调用禁言 API 时需要传入 |
 | `message`        | string | -           | 消息内容                      |
 
+#### 响应数据
+
+| 字段名         | 数据类型    | 允许的值            | 说明                                       |
+| ----------- | ------- | --------------- | ---------------------------------------- |
+| `reply`     | string  | -               | 要回复的内容                                   |
+| `at_sender` | boolean | `true`, `false` | 是否要在回复开头 at 发送者（自动添加），默认为 `true`，发送者是匿名用户时无效 |
+| `kick`      | boolean | `true`, `false` | 把发送者踢出群组（需要登录号权限足够），**不拒绝**此人后续加群请求，默认为 `false`，发送者是匿名用户时无效 |
+| `ban`       | boolean | `true`, `false` | 把发送者禁言 30 分钟（需要登录号权限足够），对匿名用户也有效，不支持指定禁言时长（如需指定，请调用相应 API），默认为 `false` |
+
 ### 讨论组消息
 
+#### 上报数据
+
 | 字段名            | 数据类型   | 可能的值        | 说明       |
 | -------------- | ------ | ----------- | -------- |
 | `post_type`    | string | `"message"` | 上报类型     |
@@ -63,8 +106,17 @@ Authorization: token kSLuTF2GC2Q4q4ugm3
 | `user_id`      | number | -           | 发送者 QQ 号 |
 | `message`      | string | -           | 消息内容     |
 
+#### 响应数据
+
+| 字段名         | 数据类型    | 允许的值            | 说明                               |
+| ----------- | ------- | --------------- | -------------------------------- |
+| `reply`     | string  | -               | 要回复的内容                           |
+| `at_sender` | boolean | `true`, `false` | 是否要在回复开头 at 发送者（自动添加），默认为 `true` |
+
 ### 群管理员变动
 
+#### 上报数据
+
 | 字段名         | 数据类型   | 可能的值              | 说明                 |
 | ----------- | ------ | ----------------- | ------------------ |
 | `post_type` | string | `"event"`         | 上报类型               |
@@ -75,6 +127,8 @@ Authorization: token kSLuTF2GC2Q4q4ugm3
 
 ### 群成员减少
 
+#### 上报数据
+
 | 字段名           | 数据类型   | 可能的值                           | 说明                                       |
 | ------------- | ------ | ------------------------------ | ---------------------------------------- |
 | `post_type`   | string | `"event"`                      | 上报类型                                     |
@@ -86,6 +140,8 @@ Authorization: token kSLuTF2GC2Q4q4ugm3
 
 ### 群成员增加
 
+#### 上报数据
+
 | 字段名           | 数据类型   | 可能的值                   | 说明                         |
 | ------------- | ------ | ---------------------- | -------------------------- |
 | `post_type`   | string | `"event"`              | 上报类型                       |
@@ -97,6 +153,8 @@ Authorization: token kSLuTF2GC2Q4q4ugm3
 
 ### 好友已添加
 
+#### 上报数据
+
 | 字段名         | 数据类型   | 可能的值             | 说明         |
 | ----------- | ------ | ---------------- | ---------- |
 | `post_type` | string | `"event"`        | 上报类型       |
@@ -105,6 +163,8 @@ Authorization: token kSLuTF2GC2Q4q4ugm3
 
 ### 加好友请求
 
+#### 上报数据
+
 | 字段名            | 数据类型   | 可能的值        | 说明                         |
 | -------------- | ------ | ----------- | -------------------------- |
 | `post_type`    | string | `"request"` | 上报类型                       |
@@ -113,13 +173,29 @@ Authorization: token kSLuTF2GC2Q4q4ugm3
 | `message`      | string | -           | 验证信息                       |
 | `flag`         | string | -           | 请求 flag，在调用处理请求的 API 时需要传入 |
 
+#### 响应数据
+
+| 字段名       | 数据类型    | 允许的值            | 说明       |
+| --------- | ------- | --------------- | -------- |
+| `approve` | boolean | `true`, `false` | 是否同意请求   |
+| `remark`  | string  | -               | 添加后的好友备注 |
+
 ### 加群请求／邀请
 
+#### 上报数据
+
 | 字段名            | 数据类型   | 可能的值               | 说明                         |
 | -------------- | ------ | ------------------ | -------------------------- |
 | `post_type`    | string | `"request"`        | 上报类型                       |
 | `request_type` | string | `"group"`          | 请求类型                       |
 | `sub_type`     | string | `"add"`、`"invite"` | 请求子类型，分别表示加群请求、邀请登录号入群     |
 | `user_id`      | number | -                  | 发送请求的 QQ 号                 |
 | `message`      | string | -                  | 验证信息                       |
-| `flag`         | string | -                  | 请求 flag，在调用处理请求的 API 时需要传入 |
+| `flag`         | string | -                  | 请求 flag，在调用处理请求的 API 时需要传入 |
+
+#### 响应数据
+
+| 字段名       | 数据类型    | 允许的值            | 说明        |
+| --------- | ------- | --------------- | --------- |
+| `approve` | boolean | `true`, `false` | 是否同意请求／邀请 |
+| `remark`  | string  | -               | 拒绝理由      |
diff --git a/io.github.richardchien.coolqhttpapi.json b/io.github.richardchien.coolqhttpapi.json
@@ -5,8 +5,8 @@
   "ret": 1, // 返回码，固定为1
   "apiver": 9, // Api版本，本SDK为9
   "name": "HTTP API", // 应用名称
-  "version": "1.0.5", // 应用版本
-  "version_id": 9, // 应用顺序版本（每次发布时至少+1）
+  "version": "1.1.0", // 应用版本
+  "version_id": 10, // 应用顺序版本（每次发布时至少+1）
   "author": "Richard Chien", // 应用作者
   "description": "使酷 Q 支持通过 HTTP 上报事件信息及调用接口",
   "event": [// 事件列表，同一事件类型可重复定义（发布前请删除无用事件）
@@ -15,90 +15,90 @@
       "type": 21, // 事件类型
       "name": "私聊消息处理", // 事件名称
       "function": "_eventPrivateMsg", // 事件对应函数
-      "priority": 30000 // 事件优先级(参见 cqp.im/deveventpriority)
+      "priority": 20000 // 事件优先级(参见 cqp.im/deveventpriority)
     },
     {
       "id": 2,
       "type": 2,
       "name": "群消息处理",
       "function": "_eventGroupMsg",
-      "priority": 30000
+      "priority": 20000
     },
     {
       "id": 3,
       "type": 4,
       "name": "讨论组消息处理",
       "function": "_eventDiscussMsg",
-      "priority": 30000
+      "priority": 20000
     },
     {
       "id": 5,
       "type": 101,
       "name": "群管理变动事件处理",
       "function": "_eventSystem_GroupAdmin",
-      "priority": 30000
+      "priority": 20000
     },
     {
       "id": 6,
       "type": 102,
       "name": "群成员减少事件处理",
       "function": "_eventSystem_GroupMemberDecrease",
-      "priority": 30000
+      "priority": 20000
     },
     {
       "id": 7,
       "type": 103,
       "name": "群成员增加事件处理",
       "function": "_eventSystem_GroupMemberIncrease",
-      "priority": 30000
+      "priority": 20000
     },
     {
       "id": 10,
       "type": 201,
       "name": "好友已添加事件处理",
       "function": "_eventFriend_Add",
-      "priority": 30000
+      "priority": 20000
     },
     {
       "id": 8,
       "type": 301,
       "name": "好友添加请求处理",
       "function": "_eventRequest_AddFriend",
-      "priority": 30000
+      "priority": 20000
     },
     {
       "id": 9,
       "type": 302,
       "name": "群添加请求处理",
       "function": "_eventRequest_AddGroup",
-      "priority": 30000
+      "priority": 20000
     },
     {
       "id": 1001,
       "type": 1001,
       "name": "酷Q启动事件",
-      "priority": 30000,
+      "priority": 20000,
       "function": "_eventStartup"
     },
     {
       "id": 1002,
       "type": 1002,
       "name": "酷Q关闭事件",
-      "priority": 30000,
+      "priority": 20000,
       "function": "_eventExit"
     },
     {
       "id": 1003,
       "type": 1003,
       "name": "应用已被启用",
-      "priority": 30000,
+      "priority": 20000,
       "function": "_eventEnable"
     },
     {
       "id": 1004,
       "type": 1004,
       "name": "应用将被停用",
-      "priority": 30000,
+      "priority": 20000,
       "function": "_eventDisable"
     }
   ],