补全文档

README.md

@@ -1,5 +1,59 @@
 # EdgeManager（SCADA系统）
 
+- [EdgeManager（SCADA系统）](#edgemanagerscada系统)
+  - [API](#api)
+    - [class `EDataCapture`](#class-edatacapture)
+  - [开发环境](#开发环境)
+  - [技术细节](#技术细节)
+    - [0. `EdgeManager\EDataCapture\EDataCapture -> set_data()`为什么是以`6507524`为大小chunked的？](#0-edgemanageredatacaptureedatacapture---set_data为什么是以6507524为大小chunked的)
+
+## API
+
+> API设计最大程度遵循了已有的MES规范。
+
+### class `EDataCapture`
+
+0. HTTP POST: `set_data`
+
+**请求**
+
+```json
+{
+    'action': 'set_data',
+    'param': {
+        'working_subclass': <string>,
+        'type': 'string' | 'int' | 'float' | 'bool',
+        'code': <string>,
+        // value的类型需与type对应
+        'value': <string | int | float | bool>,
+        'device_code': [string],
+        'batch': [string]
+    }
+}
+```
+
+**返回**
+
+操作成功：
+
+```json
+{
+    'action': 'result_set_data',
+    'errcode': 0,
+    'errmsg': ''
+}
+```
+
+操作失败：
+
+```json
+{
+    'action': 'result_set_data',
+    'errcode': 4002,
+    'errmsg': 'ROLLBACKed: Bad data received (structure and/or values)'
+}
+```
+
 ## 开发环境
 
 拉取代码：
@@ -26,4 +80,48 @@ docker exec -it edge_manager bash
 
 ```bash
 php EdgeManager.php --server_name=GPU-server-01 --user=postgres --password=big_dick start
-```
+```
+
+客户端连接：
+
+```bash
+sudo apt install postgresql-client
+# 登入
+psql -h localhost -U postgres
+# 显示数据库列表
+\l
+```
+
+## 技术细节
+
+### 0. `EdgeManager\EDataCapture\EDataCapture -> set_data()`为什么是以`6507524`为大小chunked的？
+
+首先明确一点，根据PostgreSQL的技术架构，条件允许的情况下，**一次性插入多条记录是效率最高的**。
+
+这其中，仅插入部分字段的值，比如：
+
+```sql
+INSERT INTO films (code, title, did, date_prod, kind)
+    VALUES ('T_601', 'Yojimbo', 106, '1961-06-16', 'Drama');
+```
+
+的效率又远远不如插入全部列，但使用特殊变量DEFAULT替代缺少的字段，比如：
+
+```sql
+INSERT INTO films VALUES
+    ('UA502', 'Bananas', DEFAULT, '1971-07-13', 'Comedy', '82 minutes');
+```
+
+PostgreSQL的文档里没有提及这个话题，因为源码里为SQL语句的内存分配[指定了一个最大长度常量`MaxAllocSize`](https://github.com/postgres/postgres/blob/2373fe78dfc9d4aa2348a86fffdf8eb9d757e9d5/src/common/stringinfo.c#L28)，其大小为比1GB小1字节。这个值可以在编译前手动修改，所以理论上每个PG运行的实例都可以不一样，如果我们使用的PG并非修改过源码手动编译的，那么SQL语句的最大长度为`1024 ** 3 - 1 = 1073741823` bytes。
+
+> 安全起见，下述计算假定working_subclass等字段的最大长度均为我们以往约定的45 bytes。
+
+而此处我源码中的SQL语句头长度为131 bytes（注意末尾空格）：
+
+![](imgs/sql_head.png)
+
+单个语句体的长度为165 bytes：
+
+![](imgs/sql_body.png)
+
+所以其最多可以一次性插入`(1073741823 - 131) / 165`条记录，向下取整后即为`6507524`。