udms/sync_mysql_new.md

+# MySQL通用入库模块
+
+本模块用于一般的数据入MySql数据库的操作。目前支持以下几种操作
+* insert 
+* update
+* upsert
+* delete
+
+本模块需要根据所传入的数据类型及要求执行的操作，向预先定义的数据库中
+执行相应的数据库操作。模块能够正确执行数据库操作依赖以下前提：
+1. 数据本身或模块配置中，指明了传入数据为何种数据类型
+2. 数据本身或模块配置中，指明了应该执行何种数据库操作(insert/update/upsert/delete)
+2. 当前模块配置指明了特定数据类型所对应的数据库及表
+
+## 约定
+本文档中配置或数据示例中，对于dict类型的key的名字，可能存在系统预定义的内容和用户定义的内容。
+为了以示区分，所有用户自定义的内容均以<>引用。如以下内容
+
+```
+{
+    "<field1>": "value", //要入库的具休数据
+    "<field2>": "value",
+    
+    ...
+    
+    "sync_condition": {  //入库操作及数据类型声明
+        "operation": "upsert",
+        "data_type": "test_ic",
+    }
+}
+```
+* field1。field2均为用户的内容。
+* sync_condition, operation, data_type 为本模块定义的内容。
+
+**使用尖括号只是为了在文档中加以区分，并非实际应用中需要这样做。**
+
+## 1. 传入的数据
+传入数据可以声明当前数据的数据类型(data_type)及希望执行的操作(operation)。
+前续模块可以通过在数据中加入如下内容来实现这个目的。
+
+```json
+{
+    "<field1>": "value", //要入库的具休数据
+    "<field2>": "value",
+    
+    ...
+    
+    "sync_condition": {  //入库操作及数据类型声明
+        "operation":"upsert",
+        "data_type": "test_ic",
+    }
+}
+```
+
+### 1.1 操作和数据类型声明 (sync_condition)
+
+#### 操作 (operation)
+|operation | 说明 |
+|----|----|
+| insert  | 插入操作 |
+| update  | 更新操作 |
+| upsert  | 不存在则insert 否则 update |
+| delete  | 删除操作 |
+
+#### update/upsert/delete 操作约束
+要支持这三种操作需具备以下条件：
+1. 数据库表上有主键和唯一键
+2. 传入的数据也指定了主键和唯一键
+
+例，数据库表如下
+
+|字段|说明|
+|----|----|
+|id | pk |
+|company_name_digest | uni index|
+|company_name |  |
+|company_type |  |
+|company_status |  |
+
+具体数据如下：
+
+|id |company_name_digest | company_name | company_status |
+|---- | ---- | ---- | ----|
+|1 |56a1254773711761 | 钦州全安劳务有限公司 | 正常 |
+|2 |5e802c8d9e473c01 | 凭安网络科技有限公司 | 正常 |
+
+如果要将 钦州全安劳务有限公司 的状态更新为 吊销 则需要转入如下数据:
+
+```json
+{
+    "<id>": 1,
+    "<company_status>": "吊销",
+    
+    "sync_condition": {
+        "operation":"update",
+    }
+}
+```
+
+或
+
+```json
+{
+    "<company_name_digest>": "5e802c8d9e473c01",
+    "<company_status>": "吊销",
+    "sync_condition": {
+        "operation":"update",
+    }
+}
+```
+
+因为，id和company_name_digest都能唯一确定这条数据。由此可以完成更新。
+
+
+#### 1.2 数据类型 data_type
+自定义的数据类型标识。该字段内空需要与模块中定义的data_type相对应。才能完成相应数据库操作。
+
+
+    注意：如果在数据中没有指定sync_condition，也可通过模块配置项
+     default_data_type和default_operation进行全局配置。但是在一个模块配置中只能
+     设置一个全局默认值。因此，这种方法只适用于处理单一数据类型的时候。
+     
+
+## 2. 模块配置
+模块的配置用于定义前续模块所传入的数据对应更新到哪个数据库的什么表中。
+这个定义通过一个两层结构来表达：
+
+  catalog --> data_type 
+  
+  * catalog   定义数据库连接参数
+  * data_type 定义某一种要处理的数据对应数据库里的一张或多张表
+  
+### catalog
+catalog 定义一个数据库连接。一个catalog中只能定义一种数据库连接参数。
+通常把使用的相同连接参数的data_type配置在一个catalog中。
+当然也可以根据需要放在多个catalog中。
+
+### data_type
+定义某一种要处理的数据。它与前续处理模块输出的数据类型相对应。
+这个数据类型通常是业务层面的一种数据。如，一条被执行人信息。
+通常这样一条业务数据以一个确定的JSON格式在数据系统中传递。
+但业务层面的一条数据在存储到数据库时，可能对应的是一张表也可能是多张表。
+而data_type的定义，就是指明入库模块收到的某一种数据类型所对应的数据库表是哪些。
+
+### default_data_type和default_operation
+当数据中没有指明数据类型或操作时。则默认使用这两项所设置的值。如果在数据中对data_type和
+operation进行了设置，则忽略该选项
+
+### table_explode   
+<!--FIXME 名字建议改一改。
+这个字段改为data_explode更为合理。因为这是对数据的操作，而非对表的操作
+解释用途, 提供样例
+-->
+table_explode中定义了要炸开数据
+    表table_b的b_list的字段在输入的一条数据上要炸开，table_b产生一变多的效果入库
+    表table_c的c_list的字段在输入的一条数据上要炸开，table_c产生一变多的效果入库   
+    
+### table_match   
+<!--FIXME 是正则表达式吗？-->
+<!--FIXME 名字建议改一改。
+这个功能是对输入的数据进行过滤。而不是针对表进行匹配。data_match 更为合理
+-->
+
+table_match中定义了数据要匹配正则表达式才可以入库：
+    table_b: "b1=='5' and b2=='5'", table_b要匹配正则才可以入库
+    table_c: ["c1=='5'", "c3=='4'"], table_c匹配list中任意一个正则就可以入库（正则之间或的关系）
+    
+### db_start_transaction:
+<!--TODO  解释用途, 提供样例-->
+db_start_transaction定义事务的级别信息，isolation_level: "READ COMMITTED"主要解决的INSERT INTO on duplicate key update
+会产生死锁的现象 
+
+### add_return_keys
+<!--TODO  解释用途,提供数据样例-->
+add_return_keys定义的返回的结果上需要新加一列，键名为company_name_digest
+
+
+## 3. 应用场景说明
+<!--TODO 举几个典型的应用场景的配置。内容包括：
+1. 场景的描述
+2. 配置样例
+3. 数据样例：输入的dict，及入库后的效果
+-->
+
+### 简单的单表入库
+
+### 多表事务事务入库
+
+### 一对多的主、子表展开入库
+
+### 为后续流程提供必要信息
+
+### 只对符合某些条件的数据进行操作(过滤)
+
+
+
+
+
+### 配置样例
+以下样例配置，定义了两个catalog：一个指向db_host1上的数据库database1，另一个指向
+db_host2上的database2。
+
+一个data_type=data_demo的doc入库时，
+    入table_a：doc不变，一对一入库
+    入table_b：doc除了b_list字段其他的不变，b_list要展开，一对多入库
+    入table_c：doc除了b_list字段其他的不变，c_list要展开，一对多入库
+    
+```yaml
+  default_data_type: "company_contact_details"
+  default_operation: "upsert"
+  catalogues:
+    - data_type:
+        - 'data_demo': ['table_a', 'table_b', 'table_c']
+      table_explode:
+        table_b: b_list
+        table_c: c_list
+      table_match:
+        table_b: "b1=='5' and b2=='5'"
+        table_c: ["c1=='5'", "c3=='4'"]
+      db_start_transaction:
+        consistent_snapshot: False
+        isolation_level: "READ COMMITTED"
+      add_return_keys:
+        - company_name_digest
+      db_connection:
+        user: "upc"
+        password: "upc@123"
+        host: "192.168.109.220"
+        port: "3306"
+        database: "data_test"
+      bulk: False