Merge pull request #300 from filecoin-project/docs/tanlang/add-docume…

…nt-about-dealfilter

docs: add document about deal filter

docs/zh/订单过滤器.md

@@ -0,0 +1,126 @@
+# 订单过滤器
+
+## 背景
+
+有时候, `SP` 可能会希望可以对是否接受订单以及接受哪些订单做出一些更加精细化的控制. 例如, 有些 `SP` 可能希望只接受来自特定 `peer` 的订单, 或者只接受来自特定 `peer` 的订单, 并且订单的价格必须在某个范围内. 
+
+## 详情
+
+为了满足这些需求, 可以在 `Droplet` 的配置文件中给特定的 `miner` 配置一个订单过滤器, 该过滤器在配置文件中的表现形式是一个表示一个 `shell` 命令的字符串, 每当 `Droplet` 决定是否接受指向某个 `miner` 的订单时, 就会调用该命令, 并将 `订单的信息` ( json 字符串) 作为命令的参数 (标准输入) 传递给该命令. 如果命令退出码为 `0`, 则表示接受该订单, 否则拒绝该订单.
+
+- exit with 0 :  接受订单
+- exit with non-0 :  拒绝订单
+
+### 订单信息
+
+- Storage Deal
+
+```json
+{
+"IsOffline": false,
+"Proposal": {
+"PieceCID": {
+"/": "baga6ea4seaqihx2pxanewwxvqwgeyrcmal7aomucelef52vhqy7qaarciamaqoq"
+},
+"PieceSize": 2048,
+"VerifiedDeal": false,
+"Client": "f3r3hr3xl27unpefvipve2f4hlfvdnq3forgr253z6dqahufvanatdandxm74zikheccvx74ys7by5vzafq2va",
+"Provider": "f01000",
+"Label": "bafk2bzacebiupsywspqnsvc5v7ing74i3u4y3r7wtgjioor7pqn3cxopq7lo4",
+"StartEpoch": 18171,
+"EndEpoch": 536571,
+"StoragePricePerEpoch": "1",
+"ProviderCollateral": "0",
+"ClientCollateral": "0"
+},
+"ClientSignature": {
+"Type": 2,
+"Data": "oEnUUL1WejrLawl3sP9o/TZYRZgPYA86xmF3RMQt5bPQJbrK/5x3UXYxeUKoIDMjE96fA1GSqfrE14tFl/nMyatPLUvzzZ0ulsPTQVwfb54Mgx0yBSMYTf/O8Bg09MNq"
+},
+"DealType": "storage",
+"Agent": "venus-market"
+}
+```
+
+
+- Retrivel Deal
+
+```json
+{
+  "PayloadCID": null,
+  "ID": 0,
+  "Selector": null,
+  "PieceCID": null,
+  "PricePerByte": "\u003cnil\u003e",
+  "PaymentInterval": 0,
+  "PaymentIntervalIncrease": 0,
+  "UnsealPrice": "\u003cnil\u003e",
+  "StoreID": 0,
+  "SelStorageProposalCid": null,
+  "ChannelID": null,
+  "Status": 0,
+  "Receiver": "",
+  "TotalSent": 0,
+  "FundsReceived": "\u003cnil\u003e",
+  "Message": "",
+  "CurrentInterval": 0,
+  "LegacyProtocol": false,
+  "CreatedAt": 0,
+  "UpdatedAt": 0,
+  "DealType": "retrieval"
+}
+```
+
+
+## 示例
+
+```toml
+# Storage Deal
+Filter = ""
+
+# Retrieval Deal
+RetrievalFilter = ""
+```
+
+- 例子: 最简单的订单过滤器
+
+```toml
+# 拒绝所有订单
+Filter = "exit 1"
+
+# 接受所有订单
+Filter = "exit 0"
+```
+
+- 例子: 只接受来自 `f01000` 的订单
+
+```toml
+Filter = "jq -r '.Proposal.Provider' | grep -q '^f01000$'"
+```
+
+- 例子: 使用 `python` 脚本
+
+```toml
+# config.toml
+Filter = "python3 /path/to/filter.py"
+```
+
+```python
+# filter.py
+import json
+import sys
+
+try:
+    json_str = sys.stdin.read()
+    data = json.loads(json_str)
+
+    if data['Proposal']['PieceSize'] < 2048:
+        print("")
+        sys.exit(0)
+    else:
+        print("PieceSize is greater than or equal to 2048. Exiting with code 1.")
+        sys.exit(1)
+except Exception as e:
+    print("An error occurred: ", e)
+    sys.exit(1)
+```