luna_park 0.11.0

data/docs/_coverpage.md

@@ -0,0 +1,18 @@
+![logo](_media/black_cover.jpg)
+
+# LunaPark <small>0.5.9</small>
+
+> Simple Domain-Driven-Design ruby framework
+
+- Make complex things simple
+- Knowledge is more important than technology
+- Pragmatism is more important than dogmatism
+- Hardness in architecture, flexibility in solutions
+
+[GitHub](https://github.com/am-team/luna_park/)
+[Guideline](#Область-применения)
+
+Contacts: 
+- Alexander Kudrin - [alexander.kudrin@lunapark.dev](mailto:alexander.kudrin@lunapark.dev)
+- Philipp Sorokin  - [philipp.sorokin@lunapark.dev](mailto:philipp.sorokin@lunapark.dev)
+- Telegram         - https://t.me/lunapark_dev

data/docs/_media/logo.svg

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Svg Vector Icons : http://www.onlinewebfonts.com/icon -->
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px" viewBox="0 0 1000 1000" enable-background="new 0 0 1000 1000" xml:space="preserve">
+<metadata> Svg Vector Icons : http://www.onlinewebfonts.com/icon </metadata>
+<g><path d="M500,10c28.5,0,51.6,23.1,51.6,51.6c0,21.2-19.2,39.4-37.5,47.3l13.8,133.2c98.7,1.2,178.4,81.5,178.4,180.5l0,77.4h-25.8c57,0,103.2,46.2,103.2,103.2v51.6c0,57-46.2,103.2-103.1,103.2h25.8v196C659.3,975.8,584.4,990,500,990s-159.3-14.2-206.3-36.1v-196h25.8c-57,0-103.1-46.2-103.1-103.2v-51.6c0-57,46.2-103.2,103.2-103.2h-25.8v-77.4c0-99,79.7-179.4,178.4-180.5l13.8-133.2c-18.3-7.9-37.5-26.1-37.5-47.3C448.4,33.1,471.5,10,500,10z M680.5,525.8H319.5c-42.7,0-77.4,34.6-77.4,77.4v51.6c0,42.7,34.6,77.4,77.4,77.4h361.1c42.7,0,77.4-34.6,77.4-77.4v-51.6C757.9,560.4,723.3,525.8,680.5,525.8z M500,790.1l-25.8-6.1v51.2h51.6v-51.2L500,790.1z M680.5,835.3c0-51.6-19.7-43.3-51.6-51.7v51.7H680.5z M551.6,785.3v50h51.6v-50.7L551.6,785.3z M396.8,784.5v50.7h51.6v-50L396.8,784.5z M319.5,835.3h51.6v-51.7C339.1,792,319.5,783.7,319.5,835.3z M500,912.6l25.8-0.6v-51h-51.6v51L500,912.6z M671.4,861.1h-42.5v30.8C649.4,883.1,663.3,872.3,671.4,861.1z M551.6,861.1v49.1c19.6-2,36.8-5.3,51.6-9.4v-39.7H551.6z M396.8,861.1v38.7h-3.6c15.6,4.6,33.9,8.2,55.1,10.4v-49.1H396.8z M328.6,861.1c8.2,11.3,22.1,22,42.5,30.8v-30.8H328.6z M371.1,603.2h51.6v51.6h-51.6V603.2z M577.4,603.2h51.6v51.6h-51.6V603.2z M319.5,551.6h30.8c-26.2,15.8-43.7,44.5-43.7,77.4c0,32.8,17.5,61.6,43.7,77.4h-30.9c-28.5,0-51.6-23.1-51.6-51.6v-51.6C267.9,574.7,291,551.6,319.5,551.6z M680.5,551.6c28.5,0,51.6,23.1,51.6,51.6v51.6c0,28.5-23.1,51.6-51.6,51.6h-30.8c26.2-15.8,43.7-44.5,43.7-77.4c0-32.8-17.5-61.6-43.7-77.4H680.5z M443.4,706.3c26.2-15.8,43.7-44.5,43.7-77.4c0-32.8-17.5-61.6-43.7-77.4h113.3c-26.2,15.8-43.7,44.5-43.7,77.4c0,32.8,17.5,61.6,43.7,77.4H443.4z"/></g>
+</svg>

data/docs/_sidebar.md

@@ -0,0 +1,9 @@
+* Фреймворк
+    * [Область применения](/)
+    * [Методология](methodology)
+    * [Архитектура](architecture)
+    * [Подход](way)
+* Паттерны
+    * [Объект-значение](patterns/value)
+    * [Сущность](patterns/entity)
+    

data/docs/architecture.md

@@ -0,0 +1,214 @@
+# Архитектура
+
+
+![WM](_imgs/wm.jpeg)
+
+# Гибкая архитектура
+DDD включает в себя практику реализации через модель. Предметная область должна описываться через ваш код. Давайте попробуем разобраться, как это сделать.
+
+В своей книге Эрик Эванс приводит ряд шаблонов проектирования, рекомендуемых к использованию, и обозначает данный подход как гибкий:
+
+> Во имя гибкости архитектуры в программах было нагромождено множество ненужных конструкций. Лишние уровни абстрагирования и косвенных ссылок чаще мешают, чем помогают в этом деле. Посмотрите на архитектуру, которая действительно вдохновляет программистов, занимающихся ее доработкой, и вы увидите, как правило, что-нибудь очень простое. Но простое - не значит легкое в исполнении. Чтобы создать такие элементы, которые можно собрать в сложные системы и при этом нетрудно понять, необходимо сочетать "преданность " проектированию по модели с достаточно строгим стилем архитектуры. Определенный навык проектирования нужен не только для создания чего-либо, но даже для использования готового.
+
+> Eric Evans, Domain-Driven Design: Tackling Complexity in the Heart of Software
+
+Представленный набор шаблонов проектирования не является строгой архитектурой или готовым решением, а, скорее, пищей для размышления.
+
+# Кричащая архитектура
+
+Похожие мысли возникали в голове у многих разработчиков и проектировщиков сложных систем.
+
+В 2011 году вышла статья Роберта Мартина - [Screaming Architecture](https://blog.cleancoder.com/uncle-bob/2011/09/30/Screaming-Architecture.html), которая говорит о том, что ваш код не просто должен описывать предметную область, а орать о ней, желательно матом.
+
+> So what does the architecture of your application scream? When you look at the top level directory structure, and the source files in the highest level package; do they scream: Health Care System, or Accounting System, or Inventory Management System? Or do they scream: Rails, or Spring/Hibernate, or ASP?
+
+> Robert C. Martin, 30 September 2011
+
+Роберт рассказывает, что код вашего приложения должен отображать деятельность приложения, вместо того чтобы подстраиваться под правила фреймворка. Структура фреймворка не должна ограничивать вашу архитектуру. Приложение,в свою очередь, не должно привязываться к БД или http протоколу, это всего лишь механизмы хранения и доставки. Ограничительные рамки являются инструментом. Не следует становиться адептом фреймоворка. Тесты вашего приложения - это тесты логики его работы, а не тестирование http протокола.
+
+# Чистая архитектура
+
+Через год выходит следующая статья Роберта Мартина - [The Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html). В ней автор рассказывает, как добиться того, чтобы код кричал. Изучив несколько архитектур, он выделяет основные принципы:
+
+1. Независимость от рамок. Архитектура не зависит от какой-то существующей библиотеки. Это позволяет использовать фреймворки как инструменты, а не ограничения, связывающие ваши руки.
+2. Тестируемость. Бизнес-правила могут быть протестированы без пользовательского интерфейса, базы данных, веб-сервера или любого другого технического средства.
+3. Независимость от пользовательского интерфейса. Пользовательский интерфейс может легко меняться, не изменяя остальную часть системы. Например, веб-интерфейс можно заменить консольным интерфейсом, не изменяя бизнес-логику.
+4. Независимость от базы данных. Вы можете обменять Oracle или SQL Server на Mongo, BigTable, CouchDB или что-то еще. Логика вашего приложения не должна быть привязана к базе данных.
+5. Независимость от воздействия внешней среды. На самом деле ваши бизнес-правила просто ничего не знают о внешнем мире.
+
+На хабре уже опубликована очень хорошая статья [Заблуждения Clean Architecture](https://habr.com/company/mobileup/blog/335382/). Ее автор, @Jeevuz очень хорошо разжевал тонкости понимания данного подхода. Настоятельно рекомендую ознакомиться как и с ней так и с оригинальными материалами.
+
+# Вариативная архитектура
+
+Описание представленного выше подхода не выглядит столь однозначным. В рамках разработки архитектуры ряда сложных корпоративных систем мной и моими коллегами была выработана достаточно четкая интерпретация описанных подходов, которую я собираюсь изложить ниже.
+
+До появления компьютеров и языков программирования при построении и управлении системами со сложной бизнес-логикой использовался бумажный документооборот. Результатом любого процесса являлся документ, который в конечном счете описывал тот или иной бизнес-объект. В итоге делопроизводство сводилось к трем простым _Действиям_:
+
+1. Создание документа
+2. Обработка документа
+3. Работа с архивом документов
+4. Представление документа
+
+> Документ - фиксация информации о хозяйственной деятельности относительного того или иного реального бизнес-объекта.
+
+Прошу заметить, что документ сам по себе не является реальным бизнес-объектом, а только его _Моделью_. В данный момент бумажные документы вытесняются электронными. Документом может быть запись в таблице, картинка, файл, отправленное письмо или любой другой фрагмент информации.
+Я бы не хотел в дальнейшем использовать слово документ, так как оно будет вносить скорее путаницу, мы будем использовать понятие _Сущность_ (Entity) из DDD терминологии. Но вы можете представить, что сейчас вся ваша система, это система электронного документооборота, которая выполняет четыре простых _Действия_.
+
+1. Collecting
+2. Processing
+3. Storage
+4. Representation
+
+> Действие (Action) - структурная единица деятельности бизнес-модели; относительно завершенный отдельный акт осознаваемой цели, произвольность и преднамеренность индивидуальной активности бизнес-объекта, различаемая конечным потребителем.
+
+Хорошим примером _Дейсвтия_ является театральный акт. Театр моделирует события из реальной жизни. Акт является осмысленной частью пьесы. Но, чтобы сделать историю законченной, нужно проиграть несколько актов в строго отведенном порядке. Такой порядок в нашей архитектуре мы будем называть _Режим_.
+
+> Режим (Conduction)- набор _Действий_ в определенном порядке, имеющий законченный смысл, несущий пользу конечному потребителю.
+
+![conduction](_imgs/conductor_schema.png)
+
+<a name="conduction" id="conduction"></a> Для подобных _Режимов_ работы был придуман селективный кондуктор или _Вариатор_ (Selector). Точнее "Timing mechanism for conducting a selected one of a plurality of sequences of operation", на который был получен патент [US2870278A](https://patents.google.com/patent/US2870278A/en). Мы знаем это устройство как "крутилка" стиральной машины. Архитектурная "крутилка" приведена в начале статьи.
+
+Вариативность подхода проявляется в том, что с такой архитектурой вы можете выбрать любой из четырех _Режимов_, проходя которые вы не будете совершать лишних _Действий_.
+
+Запуская стиральную машину, вы можете выбрать режим: стирка, полоскание или отжим. Если вы выбрали стирку, то ваша машина все равно прополощет белье, а затем его отожмет. С полоскание в комплекте вы обязательно получите отжим. Отжим - финальное _Действие_ в процессе стирки оно является самым “простым”. В нашей архитектуре самое простое _Дейтствие_ - _Представление_, с него и начнем.
+
+## Представление (Representation)
+
+Если говорить о чистом представлении без обращения к базе данных или внешнему источнику, то мы выдаем какую-то статическую информацию: html-страницу, файл, справочник лежащий в виде json'a. Мы даже можем выдать просто _Code response_ - 200:
+
+Напишем простейший "Health checker"
+
+```ruby
+  module Health
+    class Endpoints < Sinatra::Base
+      get '/check' do; end
+    end
+  end
+```
+
+В самом примитивном виде наша схема будет выглядеть так:
+
+![Representation](_imgs/representation.png)
+
+<spoiler title="Лирическое отступление">
+Я прошу заметить, что во фреймворке Sinatra класс _Endpoints_ объединяет в себе как _Router_, так и _Controller_ в одном классе. Не нарушает ли это принципа единственной ответственности? По факту, Endpoints это не класс, а слой, выраженный через класс, и зона его ответственности на более высоком уровне.
+
+Ок, а как же _Router_ и _Controller_? Они представлены не набором классов, а наименованием и реализацией функции. А статический файл это вообще файл. Один класс отвечает одной ответственности, но не пытайтесь выразить каждую ответственность через класс. Исходите из практичности, а не из догматизма.
+</spoiler>
+
+## Работа с системой хранения (Storage)
+
+Бизнес требователен к доступности вашего приложения. Зачем кому-то нужен ваш сервис, если в нужный момент мы не можем его использовать? Для обеспечения целостности данных мы фиксируем изменение состояния бизнес-объекта после каждой обработки.
+
+Чтобы извлечь объект из хранилища, не требуется обращение к бизнес-логике. Представим, что мы автоматизируем деятельность сети отелей и у нас есть журнал постояльцев на стойке регистрации. Мы решили посмотреть информацию о посетителе.
+
+```ruby
+  module Reception
+    class Endpoints < Sinatra::Base
+
+    # Show item
+    get '/residents/:id', provides: :json do
+      resident = Repository::Residents.find params[:id]
+      status 200
+      serialize(resident)
+    end
+  end
+end
+```
+
+_Работа с системой хранения_ в виде графической схемы:
+
+![Storage](_imgs/storage.png)
+
+Как мы можем заметить общение между уровнем, отвечающим за _Хранение_, и уровнем, отвечающим за представление данных, реализовано через Response model. Данная модель не принадлежит ни одному из этих слоев. По факту, это бизнес-объект и он находится на слое, отвечающим за бизнес-логику.
+
+## Обработка (Processing)
+
+Если речь заходит о том, что объектная модель изменяется на основе своих свойств без внесения новых данных, то мы обращаемся к слою _Интерактора_ напрямую. Слой _Интерактора_ является ключевым в нашем приложении, именно в нем описывается вся бизнес-логика в виде отдельных _Вариантов использования_ (Use Cases) и именно на нем идет изменение _Сущностей_.
+
+Рассмотрим такой сценарий использования. В нашей гостинице посетитель уже зарегистрирован, но мы отмечаем каждый его приход или уход.
+
+```ruby
+  module Reception
+    class Endpoints < Sinatra::Base
+
+      # Register resident arrival
+      post '/residents/:uid/arrival', provides: :json do
+        result = Interactors::Arrival.call(resident_id: params[:id])
+        check!(result) do
+          status 201
+          serialize result.data
+        end
+      end
+
+      # Register resident departure
+      post '/residents/:uid/departure', provides: :json do
+        result = Interactors::Departure.call(resident_id: params[:id])
+        check!(result) do
+          status 201
+          serialize result.data
+        end
+      end
+    end
+  end
+```
+
+Давайте немного остановимся. Почему не сделать реализацию одним методом с параметром `status` ? _Интеракторы_ `Arrival` и `Departure` в корне отличаются. Если к нам пришел постоялец, то мы должны проверить закончилась ли уборка, не поступало ли для него новых сообщений и т.п. При его уходе мы, наоборот, должны инициировать уборку в случае необходимости. Про сообщения, в свою очередь, мы даже не вспоминаем, поскольку если бы он был в гостинице, мы бы ему сразу позвонили. Именно всю эту логику бизнеса мы и прописываем на слое _Интерактора_.
+
+![Processing](_imgs/processing.png)
+
+Но что нам делать, если у нас есть данные извне? Тут подключается действие _Сбора данных_.
+
+## Сбор данных (Collecting)
+
+При первичной регистрации постояльца в гостинице он заполняет форму регистрации. Эта форма проверяется. Если данные верны, то происходит бизнес-процесс Регистрация. Процесс возвращает данные - созданную бизнес-модель "Постояльца". Эту модель мы представляем постояльцу в читаемой форме:
+
+```ruby
+module Reception
+  class Endpoints < Sinatra::Base
+
+  # Register new resident
+    post '/residents', provides: [:json] do
+      form = Forms::Registration.new(params)
+      submit! form do
+        check! form.result do
+          status 201
+          serialize form.result.data
+        end
+      end
+    end
+  end
+end
+```
+
+Схематично это выглядит так:
+
+![Collecting](_imgs/collecting.png)
+
+# Правила игры (Rules)
+
+- Вариативная система с точки зрения процессов делится на _Действия_.
+- Последовательность _Действий_ определяется _Режимом_.
+- _Режимы_ инкрементальны.
+- Более "сложный" _Режим_ дополняет более "простой", на строго одно действие.
+- Каждое действие происходит в рамках одного _Слоя_.
+- Каждый слой представлен _Классом_.
+- Внутри слоя могут быть _Классы-Слои_ и _Классы-Ответственности_.
+- Общение происходит только между _Слоем_ и _Внутрислойным Классом_.
+- _Модели-Представления_ являются исключениями.
+- Обработка ошибок должна происходить на уровне _Класса-Cлоя_.
+
+![Tree](_imgs/tree.png)
+
+# Общая схема
+
+У данного подхода высокий порог вхождения. Его применение требует от проектировщика большого опыта для четкого осознания решаемых задач. Сложность также представляет разнообразие выбора необходимого инструмента. Но, не смотря на сложность структуры, реализация на уровне кода невероятно проста и выразительна. Хотя и содержит в себе ряд условностей и доверенностей. В дальнейшем мы разберем каждый шаблон проектирования в отдельности, опишем как его создать, тестировать и обозначим область применения. А чтобы не запутаться в их многообразии, предлагается полная карта:
+![Карта в высоком разрешении](_imgs/full_map_hight_res.png)
+
+---
+- Проблемно-ориентированное проектирование, Эрик Дж. Эванс
+- Кейт Матсудейра: Масштабируемая веб-архитектура и распределенные системы
+- https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html
+- https://blog.cleancoder.com/uncle-bob/2011/09/30/Screaming-Architecture.html
+- https://habr.com/company/mobileup/blog/335382/

data/docs/google48f1e6f5c35eae5f.html

@@ -0,0 +1 @@
+google-site-verification: google48f1e6f5c35eae5f.html

data/docs/index.html

@@ -0,0 +1,32 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Document</title>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+  <meta name="description" content="Description">
+  <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
+  <link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">
+</head>
+<body>
+  <div id="app"></div>
+  <script>
+    window.$docsify = {
+      name: 'LunaPark',
+      repo: 'am-team/luna_park',
+      loadSidebar: true,
+      coverpage: true,
+      auto2top: true,
+      maxLevel: 4,
+      subMaxLevel: 2,
+      ga: 'UA-131438707-1',
+      search: 'auto',
+    }
+  </script>
+  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
+  <script src="//unpkg.com/prismjs/components/prism-ruby.min.js"></script>
+  <script src="//unpkg.com/prismjs/components/prism-markdown.min.js"></script>
+  <script src="//unpkg.com/docsify/lib/plugins/ga.min.js"></script>
+  <script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script>
+</body>
+</html>

data/docs/methodology.md

@@ -0,0 +1,376 @@
+# Методология
+![ddd-header](_imgs/ddd_header.jpeg)
+
+# DDD
+
+Вспомним данное ранее определение:
+
+> Проектирование на основе предметной области (DDD, Domain-driven design) - это подход к разработке программного обеспечения для комплексного удовлетворения потребностей, путем сильной связи реализации с основными бизнес-моделями, находящимися в процессе постоянного развития.
+
+Эталонной книгой которая описывает практики построения сложных систем является книга [Domain Driven Dedign](https://domainlanguage.com/ddd/) (Big Blue Book) Эрика Эванса. Если вы читали любую обзорную статью по этой теме, вы уже знаете об этом. К моменту применения DDD на практике вам придется ее прочесть. Это не самая легкая книга для восприятия:
+
+> The canonical source for DDD is Eric Evans's book. It isn't the easiest read in the software literature, but it's one of those books that amply repays a substantial investment.
+> 
+> Martin Fowler: 15 January 2014
+
+Если пролистать содержание книги, она покажется вам не совсем структурированной. Но нам поможет карта. 
+![DDD-map](_imgs/ddd_map.png)
+
+На карте выделены те практики, которые мы рассмотрим.
+
+Объем рассмотренных в книге практик огромен. Объем практик, которые можно применить за пределами данной книги еще больше. Прежде чем брать на вооружение хотя бы часть их них, обозначьте для себя цели. Приведу в качестве примера свои.
+- Повысить производительность.
+- Писать понятный код.
+- Масштабирование на уровне разработки программного обеспечения.
+
+
+# Единый язык
+
+Разработка программного обеспечения редко приводит к созданию чего-то нового, как правило, это моделирование чего-то существующего.
+
+> Модель - представление реального объекта, включающее в себя только необходимые свойства и функции.
+
+Мы не можем создать программный продукт, который охватит всю предметную область. Возможно воспроизвести только ту его часть, которая будет воспроизводить необходимый функционал. 
+
+Хорошим примером модели будет являться топографическая карта. Она является моделью местности. Карта не содержит лугов полей и рек, она только отражает месторасположение реальных объектов относительно друг друга.
+
+Чтобы построить четкую и ясную для всех модель, нужно говорить на одном языке. Об этом нам говорит не только Эрик Эванс, но и здравый смысл. Если программисты будут использовать свои термины, а бизнес свой 'сленг', то первые просто не будут понимать что нужно делать. Бизнес же в этом случае не сможет осознать реальной стоимости разработки той или иной 'фичи'. Сколько раз вам приходилось слышать: "Да это всего лишь добавить кнопку"?
+
+Ваша цель, как проектировщика системы, должна быть в том, чтобы добиться от всей команды максимального понимания друг друга. Как же этого добиться? Начните говорить. Если люди начинают общаться в любой тесной группе, у них появляется некий общепринятый набор терминов. В различных компаниях процесс введения общего языка, скорее всего, будет отличаться. Это может быть как волевым решением, так и демократической процедурой. Язык может быть обозначен явно, так и вводиться не явно, в этом случае на нем начинают просто говорить. Хорошим приемом введения общего языка станет общая документация.
+
+## Документация проекта
+
+1. Любое общение между бизнесом и разработкой должно улучшить вашу модель.
+2. После совещания зафиксируйте результат в виде документации (артефакт Scrum), и покажите эту документацию всем участникам процесса разработки.
+3. Используйте в документации единый язык.
+4. Самое важное: не тратьте время на документацию. Вам еще придется писать код, а документация будет переписываться многократно, тратить ресурсы - это дорого. Вместо того, чтобы долго возиться с приложением для рисования диаграмм UML, воспользуйтесь салфеткой, ручкой и фотоаппаратом на телефоне.
+5. Документация требует дисциплины, нельзя писать ее время от времени. 
+6. Разделите документацию:
+    - Комментарии в коде - описывайте непонятные моменты прямо в коде, оставляйте `#ТODO:` (убирайте, когда сливаете код в master). Выражайте свое мнение в комментариях, к примеру вам приходиться использовать тот или иной костыль при работе с legasy кодом. 
+    - Комментарии к проекту `README.md` в корневом каталоге вашего проекта должны содержать техническую информацию: как запустить проект, как прогнать тесты, и т.п. Так же неплохо завести карту, где у вас лежат все проекты, и на каких серверах они запущенны. Отдельно записать все принятые соглашения.
+    - И самое важное - база знаний. Сборник документов, описывающих бизнес процессы, это та часть документов, которая доступна как вам, так и бизнесу.
+7. Основная ошибка тех, кто пишет документацию, избыточность. Не пытайтесь охватить все и вся, передавайте только общий смысл. Документация должна дополнять ваш проект, но никак не заменять его. Не записывайте все термины, только имеющие неоднозначное значение. Если определение занимает больше двух предложений, это плохое определение.
+
+Пример документации: 
+
+```markdown
+# Система авторизации
+
+Система авторизации отвечает за идентификацию конкретного пользователя.
+
+# Сущности:
+
+Пользователь характеризуется:
+- Именем и фамилией
+- email
+- телефоном
+
+## Процессы:
+
+### Регистрация
+В процессе регистрации мы создаем нового пользователя, просим его подтвердить его email и телефон, авторизуем пользователя на 1 день (за это время он обязан подтвердить email и телефон).
+
+### Авторизация
+В процессе авторизации мы выписываем пользователю аутентификационный ключ на месяц. Аутентифицироваться может только пользователь с верифицированным телефоном и и email адресом.
+
+### Верификация email
+На email пользователя приходит письмо со ссылкой. Открывая ссылку пользователь сообщает, что это его email. Ссылка действительна сутки.
+
+### Верификация телефона
+На телефон пользователя приходит смс, ответив на которое он подтверждает, что это его телефон. Код действителен сутки.
+
+### Восстановление пароля
+Пользователь вводит свой email, на него приходит ссылка, по которой ему будет предложено изменить пароль. Ссылка действует 2 часа.
+
+### Авторизация на других доменах
+При использовании амортизационного ключа мы можем получить доступ к учетным записям на других доменах. Если ключ не подходит, происходит переход на страницу авторизации, при успешном прохождении которой будет произведен переход пользователя на исходную страницу исходного домена.
+
+```
+
+Заметим, что в данном примере мы не указали явный словарь, тем не менее мы закрепили понятие _Пользователь_, _Авторизация_, _Регистрация_. Написание подобной документации не займет у эксперта больше 20 минут. 
+
+Для человека, не являющегося экспертом в предметной области, процесс написания документации воспринимается как что-то сложное. Нужно разделять сбор знаний и запись собранных знаний. `Документирование != Документирование + Сбор знаний.`
+
+>– То, что вы называете вселенной, – утверждал четвертый, – есть, собственно, скопление миров, которые, подобно кожице лука, находятся один на другом и постепенно отделяются друг от друга.
+>
+>– Необыкновенно ясно изложено! – восхищались абдериты. – Удивительно ясно! – Они полагали, что понимают философа, так как очень хорошо знали, что такое луковица.
+>
+> История Абердитов, Кристов Мартин Виланд
+
+# Ограниченный контексты и домены
+
+Представим себе, что мы выступили в роли проектировщика прогрессивного стартапа. Все мы любим остывшую пиццу, ругаться с курьерами и часами заполнять формы на сайте. Поэтому мы придумали замечательный стартап "Четыре черепахи и одна крыса":
+- Есть сайт, на котором регистрируются пиццерии и вывешивают свои актуальные блюда.
+- У данных пиццерий нет своей курьерской службы.
+- Есть заказчики, которые не могут дойти до пиццерии, но они готовы сделать заказ через сайт или мобильное приложение.
+- Киллер 'фича': курьерами выступают не специально нанятый персонал, а простые люди, зарегистрировавшиеся через мобильно приложение
+- Курьеры получают заказы, после их исполнения им приходит оплата за проделанную работу. 
+- Ждать таких курьеров приходится дольше, но и доставка, а соответственно и пицца выходит дешевле.
+
+Давайте вспомним документацию, которую мы описывали в предыдущей главе. Там в нашем едином словаре использовался термин _регистрация_. Но в данном проекте мы имеем их несколько:
+- Регистрация заказчика
+- Регистрация пиццерии
+- Регистрация курьера
+- Регистрация заказа
+
+Унифицированный язык принадлежит к ограниченному контексту. Домен приведенной выше документации - 'Система авторизации'. Давайте попробуем выделить домены для нашего стартапа.
+
+Но прежде чем мы к этому приступим, давайте немного разберемся в терминологии, что такое домен и что такое ограниченный контекст. 
+
+> Домен (Domain) - это репрезентация реальной бизнес структуры, решающая определенную задачу.
+
+Например: Система логистики, Система оплаты, Система авторизации, Система управления заказами.
+
+Домен делится на сабдомены, которые описывают меньшие структуры, например: корзина заказов, система построения маршрутов.
+
+Каждый домен имеет ограниченную зону ответственности - лимитированную функциональность. 
+
+> Ограниченный контекст (Bounded context) - набор ограничений домена, помогающий сфокусироваться домену только на одной задаче для ее лучшего решения.   
+
+Мне нравится представлять этот термин в виде такой абстракции. Домен - это круг. Ограниченный контекст - это окружность.
+
+![Domain-context](_imgs/domain_context.jpeg)
+
+Еще в терминологии DDD выделяют ядро. 
+
+> Ядро (Core domain) - самый главный домен, наиболее емко характеризующий ваш бизнес.
+
+Итак, домены проекта "Четыре черепахи и одна крыса":
+
+__Работа с пиццерией__ (Pizzarias)
+
+_Контекст_: b2b все, что относится к работе с пиццериями
+
+_Сабдомены_:
+- регистрация новых пиццерий
+- добавление ассортимента
+- обновления статуса наличия того или иного товара
+
+__Работа с клиентом__ (Clients)
+
+_Контекст_: b2c, все что относится к работе с заказчиками пиццы
+
+_Сабдомены_:	
+- просмотр ассортимента
+- информационные материалы
+
+__Работа с курьерами__ (Delivery system)
+
+_Контекст_: b2e, все что относится к работе с курьерами
+
+_Сабдомены_:	
+- регистрация курьера
+- выдача заданий
+- регистрация заявок на вывод заработанных курьером средств.
+
+__Система заказов__ (Order system)
+ 
+_Контекст_: Ядро. Позволяет координировать все отдельные домены, обеспечивая полный цикл от получения заказа до доставки пиццы пользователю. Не является исполнителем, а исполняет роль дирижера.
+
+_Сабдомены_:
+- принятие заказа 
+- исполнение заказа
+- отслеживание статуса заказа
+
+__Система рассчетов__ (Billing)
+
+_Контекст_: Содержит в себе все финансовые операции. Обеспечивает взаимодействие с процессинговым центром.
+
+_Сабдомены_:
+- прием денег за заказы
+- выдача денег курьерам за выполненную работу
+
+__Система статистки__ (Statistics)
+
+_Контекст_: Сбор и обработка (не выдача) аналитической информации.
+
+_Сабдомены_: 
+- статистики по средствам
+- статистики по заявкам
+
+__Система менеджмента__ (Managment panel)
+
+_Контекст_: Выдача аналитической информации. Инструментарий управленческих решений.
+
+- аналитика на основе собранной статистики
+- премодерация выплат курьерам 
+
+На основе доменов давайте составим его карту. 
+
+> Карта доменов (Context map) - графический инструмент, который позволяет описать связи между отдельными доменами.
+
+![Context-map](_imgs/tourtle_context_map.png )
+
+Карта показывает связи между доменами. Данная карта очень поверхностна, но и предметная область изучена не достаточно. Это первый набросок, переписывая который вы получите ожидаемый результат. 
+
+Самое важное в карте - мы видим связи межу доменами. Такая структура очень хорошо ложится на микросервисную архитектуру:
+
+> Главный принцип микросервисной архитектуры: слабая связанность и сильное сцепление.
+
+Данный принцип дается в книге Сэма Ньюмана - [Создание микросервисов](http://shop.oreilly.com/product/0636920033158.do), это вторая книга, которую вам придется прочесть, чтобы приступить к практическому использованию описанных в данной статье подходов. Что имеется в виду: домены должны быть слабо связанны между собой, но тесно сцеплены внутри. 
+
+Перевод данных терминов взят из официального русского перевода и, возможно, плохо отражает передаваемый смысл. В оригинале термины звучат как: Low coupling (связанность, зацепление, сцепление, сопряженность), high cohesion (связность, прочность).
+
+# Доменное разделение
+
+Хотелось бы поделиться личным опытом - набором осознанных решений. Я не призываю вас использовать эти решения. Но они могут оказаться хорошим выбором, если вы не знаете с чего начать. С получением личного опыта инструментарий будет доработан под ваши нужды.
+
+Основные принципы, которыми мы руководствовались:
+
+- Простота решения. Делать сложные вещи простыми, а не простые сложными.
+- Прагматизм. Всегда нужно смотреть по ситуации, и при отсутствии имеющегося решения вырабатывать новое.  Старайтесь все типизировать, но избегайте догматизма.
+- Код != документация. Код это инструкции для машины, документация это инструкция для людей. Не нужно их путать и выдавать одно за другое.
+- [SOLID](https://subvisual.co/blog/posts/19-solid-principles-in-ruby/)
+
+## Реализация доменов
+
+Очень удобно выделять домены как отдельные микросервисы.
+
+> Микросервисы - это отдельное приложение, реализующее логику одного домена.
+
+В DDD-разработке принципом выделения микросервиса в отдельное приложение будет служить ограниченный контекст. Это не отменяет технический принцип разделения сервисов (если это обусловлено необходимостью обеспечения высокой производительности). Но контекстный принцип будет доминирующим и обязательным.
+
+## Связи между доменами
+
+Связи между доменами это всегда API. Это может быть RESTful json api, gRPC, AMPQ. Мы не будем в рамках данной статьи сравнивать один протокол с другим и выделять их преимущества и недостатки, у каждого из них есть своя область применения. Но все же, остановимся на общих рекомендациях:
+ 
+ __Будте гибкими в выборе протокола и жесткими в однотипности его реализации.__
+ 
+ 
+Выбирайте протокол для каждой пары доменов индивидуально, не старайтесь везде использовать http, возможно, вам где-то понадобится асинхронные очереди и преимущества AMPQ для вас станут очевидными. Не игнорируйте эту возможность потому, что у вас везде RESTful. 
+
+С другой стороны, если вы реализуйте RESTful json, используйте один стандарт структуризации данных. Можете взять готовый например jsonapi или openapi. Если по каким-то причинам готовые решения вас не устраивают и вы чувствуете, что можете разработать свой стандарт - опишите и используйте его. Но применяйте его везде, не разводите "зоопарк" стандартов. Если вам нужно общаться с внешней системой, где про ваши стандарты ничего знают, напишите микросервис адаптер.
+
+![Adapter](_imgs/adapter.png)
+
+
+## Реализация сабдоменов
+
+Как отдельные модули внутри микросервиса.
+
+> Модуль - это реализация сабдомена, путем вынесения логики в отдельное пространство имен (Namespace) в рамках одного микросервиса. 
+
+Как это все выглядит? Давайте рассмотрим на примере. Как мы помним, у нас есть домен __Работа с курьерами__ (Delivery system) - у этого домена есть три сабдомена:
+- регистрация курьера (registration)
+- выдача заданий (tasks)
+- регистрация заявок на вывод заработанных курьером средств (withdrawal)
+- проверка того, что ваш микросервис работает, вспомогательное, техническое средство(healt_checker)
+
+Представим это все в виде структуры папок:
+```bash
+$ tree --dirsfirst delivery_system
+
+ delivery_system
+ ├── app/
+ │   ├── health_checker/
+ │   │   └── endpoints.rb
+ │   ├── registrations/
+ │   │   ├── entities/
+ │   │   ├── forms/
+ │   │   ├── repositories/
+ │   │   ├── interactor/
+ │   │   ├── services/
+ │   │   ├── validations/
+ │   │   ├── endpoints.rb
+ │   │   └── helpers.rb
+ │   ├── tasks
+ │   │   ├── entities/
+ │   │   ├── queries/
+ │   │   ├── repositories/
+ │   │   ├── endpoints.rb
+ │   │   └── helpers.rb
+ │   └── withdrawals
+ │       ├── entities/
+ │       ├── forms/
+ │       ├── repositories/
+ │       ├── interactor/
+ │       ├── services/
+ │       ├── validations/
+ │       ├── endpoints.rb
+ │       └── helpers.rb
+ ├── config/
+ ├── db/
+ ├── docs/
+ ├── lib/
+ │   ├── schemas/
+ │   └── values/
+ ├── public
+ ├── specs
+ ├── config.ru
+ ├── Gemfile
+ ├── Gemfile.lock
+ ├── Rakefile
+ └── README.md
+```
+
+Каждая папка в директории `apps/` реализует тот или иной сабдомен, внутри каждого домена есть различные паттерны: `entities`, `forms`, `services` и др. Мы рассмотрим каждый из применяемых паттернов подробно в одной из будущих статей.
+
+Каждый такой паттерн реализован в соответствующем пространстве имен (Namespace). Например форма создания завяки на выплату курьеру:
+
+```ruby
+module Withdrawal # Имя сабдомена
+  module Forms #Реализуемый паттерн
+    class Create
+      
+    end
+  end
+end
+```
+
+## Связи между сабдоменами
+
+Давайте рассмотрим конкретный пример. У нас есть учетная запись курьера: `Registrations::Entities::Account`. Она относится к сабдомену `Registrations` - так как мы рассматриваем данный домен не как процесс регистрации, а, скорее, как учетный стол и регистрационную книгу, о чем указанно в нашей документации для бизнеса.
+
+У нас есть два _Процесса_ при исполнении которых мы обращаемся к этой учетной записи.
+
+- Создание учетной записи (Registration)
+- Создание заявки на вывод заработанных курьером средств (Wihtdrawal)
+
+Как мы видим эти два процесса относятся к разным сабдоменам - Registration и Wihtdrawal. 
+
+```ruby
+module Registrations
+  module Serivices 
+    class CreateAccount
+      def call
+        account = Entities::Account.new
+      end
+    end
+  end
+end
+
+module Withdrwals
+  module Serivices 
+    class CreateOrder
+      def call
+        account = Registrations::Entities::Account.new
+      end
+    end
+  end
+end
+```
+
+В первом обращение ообращение к классу будет реализованно через вызов `Entities::Account`. А во втором случае через явный вызов `Registrations::Entities::Account`. Т.е. если мы явно указываем сабдомен, значит класс  из другого сабдомена и так мы четко обозначаем связь.
+
+Если класс не относится явно ни к одному из сабдоменов, есть смысл выносить его в папку `lib/`. Как правило, это классы, реализующие паттерн 'ValueObject'. Мы рассмотри этот паттерн подробнее в одной из следующих статей.
+
+
+# Реализация через модель
+
+
+Процитирую Эрика Эванса:
+
+> Если архитектура программы или хотя бы некая ее центральная часть, не соответствует структуре модели предметной области, то такая модель практически бесполезна, и правильность работы программы тоже нужно поставить под подозрение. В то же время слишком сложные взаимосвязи между моделями и функциями в программной архитектуре трудно поддаются пониманию, и на практике их сложно сохранить по мере изменения архитектуры. 
+
+Давайте вспомним пример хорошей модели, который я уже приводил в начале этой статьи - топографическая карта. У нас стоит цель - иметь возможность быстро найти расстояние между двумя населенными пунктами. Мы могли бы воспользоваться справочником-таблицей с указанием двух точек между городами. А можем воспользоваться картой. И там и там мы получим один и тот же результат примерно за одно и то же время. Но карта компактнее, она точнее отображает предметную область, она универсальнее. Карта как модель невероятно выразительна. И если рассматривать ее в рамках данной задачи, то померить расстояние удобнее по карте, чем на самой территории, которую она отражает. Модель, которая отражает предметную область, может превосходить ее в некоторых свойствах. Это действительно потрясает воображение.
+
+Реализация модели это всегда творческий процесс с непредсказуемым результатом. Качество вашего кода это не его производительность, и не его сложность, это простота и выразительность. Совершенствуйте его через постоянный рефакторинг, делайте его гибким и отсекайте все лишнее. Разделите слой, который будет отвечать за бизнес логику модели,  от слоев, чья необходимость обусловлена технической реализацией. О том, как нам удалось это сделать, будет рассказано в дальнейшем.  
+
+---
+- Проблемно-ориентированное проектирование, Эрик Дж. Эванс
+- Создание микросервисов, Сэм Ньюман
+- http://gorodinski.com/blog/2013/04/29/sub-domains-and-bounded-contexts-in-domain-driven-design-ddd/
+- https://martinfowler.com/bliki/BoundedContext.html
+- https://habr.com/post/316438/
+- https://dotnetcodr.com/2015/08/06/domain-driven-design-with-web-api-revisited-part-1-introduction/
+- История абдеритов, Кристов Мартин Виланд