В статью об Эргономичной архитектуре добалены правила кодирования портов

Author: d-r-q

content/docs/models/ergo-arch.adoc

@@ -58,68 +58,87 @@ weight: 875
 
 == Проекция структуры данных (модель данных)
 
-Проекция структуры данных по большому счёту является комбинацией проверенных идей из DDD, Функциональной архитектуры и Entity-Relation-модели с небольшими отличиями.
+Проекция структуры данных является комбинацией идей из DDD, Функциональной архитектуры, Entity-Relation-модели и ECS архитектуры.
 
 === Номенклатура блоков
 
-Концептуальными базовыми блоками этой проекции являются:
+Модель данных ЭА состоит из сущностей, которые, в свою очередь могут включать компоненты.
+Компоненты могут принадлежать только одному владельцу - сущности или другому компоненту.
+Сущность со всеми своими компонентами является единицей хранения - она загружается из хранилища и сохраняется в нём целиком со всеми компонентами.
 
-. Сущности - объекты обладающие идентичностью;
-. Объекты-значения - доменно-специфичные составные объекты, не обладающие идентичностью;
-. Агрегаты - кластер сущностей и объектов-значений, жёстко объединённых общим жизненным циклом.
+И у сущностей, и у компонентов есть атрибуты.
+Атрибут может быть простым (имя, цена) или составным - то есть компонентом (позиция заказа с количеством и ссылкой на продукт).
+Кроме того, атрибуты могут быть скалярами (цена заказа) и коллекциями примитивов или компонентов (список позиций заказа).
 
-Номинально, номенклатура блоков полностью совпадает с DDD.
-Однако есть ряд отличий:
+Сущности бывают двух типов:
 
-. В ЭА допустимо ссылаться на сущности, не являющиеся корнем агрегата;
-. Базовым критерием объединения сущностей в агрегаты является их жизненный цикл, а не инварианты, которые необходимо обеспечить.
+. Коренная сущность.
+  Это самостоятельная сущность обладающая собственной идентичностью - заказ, клиент, продукт и т. д.;
+. Аспект другой сущности.
+  Сущность-аспект, это фактически компонент, который был повышен до сущности по дизайнерским или техническим причинам.
+  Например, если в предметной области встречаются заказы с сотнями позиций, то в модели позиция может быть сделана сущностью-аспектом, для того чтобы повысить эффективность работы с БД в реализации модели.
+  Или компонент "Адрес доставки" сущности "Заказ" может быть сделан сущностью-аспектом, если эта информация нужна  модулю, отличному от того, который управляет коренной сущностью "Заказ";
 
-=== Связи между блоками
-
-У связи между блоками есть два атрибута: сила (слабая или сильная) и кардинальность (один, немного, много).
-
-Сила связи это аналог связей внутри и между агрегатами в DDD и связей между обычными и стержневыми и слабыми сущностями в ER-модели.
+Коренная сущность со всеми её компонентами и аспектами называется агрегатом.
 
-Для владеющих связей, при удалении блока-владельца удаляются и все блоки, с которым он связан владеющей связью.
-Для невладеющих связей недопустимо удалять целевой блок, при наличии ссылающихся на неё блоков.
+=== Связи между блоками
 
-ЭА разделяет связи 1-к-немногим и 1-ко-многим.
-Связь один к немногим - это частый случай связи 1-ко-многим про который вы на этапе проектирования можете сказать, что в этой связи связи будет участвовать определённое, ограниченное и небольше количество сущностей.
+В модели данных ЭА есть только связи один-к-одному и один-ко-многим.
+Связей многие-ко-многим нет.
 
-Связей многие-ко-многим в ЭА нет.
-Если два класса/типа агрегата могут быть связаны отношением многие-ко-многим, то в модели они отображаются одним из двух вариантов:
+Так же связь может быть владеющей и не владеющей.
+Связи между сущностями и компонентами (и между компонентами), а также между коренной сущностью и сущностью-аспектом является владеющей.
+Связи между агрегатами являются не владеющими.
 
-. Если на самом деле отношение является многие-к-немногим, то в агрегат на стороне "многие" добавляется объект-значение с невладеющей связью с другим агрегатом, который связан отношениме немногие-к-одному с одной из сущностей или объектов-значения агрегата;
-. В противном случае для отношения заводится самостоятельный агрегат с двумя невладеющими связями с основными агрегатами (аля связующая таблица в реляционной модели)
 
-Ограничения на связи между блоками:
 
-. Сущность не может быть "владеемой" несколькими другими сущностями (читай: сущность может входить только в один агрегат);
-. Связи между сущностями должны образовывать направленный ацикличный граф.
+=== Кодирование блоков
 
-При следовании этим правилам в графе структуры данных образуется три слоя:
+[NOTE]
+====
+Здесь и далее в качестве примеров кодирования я использую терминологию Kotlin.
+Однако ЭА может быть реализована на любом тюринг-полном языке - хоть Си, хоть Хаскель, разница лишь в том, придётся ли при этом бороться с сами языком.
+Борьбы с языком не будет, если он мультипарадигменный - поддерживает и императивную, и объектную и функциональную модель программирования.
+====
 
-. слой генеричных/универсальных агрегатов;
-. слой ключевых сущностей системы;
-. слой вспомогательных сущностей системы.
+И сущности и компоненты кодируются неизменяемыми `data class`-ами.
 
-=== Кодирование блоков
+Связи между сущностями и компонентами кодируются атрибутом сущности с типом компонента
 
-В код попадают только сущности и объекты-значения.
-И те и другие кодируются в виде неизменяемых классов и различаются наличием или отсутствием поля-идентификатора.
+Связи между сущностью-аспектом и коренной сущностью кодируются атрибутом сущности-аспекта с типом идентификатора^*^.
 
 [NOTE]
 ====
-Здесь и далее в качестве примеров кодирования я использую терминалогию Kotlin.
-Однако ЭА может быть реализована на любом тюринг-полном языке - хоть Си, хоть Хаскель, разница лишь в том, придётся ли при этом бороться с сами языком.
-Борьбы с языком не будет, если он мультипарадигменный - поддерживает и императивную, и объектную и функциональную модель программирования.
-И, на самом деле, большинство современных языков таковыми являются - Java, C#, Python, JavaScript, TypeScript, Swift, Rust, F#, Clojure - только то, про что я сходу могу сказать, что точно подходит.
+^*^ Здесь и далее под "типом идентификатора" подразумевается простой тип, как правило - UUID, Long или String.
 ====
 
-Владеющие связи кодируются полем со ссылкой на целевой объект.
-Не владеющие связи кодируются полем с типом-обёрткой вокруг идентификатора целевого агрегата.
+Для связи один-к-одному атрибут идентификатора является одновременно и ссылкой на коренную сущность.
+Для связи один-ко-многим атрибут идентификатора сущности-аспекта делается составным и включает в себя ссылку на коренную сущность и идентификатор сущности-аспекта.
 
-Очевидно, связи один-к-одном кодируются скалярным типом, а связи один-к-немногим - типом-коллекцией - списком, множеством или мапой
+Связи между агрегатами кодируются атрибутом ссылающейся сущности или компонента с типом.
+
+[source,kotlin]
+----
+// Компонент
+data class OrderItem(
+  val quantity: Int,
+  val productRef: ProductRef<UUID>
+)
+
+// Коренная-сущность
+data class Order(
+  val id: UUID,
+  val number: String,
+  val items: List<OrderItem>
+)
+
+// Сущность-ассоциация
+data class ShippingAddress(
+  val id: OrderRef<UUID>,
+  val city: String,
+  val street: String
+)
+----
 
 === Примеры/Паттерны
 
@@ -200,6 +219,10 @@ weight: 875
 А совсем вымышленной фичей могла бы возможность для терапевтов и клиентов превращаться друг в друга.
 Условно когда терапевт по свеому номеру телефона записывается на приём к другому терапевту, то ему не заводится отдельный юзер, а заводится новый клиент, который привязывается к тому же юзеру.
 
+==== Иерархия компонентов
+
+(#todo: #)
+
 == Проекция структуры компонентов
 
 Концептуальной моделью структуры состояния является https://azhidkov.pro/effects-diagram/specification-html/#_%D0%BA%D0%BE%D0%BD%D1%86%D0%B5%D0%BF%D1%82%D1%83%D0%B0%D0%BB%D1%8C%D0%BD%D0%B0%D1%8F_%D0%BC%D0%BE%D0%B4%D0%B5%D0%BB%D1%8C[диаграмма эффектов] - диаграмма описывающая элементы состояния системы - ресурсы, операции системы и, ключевое, связи операций с ресурсами - эффекты.
@@ -247,6 +270,9 @@ weight: 875
 
 Количество публичных методов в портах и ресурсах ограниченно разумными на ваш взгляд пределами.
 
+Методы портов могу содержать в себе только один вызов операции или ресурса.
+Когнитивная сложность метода порта не может превышать 1.
+
 Классы операций могут иметь только один публичный метод.
 
 Доменные операции кодируются либо процедурами (top-level функциями или статическими методами), получающими все необходимые ресурсы в параметрах, либо классами, которые инстанциируются "вручную" внутри операций и могут обращаться только к ресурсам операции.