to version 0.02 (#5)

* init builtIn converter * split innerController * multi target `meta` support add doc * add /P /R metaType support * add conflict_avoid to MetaSetting MetaSetting support multi target `meta` * MetaSetting add meta_type property * Meta数据表：将Full_key进行拆分 * 移除 Meta::full_key 移除 MetaString * to chinese for demo * 完善 `concept` 的说明 * temp for README_ZH * fix demo for order-generate * finished demo for e-mall part 2 : pay for the order * finished demo for e-mall part 3 : outbound * finished demo for e-mall part 6 : auto sign * statistics temp * unify the version to 0.0.2 Co-authored-by: 李学斌 <lixuebin@cdeledu.com>
llxxbb · Mar 14, 2020 · 8351816 · 8351816
1 parent 253189e
commit 8351816
Show file tree

Hide file tree

Showing 33 changed files with 976 additions and 198 deletions.
diff --git a/.gitignore b/.gitignore
@@ -2,3 +2,4 @@
 **/*.rs.bk
 *.iml
 *.lock
+/.idea
diff --git a/Cargo.toml b/Cargo.toml
@@ -12,7 +12,7 @@ license = "MIT"
 
 [dependencies]
 nature_common = {path = "../Nature-Common", version="0.0.2"}
-nature_demo_common = {path = "../Nature-Demo-Common", version="0.1.0"}
+nature_demo_common = {path = "../Nature-Demo-Common", version="0.0.2"}
 
 serde_json = "1.0"
 serde = "1.0"

diff --git a/README.md b/README.md
@@ -1,40 +1,35 @@
-# A concrete example
-At here we would build an Online-Shop based on Nature.  The project will involves order, pay, warehouse and delivery domain. Don't worry about the complexity, we start at simple first, then step by step to achieve the final target. 
+# Nature 应用示例
+[English](README_EN.md)|中文
 
-Nature have provide all implement for this demo. you will find all of them in the following projects.
+如果你是第一次了解 Nature , 建议你从头到尾阅读这些 Demo。 每个章节都包含一些不同的 **Nature 要点**，以帮助你更好的了解 Nature 以及如何用 Nature 独有的方式来解决问题；同时阐述Nature 是如何简化技术性代码，使开发人员的聚焦于业务本身。下面为 Demo 相关的项目列表。
 
-- [test entry](https://github.com/llxxbb/Nature-Demo)
-- [common defines](https://github.com/llxxbb/Nature-Demo-Common)
-- [converter](https://github.com/llxxbb/Nature-Demo-Converter)
+- [示例的入口](https://github.com/llxxbb/Nature-Demo)
+- [服务于示例的一些通用封装](https://github.com/llxxbb/Nature-Demo-Common)
+- [示例项目的转换器实现](https://github.com/llxxbb/Nature-Demo-Converter)
+- [基于Restful的转换器实现](https://github.com/llxxbb/Nature-Demo-Converter-Restful)
 
-For the benefit of the simplicity, here use local-converter to instead of http based converter.
+如何启动 Nature 项目请参考：[项目准备](doc/unfinished/prepare.md)
 
-## How to read it
+## 网上商城 DEMO
 
-If you are the first time to know Nature,  It's best to read it from top to bottom.
+这个Demo涉及的场景比较多，如订单，支付，库房，配送以及多维度的销售统计等。
 
-In the whole demo description. there are some sections titled with **"Nature key points"** that would mind your attention how to do the thing in Nature way.
+这并不是一个完整的用于实际生产的例子，我们只关注业务核心逻辑。
 
-## Let‘s begin
+| 章节                                               | 内容摘要                                   | Nature 要点                                                  |
+| -------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------ |
+| [生成订单](doc/ZH/emall/emall-1-order-generate.md) | 用户向 Nature 提交一个订单                 | `Meta`, master `meta`, target-state, `Converter` ，提交`Instance`到Nature。 |
+| [支付订单](doc/ZH/emall/emall-2-pay-the-bill.md)   | 用户可以对一个金额比较大的订单进行多次支付 | 选择上游，上下文（sys.target）, 并发冲突控制                 |
+| [出库](doc/ZH/emall/emall-3-stock-out.md)          | 库房的系统比较老旧，处理订单比较慢         | 提交`state-instance` ，回调，与已有系统的对接。              |
+| [配送](doc/ZH/emall/emall-4-delivery.md)           | 和第三方协作                               | 参数化输入                                                   |
+| [签收](doc/ZH/emall/emall-5-signed.md)             | 用户接收了订单中的货物                     | 延迟转换                                                     |
 
-| chapter                                 | digest                                                    | key points                                                   |
-| --------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------ |
-| [prepare](doc/prepare.md)               | prepare for the demo                                      | how to run Nature                                            |
-| [generate order](doc/order-generate.md) | user commit an order into to Nature                       | `Meta`, master `meta`, define target-state, `Converter`  and how to commit business object to Nature |
-| [pay for the bill](doc/pay-the-bill.md) | user can pay many times for the big bill.                 | upstream select, state conflict control                      |
-| [stock-out](doc/stock-out.md)           | the warehouse system is slow to process the order's goods | input state instance, callback                               |
-| [delivery](doc/delivery.md)             | collaborate with the third-party                          | parameterization input                                       |
-| [signed](doc/signed.md)                 | user received the goods                                   | delay converter                                              |
-
-
-The following unfinished yet.
-
-| chapter       | digest                                                  | key points                      |
-| ------------- | ------------------------------------------------------- | ------------------------------- |
-| e-book        | extend category with need not delivery but can download | context                         |
-| logistic bill | one order split into many logistic bill                 | user appointed id,  grey deploy |
-
-[Q&A](doc/q&a.md)
+## 统计DEMO
 
+可以把Nature 看做一个简单的流式统计框架。
 
+| chapter                                 | digest                                                       | key points                                |
+| --------------------------------------- | ------------------------------------------------------------ | ----------------------------------------- |
+| [sale statistics](doc/ZH/emall/emall-6-statistics.md) | from goods view, make statistics freely, extensible, no coding. | context, embedded counter, serial process |
+| user consumption data                   | make data which can be got by user id, such as order list    | parallel process                          |
 
diff --git a/README_EN.md b/README_EN.md
@@ -0,0 +1,46 @@
+# A concrete example
+
+English|[中文](README.md)
+
+At here we would build an Online-Shop based on Nature.  The project will involves order, pay, warehouse and delivery domain. Even more we make some statistics through multi-dimensions. 
+
+Don't worry about the complexity, we start at simple first, then step by step to achieve the final target.  Even thou I think the code lines are great reduced compare to the traditional development, conservative estimate they are less than half.
+
+## How to read it
+
+If you are the first time to know Nature,  It's best to view this demo from top to bottom.
+
+Each chapter include little key-points of Nature, this let you come to know Nature.
+
+In the whole demo description. there are some sections titled with **"Nature key points"** that would mind your attention how to do the thing in Nature way.
+
+## Demo projects
+
+Nature have provide all implement for this demo. you will find all of them in the following projects.
+
+- [test entry](https://github.com/llxxbb/Nature-Demo)
+- [common defines](https://github.com/llxxbb/Nature-Demo-Common)
+- [converter](https://github.com/llxxbb/Nature-Demo-Converter)
+- [restful-converter](https://github.com/llxxbb/Nature-Demo-Converter-Restful)
+
+## Let‘s begin
+
+| chapter                                 | digest                                                    | key points                                                   |
+| --------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------ |
+| [prepare](doc/EN/prepare.md)               | prepare for the demo                                      | how to run Nature                                            |
+| [generate order](doc/EN/emall/emall-1-order-generate.md) | user commit an order into to Nature                       | `Meta`, master `meta`, define target-state, `Converter`  and how to commit business object to Nature |
+| [pay for the bill](doc/EN/emall/emall-2-pay-the-bill.md) | user can pay many times for the big bill.                 | upstream select, state conflict control                      |
+| [stock-out](doc/EN/emall/emall-3-stock-out.md)           | the warehouse system is slow to process the order's goods | input state instance, callback                               |
+| [delivery](doc/EN/emall/emall-4-delivery.md)             | collaborate with the third-party                          | parameterization input                                       |
+| [signed](doc/EN/emall/emall-5-signed.md)                 | user received the goods                                   | delay converter                                              |
+
+
+The following unfinished yet.
+
+| chapter                              | digest                                                       | key points                                |
+| ------------------------------------ | ------------------------------------------------------------ | ----------------------------------------- |
+| [sale statistics](doc/EN/emall/emall-6-statistics.md) | from goods view, make statistics freely, extensible, no coding. | context, embedded counter, serial process |
+| user consumption data                | make data which can be got by user id, such as order list    | parallel process                          |
+
+
+
diff --git a/doc/order-generate.md → doc/EN/emall/emall-1-order-generate.md b/doc/order-generate.md → doc/EN/emall/emall-1-order-generate.md
@@ -8,18 +8,18 @@ We suppose the user have goods selected, and use it to generate an order.
 
 First we will define two `meta`s. please insert the follow data to nature.sqlite. 
 
-- /B/sale/order: includes normal order properties.
+- B:sale/order: includes normal order properties.
 
-- /B/sale/orderState: the status for new, paid, outbound, dispatching, signed etcetera.
+- B:sale/orderState: the status for new, paid, outbound, dispatching, signed etcetera.
 
 ```sqlite
 INSERT INTO meta
 (full_key, description, version, states, fields, config)
-VALUES('/B/sale/order', 'order', 1, '', '', '{}');
+VALUES('B:sale/order', 'order', 1, '', '', '{}');
 
 INSERT INTO meta
 (full_key, description, version, states, fields, config)
-VALUES('/B/sale/orderState', 'order state', 1, 'new|paid|package|outbound|dispatching|signed|canceling|canceled', '', '{"master":"/B/sale/order:1"}');
+VALUES('B:sale/orderState', 'order state', 1, 'new|paid|package|outbound|dispatching|signed|canceling|canceled', '', '{"master":"B:sale/order:1"}');
 ```
 
 ### Nature key points
@@ -28,7 +28,7 @@ In tradition design, order and order state will be fill into one table, in this
 
 mutex state are separated by "|". 
 
-`master` means if you did not appoint a `executor` for `orderState`,  Nature will give a default conversion with empty body, and it's id will be same as `/B/sale/order`. You will see a `converter` that need a implement in the next chapter.
+`master` means if you did not appoint a `executor` for `orderState`,  Nature will give a default conversion with empty body, and it's id will be same as `B:sale/order`. You will see a `converter` that need a implement in the next chapter.
 
 ## Define `converter`
 
@@ -37,7 +37,7 @@ When we input an `Order` from outside, we set a `new` state for this order by co
 ```sqlite
 INSERT INTO relation
 (from_meta, to_meta, settings)
-VALUES('/B/sale/order:1', '/B/sale/orderState:1', '{"target_states":{"add":["new"]}}');
+VALUES('B:sale/order:1', '/B/sale/orderState:1', '{"target_states":{"add":["new"]}}');
 ```
 
 Let's see some explanation:

diff --git a/doc/pay-the-bill.md → doc/EN/emall/emall-2-pay-the-bill.md b/doc/pay-the-bill.md → doc/EN/emall/emall-2-pay-the-bill.md
diff --git a/doc/stock-out.md → doc/EN/emall/emall-3-stock-out.md b/doc/stock-out.md → doc/EN/emall/emall-3-stock-out.md
@@ -14,7 +14,7 @@ Another thing is, a warehouse process `stock-out-application` instead of `order`
 -- orderState:paid --> orderState:package
 INSERT INTO relation
 (from_meta, to_meta, settings)
-VALUES('/B/sale/orderState:1', '/B/sale/orderState:1', '{"selector":{"source_state_include":["paid"]},"executor":[{"protocol":"http","url":"http://localhost:8082/send_to_warehouse"}],"target_states":{"add":["package"]}}');
+VALUES('B:sale/orderState:1', 'B:sale/orderState:1', '{"selector":{"source_state_include":["paid"]},"executor":[{"protocol":"http","url":"http://localhost:8082/send_to_warehouse"}],"target_states":{"add":["package"]}}');
 ```
 
 ### Nature key points

diff --git a/doc/delivery.md → doc/EN/emall/emall-4-delivery.md b/doc/delivery.md → doc/EN/emall/emall-4-delivery.md
@@ -9,7 +9,7 @@ The problem is that we want to query express info by waybill id, and we do not w
 ```sqlite
 INSERT INTO meta
 (full_key, description, version, states, fields, config)
-VALUES('/B/third/waybill', 'waybill', 1, '', '', '{}');
+VALUES('B:third/waybill', 'waybill', 1, '', '', '{}');
 ```
 
 ## Define converter
@@ -18,12 +18,12 @@ VALUES('/B/third/waybill', 'waybill', 1, '', '', '{}');
 -- orderState:outbound --> waybill
 INSERT INTO relation
 (from_meta, to_meta, settings)
-VALUES('/B/sale/orderState:1', '/B/third/waybill:1', '{"selector":{"source_state_include":["outbound"]}, "executor":[{"protocol":"localRust","url":"nature_demo_converter.dll:go_express"}]}');
+VALUES('B:sale/orderState:1', 'B:third/waybill:1', '{"selector":{"source_state_include":["outbound"]}, "executor":[{"protocol":"localRust","url":"nature_demo_converter.dll:go_express"}]}');
 
 -- waybill --> orderState:dispatching
 INSERT INTO relation
 (from_meta, to_meta, settings)
-VALUES('/B/third/waybill:1', '/B/sale/orderState:1', '{"target_states":{"add":["dispatching"]}}');
+VALUES('B:third/waybill:1', 'B:sale/orderState:1', '{"target_states":{"add":["dispatching"]}}');
 ```
 
 ## Converter Implement

diff --git a/doc/signed.md → doc/EN/emall/emall-5-signed.md b/doc/signed.md → doc/EN/emall/emall-5-signed.md
@@ -9,7 +9,7 @@ For our benefit, we make fortnight to 1 seconds, so that you can see the result
 ```sqlite
 INSERT INTO meta
 (full_key, description, version, states, fields, config)
-VALUES('/B/sale/orderSign', 'order finished', 1, '', '', '{}');
+VALUES('B:sale/orderSign', 'order finished', 1, '', '', '{}');
 ```
 
 ## Define converter
@@ -18,12 +18,12 @@ VALUES('/B/sale/orderSign', 'order finished', 1, '', '', '{}');
 -- orderState:dispatching --> orderSign
 INSERT INTO relation
 (from_meta, to_meta, settings)
-VALUES('/B/sale/orderState:1', '/B/sale/orderSign:1', '{"delay":1,"selector":{"source_state_include":["dispatching"]}, "executor":[{"protocol":"localRust","url":"nature_demo_converter.dll:auto_sign"}]}');
+VALUES('B:sale/orderState:1', 'B:sale/orderSign:1', '{"delay":1,"selector":{"source_state_include":["dispatching"]}, "executor":[{"protocol":"localRust","url":"nature_demo_converter.dll:auto_sign"}]}');
 
 -- orderSign --> orderState:signed
 INSERT INTO relation
 (from_meta, to_meta, settings)
-VALUES('/B/sale/orderSign:1', '/B/sale/orderState:1', '{"target_states":{"add":["signed"]}}');
+VALUES('B:sale/orderSign:1', 'B:sale/orderState:1', '{"target_states":{"add":["signed"]}}');
 ```
 
 ### Nature key points

diff --git a/doc/EN/emall/emall-6-statistics.md b/doc/EN/emall/emall-6-statistics.md
@@ -0,0 +1,65 @@
+# Statistics
+
+After paid we want to make statistics for the products, and analysis them by multi-dimensions, but we are lazy to writing the code. Luckily Nature can do that for you.
+
+## Define `meta`
+
+```sqlite
+INSERT INTO meta
+(full_key, description, version, states, fields, config)
+VALUES('M:statistics/orderTask', 'total sold every hour', 1, '', '', '{"multi_meta":{"keys":["minute","hour"]}, "conflict_avoid": true}');
+```
+
+### how to make statistics
+
+If we we increase the counter for every order use `state-instance`, there would be many conflicts for high parallel process, and another question is that we would generated great volume of `state-instace`, so it's a terrible thing. 
+
+There is a way to do it is that we count it every minute for minute data and every hour for hour data. to do that we should generate one none state task-instance for every minute and one for every hour. 
+
+### Nature key points
+
+**"M"** `metaType` : express `multi-meta ` which will be processed parallelly, each key is defined in the `multi_meta.keys` property. For this demo, after converted Nature will save two instances.
+
+```
+B:statistics/orderTask/minute with para: current minute
+B:statistics/orderTask/hour with para: current hour
+```
+
+**"conflict_avoid"** setting tell Nature that the same instances will generated many times and Nature should cache it and check it befor save. If `false`(default) is set would lead to a large number of duplicated insertions. so the performance would be very bad.
+
+## Define converter
+
+```sqlite
+-- orderState:paid --> task
+INSERT INTO relation
+(from_meta, to_meta, settings)
+VALUES('B:sale/orderState:1', 'M:statistics/orderTask:1', '{"selector":{"source_state_include":["paid"]},"executor":[{"protocol":"localRust","url":"nature_demo_converter.dll:statistics_task"}]}');
+```
+
+
+
+## unready
+
+why delay 70 seconds? 
+
+## 
+
+### Questions
+
+There is a question, how to identify each inputted data for `consume/input`? used Nature generated instance id? no, it's hard to query it out, so we use parameterize instance technology in this converter.
+
+update the stateful-counter is a big bottleneck problem for busy system,  so we use Nature's `delay` technology and stateless `meta` to hold every past minute data. You can form you hour data, day data and any wide range data through this mechanism, but in this demo we stopped at minute data, It's enough for you to understand how to use Nature for statistics effectively.
+
+### Nature key points
+
+Another question is how to give multi-dimensions info to the following converter?,  sealed it to the `Instance.content` property? This is not a good idea, because `content`'s structure must be resolved by code! that is not we wanted. `context` will face on this problem. here we just used them in converter settings, no coding! (of course you can use `context` in your code explicitly).
+
+
+
+```sqlite
+-- orderSign --> orderState:signed
+INSERT INTO relation
+(from_meta, to_meta, settings)
+VALUES('B:statistics/consume/input:1', 'B:statistics/consume/product/total/minute:1', '{"target_states":{"add":["signed"]}}');
+```
+