Add workflows (#24)

.github/workflows/build.yml

@@ -8,3 +8,26 @@ on:
 jobs:
   build:
     uses: valitydev/java-workflow/.github/workflows/maven-library-build.yml@v1
+
+  documentation:
+    name: Build documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Set up Python runtime
+        uses: actions/setup-python@v1
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install Python dependencies
+        run: |
+          pip install -r requirements.txt
+      - name: Install theme
+        run: |
+          pip install mkdocs-gitbook
+      - name: Build documentation
+        run: |
+          mkdocs build
+          mkdocs --version

.github/workflows/deploy.yml

@@ -15,3 +15,25 @@ jobs:
       deploy-secret-key: ${{ secrets.OSSRH_GPG_SECRET_KEY }}
       deploy-secret-key-password: ${{ secrets.OSSRH_GPG_SECRET_KEY_PASSWORD }}
       mm-webhook-url: ${{ secrets.MATTERMOST_WEBHOOK_URL }}
+
+  documentation:
+    name: Build documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Set up Python runtime
+        uses: actions/setup-python@v1
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install Python dependencies
+        run: |
+          pip install -r requirements.txt
+      - name: Deploy documentation
+        env:
+          GOOGLE_ANALYTICS_KEY: ${{ secrets.GOOGLE_ANALYTICS_KEY }}
+        run: |
+          mkdocs gh-deploy --force
+          mkdocs --version

.gitignore

@@ -73,3 +73,11 @@ hs_err_pid*
 env.list
 
 gen
+
+mkdocs/site
+plantuml-toolset
+.vscode/
+.DS_Store
+pyvenv.cfg
+bin/
+lib/

Makefile

@@ -0,0 +1,13 @@
+FORMAT := png svg
+SOURCEDIR := $(CURDIR)/content
+STYLE := plantuml-toolset/super-serious-style.isvg
+
+all: plantuml-toolset
+
+plantuml-toolset:
+	git clone https://github.com/empayre/plantuml-toolset.git
+
+update-toolset: plantuml-toolset
+	cd $< && git pull
+
+-include plantuml-toolset/wsd.mk

content/docs/examples.md

@@ -0,0 +1,184 @@
+---
+title: examples
+
+metatitle: examples
+
+metadescription: examples
+
+category: examples
+---
+
+# Примеры
+
+####Простой пример с логическим оператором **И**:
+
+```sh
+rule: 
+    3 > 2 AND 1 = 1 
+-> accept;
+```
+
+####Пример работы с черными списками:
+
+```sh
+rule: 
+  inBlackList("email")
+-> notify;
+```
+
+данная функция может принимать список параметров:
+
+```sh
+rule: 
+  inBlackList("email", "fingerprint", "card_token", "bin", "ip")
+-> notify;
+```
+
+####Работа с белыми списками аналогична:
+
+```sh
+rule: check_in_white_list_rule: 
+  inWhiteList("email", "fingerprint", "card_token", "bin", "ip")
+-> notify;
+```
+
+####Работа с счетчиками:
+
+```sh
+rule: 
+  (count("ip", 1, days) >= 10 OR countSuccess("email", 1, days) > 5)
+        AND countError("fingerprint", 1, calendar_days, "error_code") > 5
+-> notify;
+```
+
+Вызываются функции подсчета количества операций в разрезе ip, 
+подсчет успешных платежей в разрезе email, а также количество конкретных ошибок при оплатах.
+
+**_Это работает следующим образом_** - _если количество платежей на один ip в сутки >= 10 
+или количество успешных платежей на один mail за сутки > 5 
+и при выполнении одного из этих условий количество ошибок с кодом "error_code" на один fingerprint за календарнык сутки > 5, 
+будет выслана уведомление_.
+
+Работа с функциями [сумм](../operations/#summ) производится аналогично.
+
+####Количество уникальных ip на один email
+
+```sh
+rule: unique("email", "ip") < 4
+-> decline;
+```
+
+####Определение страны по ip
+
+```sh
+rule: country() = "RU"
+-> notify;
+```
+
+####Определение суммы платежа
+
+```sh
+rule: amount() < 100
+-> accept;
+```
+
+####Работа с обработчиком ошибок
+
+```sh
+rule: 
+  unique("email", "ip") < 4 -> accept
+catch: decline;
+```
+
+В случае технической ошибки во время работы данной функции транзакция будет помечена как ```decline```,
+по умолчанию система возвращает ```normal``` и продолжает проверять правила
+
+####Определение доверенного трафика
+
+```sh
+rule: isTrusted(
+    paymentsConditions(
+        condition("RUB", 1, 1000, 10),
+        condition("EUR", 2, 20)
+    ),
+    withdrawalsConditions(
+        condition("USD", 3, 3000, 3)
+    )
+) -> accept;
+```
+
+В случае если сумма за 1 последний год > 100 рублей и количество транзакций > 10 
+или количество транзакций за 2 последних года  > 20 в евро 
+или количество выплат в USD за 3 последних года по сумме > 3000 или больше 3 успешных операций,
+то операция будет помечена как ```accept```.
+
+####Определение типа карты
+
+```sh
+rule: 
+  cardCategory() = "credit"
+-> accept;
+```
+
+####Определение платежной системы
+
+```sh
+rule: 
+  paymentSystem() = "VISA"
+-> accept;
+```
+
+####Определение рекурентного платежа
+
+```sh
+rule: 
+  isRecurrent()
+-> accept;
+```
+
+
+####Определение мобильного платежа
+
+```sh
+rule: 
+  isMobile()
+-> accept;
+```
+
+
+####Сравнение по шаблону и в списке
+
+```sh
+rule: cb:
+  like("bin", "5536.*") AND in("pan", "9137", "1231")
+-> decline;
+```
+Регулярные выражения формируются в стиле [java](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html)
+
+####Пример шаблона с несколькими правилами
+
+```sh
+# принимаем платеж, если хотя бы один из указанных параметров находится в вайтлисте
+rule: inWhiteList("email", "fingerprint", "card", "bin", "ip") 
+-> accept; 
+
+# отклоняем платеж, если хотя бы один из указанных параметров находится в блэклисте
+rule: inBlackList("email", "fingerprint", "card", "bin", "ip") 
+-> decline; 
+
+# эти страны блочим всегда
+rule: in(countryBy("bin"), "AS", "SD", "TR", "WE", "SD", "CD", "KL", "EW", "VF", "XZ", "CD") 
+-> decline; 
+
+# лимит суммы платежа 10 баксов для 
+rule: amount() > 1000 AND in(countryBy("bin"), "DS", "LA", "AS") 
+-> decline; 
+
+# лимит суммы платежа 10 баксов для некоторых стран
+rule: amount() > 1000 AND in(countryBy("bin"), "VC", "WE") 
+-> decline;
+
+# лимит по сумме платежа > 100 условных единиц в валюте платежа
+rule: amount() > 10000 
+-> decline;
+```

content/docs/operations.md

@@ -0,0 +1,241 @@
+---
+title: operations
+
+metatitle: operations
+
+metadescription: operations
+
+category: operations
+---
+
+# Функции языка
+
+## Параметры функций
+
+#### Поля группировки (group_field):
+
+Список полей которые можно использовать для группировок при подсчете сумм, количества и уникальности
+
+    email
+    ip
+    fingerprint
+    bin
+    shop_ip
+    party_id
+    card_token
+
+#### Единицы времени (time_unit):
+
+Минуты, часы и дни работают как разница, то есть сейчас **_13:54_**
+
+=> **_1 hours_** означает, что функция будет считать от **_12:54_**
+
+В свою очередь calendar_months и calendar_days означают календарное значение, то есть **_13:54 05.04.2022_**
+
+=> **_1 calendar_days_** означает, что функция будет считать от **_00:00 05.04.2022_**
+
+    minutes
+    hours
+    days
+    calendar_months
+    calendar_days
+
+## Подсчет количества
+
+Подсчет количества платежей в разрезе поля указанного в ```group_field``` за период по num_time, time_unit, также могут
+быть указаны дополнительные поля группировки (party_id, shop_id и т.д.)
+
+```sh
+count("group_field", num_time, time_unit, ["group_by_additional_fields"])
+```
+
+Подсчет количества успешных платежей в разрезе поля указанного в ```group_field``` за период по num_time, time_unit,
+также могут быть указаны дополнительные поля группировки (party_id, shop_id и т.д.)
+
+```sh
+countSuccess("group_field", num_time, time_unit, ["group_by_additional_fields"])
+```
+
+Подсчет количества ошибочных платежей в разрезе поля указанного в ```group_field``` за период
+по ```num_time, time_unit```, с указанием конкретного кода ошибки ```error_code```
+также могут быть указаны дополнительные поля группировки (```party_id, shop_id``` и т.д.)
+
+```sh
+countError("group_field", num_time, time_unit, "error_code", ["group_by_additional_fields"])
+```
+
+Подсчет количества чарджбеков в разрезе поля указанного в ```group_field``` за период по num_time, time_unit, также
+могут быть указаны дополнительные поля группировки (```party_id, shop_id``` и т.д.)
+
+```sh
+countChargeback("group_field", num_time, time_unit, ["group_by_additional_fields"])
+```
+
+Подсчет количества возвратов в разрезе поля указанного в ```group_field``` за период по num_time, time_unit, также могут
+быть указаны дополнительные поля группировки (```party_id, shop_id``` и т.д.)
+
+```sh
+countRefund("group_field", num_time, time_unit, ["group_by_additional_fields"])
+```
+
+[Примеры](../examples/#_5)
+
+## Подсчет сумм
+
+Подсчет суммы платежей в разрезе поля указанного в ```group_field``` за период по num_time, time_unit, также могут быть
+указаны дополнительные поля группировки (```party_id, shop_id``` и т.д.)
+
+```sh
+sum("group_field", num_time, time_unit, ["group_by_additional_fields"])
+```
+
+Подсчет суммы успешных платежей в разрезе поля указанного в ```group_field``` за период по num_time, time_unit, также
+могут быть указаны дополнительные поля группировки (```party_id, shop_id``` и т.д.)
+
+```sh
+sumSuccess("group_field", num_time, time_unit, ["group_by_additional_fields"])
+```
+
+Подсчет суммы ошибочных платежей в разрезе поля указанного в ```group_field``` за период по ```num_time, time_unit```, с
+указанием конкретного кода ошибки ```error_code```
+также могут быть указаны дополнительные поля группировки (```party_id, shop_id``` и т.д.)
+
+```sh
+sumError(("group_field", num_time, time_unit, "error_code", ["group_by_additional_fields"])
+```
+
+Подсчет суммы чарджбеков в разрезе поля указанного в ```group_field``` за период по num_time, time_unit, также могут
+быть указаны дополнительные поля группировки (```party_id, shop_id``` и т.д.)
+
+```sh
+sumChargeback("group_field", num_time, time_unit, ["group_by_additional_fields"])
+```
+
+Подсчет суммы возвратов в разрезе поля указанного в ```group_field``` за период по num_time, time_unit, также могут быть
+указаны дополнительные поля группировки (```party_id, shop_id``` и т.д.)
+
+```sh
+sumRefund("group_field", num_time, time_unit, ["group_by_additional_fields"])
+```
+
+[Примеры](../examples/#_5)
+
+## Количество уникальных значений
+
+Подсчет количества уникальных значений поля by_field в разрезе поля указанного в ```group_field``` за период по
+num_time, time_unit, также могут быть указаны дополнительные поля группировки (```party_id, shop_id``` и т.д.)
+
+```sh
+unique(("group_field", "by_field", num_time, time_unit, ["group_by_additional_fields"])
+```
+
+[Примеры](../examples/#ip-email)
+
+## Проверка по спискам
+
+Производится проверка в предзагруженных списках (белом, черном, именованном, серым)
+
+```sh
+inWhiteList("field")
+inBlackList("field")
+inList("test", "email")
+inGreyList("email")
+```
+
+[Примеры](../examples/#_3)
+
+## Определение типа платежа
+
+Определение, что выставлен признак мобильного платежа
+
+```sh
+isMobile()
+```
+
+[Примеры](../examples/#_12)
+
+Определение, что выставлен признак рекурентного платежа
+
+```sh
+isRecurrent()
+```
+
+[Примеры](../examples/#_11)
+
+## Определение доверенного клиента
+
+С помощью данной функции можно определелить доверяем ли мы данному плательщику
+
+```sh
+isTrusted()
+```
+
+[Примеры](../examples/#_8)
+
+## Вспомогательные функции
+
+Сравнивает поля с конкретными значениями в списке
+
+```sh
+in(("field", "first", "second", ...)
+```
+
+[Примеры](../examples/#_13)
+
+Сравнивает соотвествия поля регулярному выражению
+
+```sh
+like("field", "regexp_in_java_style"[1])
+```
+
+[Примеры](../examples/#_13)
+
+Возвращает сумму текущего платежа
+
+```sh
+amount()
+```
+
+[Примеры](../examples/#_6)
+
+Возвращает страну по предоставленному IP
+
+```sh
+country() - this function can return result "unknown", you must remember it!
+```
+
+[Примеры](../examples/#ip)
+
+Возвращает тип карты debit/credit
+
+```sh
+cardCategory()
+```
+
+[Примеры](../examples/#_9)
+
+Возвращает платежную систему VISA/MASTERCARD и т.д.
+
+```sh
+paymentSystem()
+```
+
+[Примеры](../examples/#_10)
+
+## Возможные результаты применения шаблона:
+
+    accept 
+    3ds
+    highRisk
+    decline
+    normal
+    notify
+    declineAndNotify
+    acceptAndNotify
+
+## Возможные результаты обработки исключений (catch):
+
+    accept
+    3ds
+    highRisk
+    notify

content/docs/syntax.md

@@ -0,0 +1,43 @@
+---
+title: syntax
+
+metatitle: syntax
+
+metadescription: syntax
+
+category: syntax
+---
+
+# Синтаксис
+
+
+<img alt="svg" src="../img/syntax.svg" /></p>
+
+Все правила начинаются с ключевого слова ```rule``` затем идет разделитель ```:```,
+после этого опционально может быть указано имя правила ```rule name``` + ```:```
+(оно будет отображаться в случае его срабатывания, иначе будет порядковый номер в шаблоне).
+
+Далее описывается основной блок с функциями разделенными логическими операторами ```operations``` 
+(список доступных функций описан в [Операции](operations.md)).
+
+В завершение необходимо определить [результат срабатывания правила](../operations/#_9), указав его после ```->```.
+
+Все правила должны быть завершены терминальным символом ```;```.
+
+Пример:
+
+```
+rule: countError("fingerprint", 1444, "error_code") > 5 -> decline;
+```
+
+Также до завершения правила опционально можно указать блок ```catch``` + ```:``` с неким [результатом](../operations/#catch),
+что подскажет системе как реагировать на ошибки при обработке правила.
+
+Пример:
+
+```
+rule: unique("email", "ip") < 4 -> accept
+catch: decline;
+```
+
+Для лучшего понимания смотрите раздел с [примерами](examples.md).

content/index.md

@@ -0,0 +1,27 @@
+
+# Добро пожаловать на портал описания Fraudo! {#welcome}
+
+Fraudo - язык для описания правил борьбы с мошенническими операциями.
+
+## Для кого и зачем создан язык? {#about}
+
+Язык создан для офицеров безопасности или технической поддержки, участвующих в процессе контроля чистоты платежей.
+На данном портале вы сможете разобраться в синтаксисе языка и понять как написать собственные правила под ваш бизнес.
+
+Данная документация вам будет интересна если вы используете продукт [fraudbusters](https://vality.dev/fraudbusters)
+
+## С чего начать? {#lets-start}
+
+**Шаг 1**
+Обратитесь к синтаксису языка [обзор](syntax.md).
+
+**Шаг 2**
+Просмотрите список доступных:
+
+-  [функций](docs/operations/#_2);
+-  [возможных результатов применения шаблона](docs/operations/#_9);
+-  [полей для группировки](docs/operations/#group_field);
+-  [доступных единиц времени](docs/operations/#time_unit)
+
+**Шаг 3**
+Обратитесь к [примерам](examples.md) для лучшего понимания стуктуры языка и понимания синтаксиса.

mkdocs.yml

@@ -0,0 +1,50 @@
+docs_dir: "content"
+site_name: "Fraudo|docs"
+#repo_url: https://github.com/valitydev/fraudo
+#edit_uri: ""
+theme:
+  name: gitbook
+  highlightjs: true
+  icon:
+    logo: material/alpha-e-box
+  favicon: assets/favicon.ico
+  language: ru
+  features:
+    - toc.integrate
+  palette:
+    primary: teal
+    accent: teal
+
+extra:
+  analytics:
+    provider: google
+    property: !ENV GOOGLE_ANALYTICS_KEY
+  nav:
+    sort_order: reverse
+strict: false
+
+plugins:
+  - autolinks
+
+markdown_extensions:
+  - pymdownx.highlight
+  - pymdownx.inlinehilite
+  - pymdownx.superfences
+  - pymdownx.snippets
+  - smarty
+  - admonition
+  - def_list
+  - footnotes
+  - codehilite
+  - attr_list
+  - md_in_html
+  - meta
+  - toc:
+      permalink: true
+
+nav:
+  - О языке: "index.md"
+  - Синтаксис:
+      - Синтаксис: "docs/syntax.md"
+      - Операции: "docs/operations.md"
+      - Примеры: "docs/examples.md"

requirements.txt

@@ -0,0 +1,5 @@
+mkdocs>=1.2.3
+mkdocs-material>=7.3.6
+mkdocs-material-extensions>=1.0
+pygments>=2.10
+mkdocs-autolinks-plugin>=0.4.0