[BE-324] DIFF 协议文档更新

shinnytech · Jun 4, 2020 · c772179 · c772179
1 parent 4d6da52
commit c772179
Show file tree

Hide file tree

Showing 6 changed files with 300 additions and 235 deletions.
diff --git a/funcset/mdhis.rst b/funcset/mdhis.rst
@@ -5,7 +5,7 @@
 
 请求订阅图表数据
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-终端通过发送 set_chart 包实现订阅图表数据
+终端通过发送 `set_chart` 包实现订阅图表数据
 
 .. code-block:: javascript
 
@@ -20,13 +20,13 @@
   
 需要注意几点:
 
-* chart_id 为一个任意字符串，当多次发送的set_chart包中的chart_id重复时，后一次的请求将覆盖前一次。chart_id不相同则视为不同的订阅
-* 历史数据服务是订阅式而非查询式的。只要发送过一次 set_chart 请求，每当行情变化时，都会通过 rtn_data 包推送新的K线，不需要多次发送 set_chart 包
+* `chart_id` 为一个任意字符串，当多次发送的 `set_chart` 包中的 `chart_id` 重复时，后一次的请求将覆盖前一次。`chart_id` 不相同则视为不同的订阅
+* 历史数据服务是订阅式而非查询式的。只要发送过一次 `set_chart` 请求，每当行情变化时，都会通过 `rtn_data` 包推送新的K线，不需要多次发送 `set_chart` 包
 
 
 图表数据同步
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-图表数据通过 `rtn_data` 包的 klines 字段和 ticks 字段进行差分发送, 如下所示:
+图表数据通过 `rtn_data` 包的 `klines` 字段和 `ticks` 字段进行差分发送, 如下所示:
 
 .. code-block:: javascript
 

diff --git a/funcset/notify.rst b/funcset/notify.rst
@@ -2,39 +2,40 @@
 
 通知
 ==================================================
-通知通过 `rtn_data` 包中的 notify 字段发送, 如下所示
+通知通过 `rtn_data` 包中的 `notify` 字段发送, 下面的 DIFF协议包为客户发送登录指令 ``{"aid": "req_login" ... }`` 后收到的通知。
 
 .. code-block:: javascript
 
   {
-    "aid": "rtn_data",                                        //数据推送
-    "data": [                                                 //diff数据数组, 一次推送中可能含有多个数据包
+    "aid": "rtn_data",                      //业务信息截面更新推送
+    "data": [                               //diff数据数组, 一次推送中可能含有多个数据包
       {
-        "notify": {                                           //通知信息
-          "2010": {
-            "type": "MESSAGE",                                //消息类型
-            "level": "INFO",                                  //消息等级
-            "code": 1000,                                     //消息代码
-            "content": "abcd",                                //消息正文
+        "notify": {                         //通知信息
+          "2020": {
+            "type": "MESSAGE",              //消息类型
+            "level": "INFO",                //消息等级
+            "code": 401,                    //消息代码
+            "content": "登录成功"             //消息正文
           }
-        },
+        }
       }
     ]
   }
 
+其中，消息类型 `type` 和 消息等级 `level` 字典定义如下表所示。消息代码 `code` 和 消息正文 `content` 由业务层确定。
 
-================= ================================================
-type              说明
-================= ================================================
-MESSAGE           content是一个短字符串，通常只有1行
-TEXT              content是一个长文本，通常有多行内容
-HTML              content为HTML格式
-================= ================================================
-
-================= ================================================
-level             信息等级
-================= ================================================
-INFO              普通消息
-WARNING           警告
-ERROR             错误
-================= ================================================
+================= ================= ================================================
+key               字典              说明
+================= ================= ================================================
+type              MESSAGE           content是一个短字符串，通常只有1行
+
+                  TEXT              content是一个长文本，通常有多行内容
+
+                  HTML              content为HTML格式
+----------------- ----------------- ------------------------------------------------
+level             INFO              普通消息
+
+                  WARNING           警告
+
+                  ERROR             错误
+================= ================= ================================================
diff --git a/funcset/quote.rst b/funcset/quote.rst
@@ -3,29 +3,52 @@
 行情报价数据
 ==================================================
 
+::
+
+    client                                        server
+       +                                             +
+       |  {"aid": "subscribe_quote","ins_list": ..}  |
+       +-------------------------------------------->+
+       |                                             |
+       |  {"aid": "peek_message"}                    |
+       +-------------------------------------------->+
+       |                                             |
+       |                                             |
+       |  {"aid":"rtn_data",                         |
+       |  "data":[{"quotes":{...}]}                  |
+       +<--------------------------------------------+
+       |                                             |
+       |                                             |
+       +                                             +
+
+行情报价订阅流程如上
+
+1. 客户端发起请求订阅行情报价
+2. 客户端发送截面更新请求
+3. 服务端推送行情报价更新截面
+
 请求订阅行情报价
 --------------------------------------------------
-终端通过发送 subscribe_quote 包实现订阅行情报价
+终端通过发送 `subscribe_quote` 指令包实现行情报价的订阅
 
 .. code-block:: javascript
 
   {
-    "aid": "subscribe_quote",       //必填, 请求订阅实时报价数据
+    "aid": "subscribe_quote",                  //必填, 请求订阅实时报价数据
     "ins_list": "SHFE.cu1612,CFFEX.IF1701",    //必填, 需要订阅的合约列表，以逗号分隔
   }
 
   
 需要注意几点:
 
-* 合约代码必须带交易所代码, 例如cu1801应该写作 SHFE.cu1801. 目前支持的交易所为 CFFEX, SHFE, DCE, CZCE, INE
-* 用户自定义的组合, 交易所代码都为 USER
+* 合约代码必须带交易所代码，例如 `cu1801` 应该写作 `SHFE.cu1801`。目前支持的交易所为 ``CFFEX``, ``SHFE``, ``DCE``, ``CZCE``, ``INE``
+* 用户自定义的组合，交易所代码都为 `USER`
 * 合约代码及交易所代码都是大小写敏感的
-* 每次发送 subscribe_quote 时，应在 ins_list 中列出所有需要订阅的合约代码。多次发送 subscribe_quote，后一次的订阅列表会覆盖前一次的
-
+* 每次发送 `subscribe_quote` 时，应在 `ins_list` 中列出所有需要订阅的合约代码。多次发送 `subscribe_quote`，后一次的订阅列表会覆盖前一次的
 
 行情报价数据同步
 --------------------------------------------------
-行情报价数据通过 `rtn_data` 包的 quotes 字段进行差分发送, 如下所示:
+行情报价数据通过 `rtn_data` 包的 `quotes` 字段进行差分发送, 如下所示:
 
 .. code-block:: javascript