feat(enrichment): apply semantic markup

domain/src/main/java/com/homebox/lens/domain/model/CustomField.kt

@@ -1,6 +1,6 @@
 // [PACKAGE] com.homebox.lens.domain.model
 // [FILE] CustomField.kt
-// [SEMANTICS] data_structure, entity, custom_field
+// [SEMANTICS] domain, model, custom_field
 package com.homebox.lens.domain.model
 
 // [ENTITY: DataClass('CustomField')]

domain/src/main/java/com/homebox/lens/domain/model/GroupStatistics.kt

@@ -1,6 +1,6 @@
 // [PACKAGE] com.homebox.lens.domain.model
 // [FILE] GroupStatistics.kt
-// [SEMANTICS] data_structure, statistics
+// [SEMANTICS] domain, model, statistics
 package com.homebox.lens.domain.model
 
 // [ENTITY: DataClass('GroupStatistics')]

domain/src/main/java/com/homebox/lens/domain/model/Image.kt

@@ -1,6 +1,6 @@
 // [PACKAGE] com.homebox.lens.domain.model
 // [FILE] Image.kt
-// [SEMANTICS] data_structure, entity, image
+// [SEMANTICS] domain, model, image
 package com.homebox.lens.domain.model
 
 // [ENTITY: DataClass('Image')]

domain/src/main/java/com/homebox/lens/domain/model/Item.kt

@@ -1,6 +1,6 @@
 // [PACKAGE] com.homebox.lens.domain.model
 // [FILE] Item.kt
-// [SEMANTICS] domain, model
+// [SEMANTICS] domain, model, item, data_model
 package com.homebox.lens.domain.model
 
 // [IMPORTS]
@@ -12,35 +12,40 @@ import com.homebox.lens.domain.model.Image
 // [ENTITY: DataClass('Item')]
 // [RELATION: DataClass('Item')] -> [DEPENDS_ON] -> [DataClass('Location')]
 // [RELATION: DataClass('Item')] -> [DEPENDS_ON] -> [DataClass('Label')]
+// [RELATION: DataClass('Item')] -> [DEPENDS_ON] -> [DataClass('CustomField')]
 /**
- * @summary Представляет собой вещь в инвентаре.
- * @param id Уникальный идентификатор вещи.
- * @param name Название вещи.
- * @param description Описание вещи.
- * @param image Url изображения.
- * @param location Местоположение вещи.
- * @param labels Список меток, присвоенных вещи.
- * @param purchasePrice Цена покупки вещи.
- * @param createdAt Дата создания.
- * @param archived Архивирована ли вещь.
- * @param assetId Идентификатор актива.
- * @param fields Пользовательские поля.
- * @param insured Застрахована ли вещь.
- * @param lifetimeWarranty Пожизненная гарантия.
- * @param manufacturer Производитель.
- * @param modelNumber Номер модели.
- * @param notes Дополнительные заметки.
- * @param parentId ID родительского элемента.
- * @param purchaseFrom Место покупки.
- * @param purchaseTime Время покупки.
- * @param serialNumber Серийный номер.
- * @param soldNotes Заметки о продаже.
- * @param soldPrice Цена продажи.
- * @param soldTime Время продажи.
- * @param soldTo Кому продано.
- * @param syncChildItemsLocations Синхронизировать местоположения дочерних элементов.
- * @param warrantyDetails Детали гарантии.
- * @param warrantyExpires Дата окончания гарантии.
+ * @summary A comprehensive data model representing an inventory item.
+ * @param id The unique identifier for the item.
+ * @param name The name of the item.
+ * @param description A detailed description of the item.
+ * @param quantity The number of units of this item.
+ * @param image An optional URL to an image of the item.
+ * @param location The physical or logical location of the item.
+ * @param labels A list of tags or categories associated with the item.
+ * @param purchasePrice The price at which the item was purchased.
+ * @param createdAt The timestamp when the item was created.
+ * @param archived A flag indicating if the item is archived.
+ * @param assetId An external asset identifier.
+ * @param fields A list of custom-defined fields for the item.
+ * @param insured A flag indicating if the item is insured.
+ * @param lifetimeWarranty A flag indicating if the item has a lifetime warranty.
+ * @param manufacturer The manufacturer of the item.
+ * @param modelNumber The model number of the item.
+ * @param notes Any additional notes about the item.
+ * @param parentId The ID of a parent item, if this is a child item.
+ * @param purchaseFrom The place where the item was purchased.
+ * @param purchaseTime The timestamp of the purchase.
+ * @param serialNumber The serial number of the item.
+ * @param soldNotes Notes related to the sale of the item.
+ * @param soldPrice The price at which the item was sold.
+ * @param soldTime The timestamp of the sale.
+ * @param soldTo The person or entity the item was sold to.
+ * @param syncChildItemsLocations A flag to sync locations of child items.
+ * @param warrantyDetails Details about the item's warranty.
+ * @param warrantyExpires The expiration date of the warranty.
+ * @invariant The 'id' must not be blank.
+ * @invariant The 'name' must not be blank.
+ * @invariant The 'quantity' must be non-negative.
  */
 data class Item(
     val id: String,

domain/src/main/java/com/homebox/lens/domain/model/ItemAttachment.kt

@@ -1,6 +1,6 @@
 // [PACKAGE] com.homebox.lens.domain.model
 // [FILE] ItemAttachment.kt
-// [SEMANTICS] data_structure, entity, attachment
+// [SEMANTICS] domain, model, attachment
 package com.homebox.lens.domain.model
 
 // [ENTITY: DataClass('ItemAttachment')]

domain/src/main/java/com/homebox/lens/domain/model/ItemCreate.kt

@@ -1,24 +1,38 @@
 // [PACKAGE] com.homebox.lens.domain.model
 // [FILE] ItemCreate.kt
-// [SEMANTICS] data_structure, entity, input, create
+// [SEMANTICS] domain, model, item_creation
 package com.homebox.lens.domain.model
 
 // [ENTITY: DataClass('ItemCreate')]
+// [RELATION: DataClass('ItemCreate')] -> [DEPENDS_ON] -> [DataClass('Location')]
+// [RELATION: DataClass('ItemCreate')] -> [DEPENDS_ON] -> [DataClass('Label')]
 /**
- * @summary Модель данных для создания новой "Вещи".
- * @param name Название вещи (обязательно).
- * @param assetId Идентификатор актива.
- * @param description Описание.
- * @param notes Заметки.
- * @param serialNumber Серийный номер.
- * @param quantity Количество.
- * @param value Стоимость.
- * @param purchasePrice Цена покупки.
- * @param purchaseDate Дата покупки.
- * @param warrantyUntil Гарантия до.
- * @param locationId ID местоположения.
- * @param parentId ID родительской вещи.
- * @param labelIds Список ID меток.
+ * @summary Data model for creating a new item.
+ * @param name The name of the item (required).
+ * @param description An optional description of the item.
+ * @param quantity The number of units of this item.
+ * @param archived A flag indicating if the item is archived.
+ * @param assetId An external asset identifier.
+ * @param insured A flag indicating if the item is insured.
+ * @param lifetimeWarranty A flag indicating if the item has a lifetime warranty.
+ * @param manufacturer The manufacturer of the item.
+ * @param modelNumber The model number of the item.
+ * @param notes Any additional notes about the item.
+ * @param parentId The ID of a parent item, if this is a child item.
+ * @param purchaseFrom The place where the item was purchased.
+ * @param purchasePrice The price at which the item was purchased.
+ * @param purchaseTime The timestamp of the purchase.
+ * @param serialNumber The serial number of the item.
+ * @param soldNotes Notes related to the sale of the item.
+ * @param soldPrice The price at which the item was sold.
+ * @param soldTime The timestamp of the sale.
+ * @param soldTo The person or entity the item was sold to.
+ * @param syncChildItemsLocations A flag to sync locations of child items.
+ * @param warrantyDetails Details about the item's warranty.
+ * @param warrantyExpires The expiration date of the warranty.
+ * @param locationId The ID of the item's location.
+ * @param labelIds A list of IDs for labels to associate with the item.
+ * @invariant The 'name' must not be blank.
  */
 data class ItemCreate(
     val name: String,

domain/src/main/java/com/homebox/lens/domain/model/ItemOut.kt

@@ -1,43 +1,52 @@
 // [PACKAGE] com.homebox.lens.domain.model
 // [FILE] ItemOut.kt
-// [SEMANTICS] data_structure, entity, detailed
+// [SEMANTICS] domain, model, item_detailed
 package com.homebox.lens.domain.model
 
 // [ENTITY: DataClass('ItemOut')]
+// [RELATION: DataClass('ItemOut')] -> [DEPENDS_ON] -> [DataClass('LocationOut')]
+// [RELATION: DataClass('ItemOut')] -> [DEPENDS_ON] -> [DataClass('ItemSummary')]
+// [RELATION: DataClass('ItemOut')] -> [DEPENDS_ON] -> [DataClass('LabelOut')]
+// [RELATION: DataClass('ItemOut')] -> [DEPENDS_ON] -> [DataClass('ItemAttachment')]
+// [RELATION: DataClass('ItemOut')] -> [DEPENDS_ON] -> [DataClass('Image')]
+// [RELATION: DataClass('ItemOut')] -> [DEPENDS_ON] -> [DataClass('CustomField')]
+// [RELATION: DataClass('ItemOut')] -> [DEPENDS_ON] -> [DataClass('MaintenanceEntry')]
 /**
- * @summary Полная модель данных для представления "Вещи" со всеми полями.
- * @param id Уникальный идентификатор.
- * @param name Название.
- * @param assetId Идентификатор актива.
- * @param description Описание.
- * @param notes Заметки.
- * @param serialNumber Серийный номер.
- * @param quantity Количество.
- * @param isArchived Флаг архивации.
- * @param purchasePrice Цена покупки.
- * @param purchaseTime Время покупки.
- * @param purchaseFrom Место покупки.
- * @param warrantyExpires Дата окончания гарантии.
- * @param warrantyDetails Детали гарантии.
- * @param lifetimeWarranty Пожизненная гарантия.
- * @param insured Застрахована ли вещь.
- * @param manufacturer Производитель.
- * @param modelNumber Номер модели.
- * @param soldPrice Цена продажи.
- * @param soldTime Время продажи.
- * @param soldTo Кому продано.
- * @param soldNotes Заметки о продаже.
- * @param syncChildItemsLocations Синхронизировать местоположения дочерних элементов.
- * @param location Местоположение.
- * @param parent Родительская вещь (если есть).
- * @param children Дочерние вещи.
- * @param labels Список меток.
- * @param attachments Список вложений.
- * @param images Список изображений.
- * @param fields Список кастомных полей.
- * @param maintenance Список записей об обслуживании.
- * @param createdAt Дата и время создания.
- * @param updatedAt Дата и время последнего обновления.
+ * @summary A comprehensive data model representing a fully-detailed inventory item.
+ * @param id The unique identifier for the item.
+ * @param name The name of the item.
+ * @param assetId An external asset identifier.
+ * @param description A detailed description of the item.
+ * @param notes Any additional notes about the item.
+ * @param serialNumber The serial number of the item.
+ * @param quantity The number of units of this item.
+ * @param isArchived A flag indicating if the item is archived.
+ * @param purchasePrice The price at which the item was purchased.
+ * @param purchaseTime The timestamp of the purchase.
+ * @param purchaseFrom The place where the item was purchased.
+ * @param warrantyExpires The expiration date of the warranty.
+ * @param warrantyDetails Details about the item's warranty.
+ * @param lifetimeWarranty A flag indicating if the item has a lifetime warranty.
+ * @param insured A flag indicating if the item is insured.
+ * @param manufacturer The manufacturer of the item.
+ * @param modelNumber The model number of the item.
+ * @param soldPrice The price at which the item was sold.
+ * @param soldTime The timestamp of the sale.
+ * @param soldTo The person or entity the item was sold to.
+ * @param soldNotes Notes related to the sale of the item.
+ * @param syncChildItemsLocations A flag to sync locations of child items.
+ * @param location The physical or logical location of the item.
+ * @param parent A summary of the parent item, if one exists.
+ * @param children A list of summaries for child items.
+ * @param labels A list of tags or categories associated with the item.
+ * @param attachments A list of file attachments for the item.
+ * @param images A list of images for the item.
+ * @param fields A list of custom-defined fields for the item.
+ * @param maintenance A list of maintenance records for the item.
+ * @param createdAt The timestamp when the item was created.
+ * @param updatedAt The timestamp when the item was last updated.
+ * @invariant The 'id' must not be blank.
+ * @invariant The 'name' must not be blank.
  */
 data class ItemOut(
     val id: String,

domain/src/main/java/com/homebox/lens/domain/model/ItemSummary.kt

@@ -1,21 +1,26 @@
 // [PACKAGE] com.homebox.lens.domain.model
 // [FILE] ItemSummary.kt
-// [SEMANTICS] data_structure, entity, summary
+// [SEMANTICS] domain, model, item_summary
 package com.homebox.lens.domain.model
 
 // [ENTITY: DataClass('ItemSummary')]
+// [RELATION: DataClass('ItemSummary')] -> [DEPENDS_ON] -> [DataClass('Image')]
+// [RELATION: DataClass('ItemSummary')] -> [DEPENDS_ON] -> [DataClass('LabelOut')]
+// [RELATION: DataClass('ItemSummary')] -> [DEPENDS_ON] -> [DataClass('LocationOut')]
 /**
- * @summary Сокращенная модель данных для представления "Вещи" в списках.
- * @param id Уникальный идентификатор вещи.
- * @param name Название вещи.
- * @param assetId Идентификатор актива.
- * @param image Основное изображение. Может быть null.
- * @param isArchived Флаг архивации.
- * @param labels Список меток.
- * @param location Местоположение. Может быть null.
- * @param value Стоимость.
- * @param createdAt Дата и время создания.
- * @param updatedAt Дата и время последнего обновления.
+ * @summary A summarized data model for representing an item in a list.
+ * @param id The unique identifier for the item.
+ * @param name The name of the item.
+ * @param assetId An external asset identifier.
+ * @param image The primary image for the item, if available.
+ * @param isArchived A flag indicating if the item is archived.
+ * @param labels A list of tags or categories associated with the item.
+ * @param location The physical or logical location of the item.
+ * @param value The monetary value of the item.
+ * @param createdAt The timestamp when the item was created.
+ * @param updatedAt The timestamp when the item was last updated.
+ * @invariant The 'id' must not be blank.
+ * @invariant The 'name' must not be blank.
  */
 data class ItemSummary(
     val id: String,

domain/src/main/java/com/homebox/lens/domain/model/ItemUpdate.kt

@@ -1,25 +1,39 @@
 // [PACKAGE] com.homebox.lens.domain.model
 // [FILE] ItemUpdate.kt
-// [SEMANTICS] data_structure, entity, input, update
+// [SEMANTICS] domain, model, item_update
 package com.homebox.lens.domain.model
 
 // [ENTITY: DataClass('ItemUpdate')]
+// [RELATION: DataClass('ItemUpdate')] -> [DEPENDS_ON] -> [DataClass('Location')]
+// [RELATION: DataClass('ItemUpdate')] -> [DEPENDS_ON] -> [DataClass('Label')]
 /**
- * @summary Модель данных для обновления существующей "Вещи".
- * @param name Название вещи.
- * @param assetId Идентификатор актива.
- * @param description Описание.
- * @param notes Заметки.
- * @param serialNumber Серийный номер.
- * @param quantity Количество.
- * @param isArchived Флаг архивации.
- * @param value Стоимость.
- * @param purchasePrice Цена покупки.
- * @param purchaseDate Дата покупки.
- * @param warrantyUntil Гарантия до.
- * @param locationId ID местоположения.
- * @param parentId ID родительской вещи.
- * @param labelIds Список ID меток для полной замены.
+ * @summary Data model for updating an existing item.
+ * @param id The unique identifier of the item to update.
+ * @param name The new name of the item.
+ * @param description An optional new description for the item.
+ * @param quantity The new number of units of this item.
+ * @param archived A flag indicating if the item is archived.
+ * @param assetId An external asset identifier.
+ * @param insured A flag indicating if the item is insured.
+ * @param lifetimeWarranty A flag indicating if the item has a lifetime warranty.
+ * @param manufacturer The manufacturer of the item.
+ * @param modelNumber The model number of the item.
+ * @param notes Any additional notes about the item.
+ * @param parentId The ID of a parent item, if this is a child item.
+ * @param purchaseFrom The place where the item was purchased.
+ * @param purchasePrice The price at which the item was purchased.
+ * @param purchaseTime The timestamp of the purchase.
+ * @param serialNumber The serial number of the item.
+ * @param soldNotes Notes related to the sale of the item.
+ * @param soldPrice The price at which the item was sold.
+ * @param soldTime The timestamp of the sale.
+ * @param soldTo The person or entity the item was sold to.
+ * @param syncChildItemsLocations A flag to sync locations of child items.
+ * @param warrantyDetails Details about the item's warranty.
+ * @param warrantyExpires The expiration date of the warranty.
+ * @param locationId The ID of the item's new location.
+ * @param labelIds A list of IDs for labels to associate with the item, replacing existing ones.
+ * @invariant The 'id' must not be blank.
  */
 data class ItemUpdate(
     val id: String,

domain/src/main/java/com/homebox/lens/domain/model/Label.kt

@@ -1,13 +1,15 @@
 // [PACKAGE] com.homebox.lens.domain.model
 // [FILE] Label.kt
-// [SEMANTICS] domain, model
+// [SEMANTICS] domain, model, label
 package com.homebox.lens.domain.model
 
 // [ENTITY: DataClass('Label')]
 /**
- * @summary Представляет собой метку (тег), которую можно присвоить вещи.
- * @param id Уникальный идентификатор метки.
- * @param name Название метки.
+ * @summary Represents a label or tag that can be assigned to an item.
+ * @param id The unique identifier of the label.
+ * @param name The name of the label.
+ * @invariant The 'id' must not be blank.
+ * @invariant The 'name' must not be blank.
  */
 data class Label(
     val id: String,

domain/src/main/java/com/homebox/lens/domain/model/LabelCreate.kt

@@ -1,14 +1,15 @@
 // [PACKAGE] com.homebox.lens.domain.model
 // [FILE] LabelCreate.kt
-// [SEMANTICS] data_structure, contract, label, create
+// [SEMANTICS] domain, model, label, create
 package com.homebox.lens.domain.model
 
 // [ENTITY: DataClass('LabelCreate')]
 /**
- * @summary Модель с данными, необходимыми для создания новой метки.
- * @param name Название новой метки. Обязательное поле.
- * @param color Цвет метки в формате HEX. Необязательное поле.
- * @invariant name не может быть пустым.
+ * @summary Data model for creating a new label.
+ * @param name The name of the new label (required).
+ * @param color The color of the label in HEX format (optional).
+ * @param description An optional description for the label.
+ * @invariant 'name' cannot be blank.
  */
 data class LabelCreate(
     val name: String,

domain/src/main/java/com/homebox/lens/domain/model/LabelOut.kt

@@ -1,17 +1,20 @@
 // [PACKAGE] com.homebox.lens.domain.model
 // [FILE] LabelOut.kt
-// [SEMANTICS] data_structure, entity, label
+// [SEMANTICS] domain, model, label
 package com.homebox.lens.domain.model
 
 // [ENTITY: DataClass('LabelOut')]
 /**
- * @summary Модель данных для представления метки (тега).
- * @param id Уникальный идентификатор.
- * @param name Название метки.
- * @param color Цвет метки в формате HEX (например, "#FF0000").
- * @param isArchived Флаг, указывающий, заархивирована ли метка.
- * @param createdAt Дата и время создания.
- * @param updatedAt Дата и время последнего обновления.
+ * @summary Data model for representing a label (tag).
+ * @param id The unique identifier.
+ * @param name The name of the label.
+ * @param description An optional description for the label.
+ * @param color The color of the label in HEX format (e.g., "#FF0000").
+ * @param isArchived A flag indicating if the label is archived.
+ * @param createdAt The timestamp when the label was created.
+ * @param updatedAt The timestamp when the label was last updated.
+ * @invariant The 'id' must not be blank.
+ * @invariant The 'name' must not be blank.
  */
 data class LabelOut(
     val id: String,

domain/src/main/java/com/homebox/lens/domain/model/LabelSummary.kt

@@ -1,13 +1,16 @@
 // [PACKAGE] com.homebox.lens.domain.model
 // [FILE] LabelSummary.kt
-// [SEMANTICS] data_structure, entity, label, summary
+// [SEMANTICS] domain, model, label, summary
 package com.homebox.lens.domain.model
 
 // [ENTITY: DataClass('LabelSummary')]
 /**
- * @summary Представляет краткую информацию о метке, обычно возвращаемую после создания.
- * @param id Уникальный идентификатор метки.
- * @param name Название метки.
+ * @summary Represents a brief summary of a label, typically returned after creation.
+ * @param id The unique identifier of the label.
+ * @param name The name of the label.
+ * @param color The color of the label in HEX format.
+ * @invariant The 'id' must not be blank.
+ * @invariant The 'name' must not be blank.
  */
 data class LabelSummary(
     val id: String,

domain/src/main/java/com/homebox/lens/domain/model/LabelUpdate.kt

@@ -1,13 +1,14 @@
 // [PACKAGE] com.homebox.lens.domain.model
 // [FILE] LabelUpdate.kt
-// [SEMANTICS] data_structure, contract, label, update
+// [SEMANTICS] domain, model, label, update
 package com.homebox.lens.domain.model
 
 // [ENTITY: DataClass('LabelUpdate')]
 /**
- * @summary Модель с данными, необходимыми для обновления метки.
- * @param name Название метки.
- * @param color Цвет метки в формате HEX.
+ * @summary Data model for updating a label.
+ * @param name The new name of the label.
+ * @param color The new color of the label in HEX format.
+ * @param description An optional new description for the label.
  */
 data class LabelUpdate(
     val name: String?,

domain/src/main/java/com/homebox/lens/domain/model/Location.kt

@@ -1,13 +1,15 @@
 // [PACKAGE] com.homebox.lens.domain.model
 // [FILE] Location.kt
-// [SEMANTICS] domain, model
+// [SEMANTICS] domain, model, location
 package com.homebox.lens.domain.model
 
 // [ENTITY: DataClass('Location')]
 /**
- * @summary Представляет собой местоположение, где может находиться вещь.
- * @param id Уникальный идентификатор местоположения.
- * @param name Название местоположения.
+ * @summary Represents a location where an item can be.
+ * @param id The unique identifier of the location.
+ * @param name The name of the location.
+ * @invariant The 'id' must not be blank.
+ * @invariant The 'name' must not be blank.
  */
 data class Location(
     val id: String,

domain/src/main/java/com/homebox/lens/domain/model/LocationCreate.kt

@@ -1,14 +1,16 @@
 // [PACKAGE] com.homebox.lens.domain.model
 // [FILE] LocationCreate.kt
-// [SEMANTICS] data_structure, contract, location, create
+// [SEMANTICS] domain, model, location, create
 package com.homebox.lens.domain.model
 
 // [ENTITY: DataClass('LocationCreate')]
 /**
- * @summary Модель с данными, необходимыми для создания нового местоположения.
- * @param name Название нового местоположения. Обязательное поле.
- * @param color Цвет местоположения в формате HEX. Необязательное поле.
- * @invariant name не может быть пустым.
+ * @summary Data model for creating a new location.
+ * @param name The name of the new location (required).
+ * @param parentId The ID of the parent location, if any.
+ * @param color The color of the location in HEX format (optional).
+ * @param description An optional description for the location.
+ * @invariant 'name' cannot be blank.
  */
 data class LocationCreate(
     val name: String,

domain/src/main/java/com/homebox/lens/domain/model/LocationOut.kt

@@ -1,17 +1,19 @@
 // [PACKAGE] com.homebox.lens.domain.model
 // [FILE] LocationOut.kt
-// [SEMANTICS] data_structure, entity, location
+// [SEMANTICS] domain, model, location
 package com.homebox.lens.domain.model
 
 // [ENTITY: DataClass('LocationOut')]
 /**
- * @summary Модель данных для представления местоположения (без счетчика).
- * @param id Уникальный идентификатор.
- * @param name Название местоположения.
- * @param color Цвет в формате HEX.
- * @param isArchived Флаг архивации.
- * @param createdAt Дата и время создания.
- * @param updatedAt Дата и время последнего обновления.
+ * @summary Data model for representing a location (without item count).
+ * @param id The unique identifier.
+ * @param name The name of the location.
+ * @param color The color in HEX format.
+ * @param isArchived A flag indicating if the location is archived.
+ * @param createdAt The timestamp when the location was created.
+ * @param updatedAt The timestamp when the location was last updated.
+ * @invariant The 'id' must not be blank.
+ * @invariant The 'name' must not be blank.
  */
 data class LocationOut(
     val id: String,

domain/src/main/java/com/homebox/lens/domain/model/LocationOutCount.kt

@@ -1,18 +1,21 @@
 // [PACKAGE] com.homebox.lens.domain.model
 // [FILE] LocationOutCount.kt
-// [SEMANTICS] data_structure, entity, location
+// [SEMANTICS] domain, model, location, count
 package com.homebox.lens.domain.model
 
 // [ENTITY: DataClass('LocationOutCount')]
 /**
- * @summary Модель данных для представления местоположения со счетчиком вещей.
- * @param id Уникальный идентификатор.
- * @param name Название местоположения.
- * @param color Цвет в формате HEX.
- * @param isArchived Флаг архивации.
- * @param itemCount Количество вещей в данном местоположении.
- * @param createdAt Дата и время создания.
- * @param updatedAt Дата и время последнего обновления.
+ * @summary Data model for representing a location with an item count.
+ * @param id The unique identifier.
+ * @param name The name of the location.
+ * @param color The color in HEX format.
+ * @param isArchived A flag indicating if the location is archived.
+ * @param itemCount The number of items in this location.
+ * @param createdAt The timestamp when the location was created.
+ * @param updatedAt The timestamp when the location was last updated.
+ * @invariant The 'id' must not be blank.
+ * @invariant The 'name' must not be blank.
+ * @invariant The 'itemCount' must be non-negative.
  */
 data class LocationOutCount(
     val id: String,

domain/src/main/java/com/homebox/lens/domain/model/LocationUpdate.kt

@@ -1,13 +1,14 @@
 // [PACKAGE] com.homebox.lens.domain.model
 // [FILE] LocationUpdate.kt
-// [SEMANTICS] data_structure, contract, location, update
+// [SEMANTICS] domain, model, location, update
 package com.homebox.lens.domain.model
 
 // [ENTITY: DataClass('LocationUpdate')]
 /**
- * @summary Модель с данными, необходимыми для обновления местоположения.
- * @param name Название местоположения.
- * @param color Цвет местоположения в формате HEX.
+ * @summary Data model for updating a location.
+ * @param name The new name of the location.
+ * @param color The new color of the location in HEX format.
+ * @param description An optional new description for the location.
  */
 data class LocationUpdate(
     val name: String?,

domain/src/main/java/com/homebox/lens/domain/model/MaintenanceEntry.kt

@@ -1,19 +1,22 @@
 // [PACKAGE] com.homebox.lens.domain.model
 // [FILE] MaintenanceEntry.kt
-// [SEMANTICS] data_structure, entity, maintenance
+// [SEMANTICS] domain, model, maintenance
 package com.homebox.lens.domain.model
 
 // [ENTITY: DataClass('MaintenanceEntry')]
 /**
- * @summary Модель данных для записи о техническом обслуживании.
- * @param id Уникальный идентификатор записи.
- * @param itemId ID связанной вещи.
- * @param title Заголовок.
- * @param details Детальное описание.
- * @param dueAt Дата, до которой нужно выполнить.
- * @param completedAt Дата выполнения.
- * @param createdAt Дата и время создания.
- * @param updatedAt Дата и время последнего обновления.
+ * @summary Data model for a maintenance entry.
+ * @param id The unique identifier of the entry.
+ * @param itemId The ID of the associated item.
+ * @param title The title of the maintenance entry.
+ * @param details A detailed description of the maintenance.
+ * @param dueAt The date when the maintenance is due.
+ * @param completedAt The date when the maintenance was completed.
+ * @param createdAt The timestamp when the entry was created.
+ * @param updatedAt The timestamp when the entry was last updated.
+ * @invariant The 'id' must not be blank.
+ * @invariant The 'itemId' must not be blank.
+ * @invariant The 'title' must not be blank.
  */
 data class MaintenanceEntry(
     val id: String,

domain/src/main/java/com/homebox/lens/domain/model/PaginationResult.kt

@@ -1,16 +1,19 @@
 // [PACKAGE] com.homebox.lens.domain.model
 // [FILE] PaginationResult.kt
-// [SEMANTICS] data_structure, generic, pagination
+// [SEMANTICS] domain, model, pagination
 package com.homebox.lens.domain.model
 
 // [ENTITY: DataClass('PaginationResult')]
 /**
- * @summary Генерик-класс для представления постраничных результатов от API.
- * @param T Тип элементов в списке.
- * @param items Список элементов на текущей странице.
- * @param page Номер текущей страницы.
- * @param pageSize Количество элементов на странице.
- * @param total Общее количество элементов.
+ * @summary A generic class for representing paginated results from an API.
+ * @param T The type of items in the list.
+ * @param items The list of items on the current page.
+ * @param page The current page number.
+ * @param pageSize The number of items per page.
+ * @param total The total number of items.
+ * @invariant 'page' must be greater than 0.
+ * @invariant 'pageSize' must be greater than 0.
+ * @invariant 'total' must be non-negative.
  */
 data class PaginationResult<T>(
     val items: List<T>,

domain/src/main/java/com/homebox/lens/domain/model/Statistics.kt

@@ -1,6 +1,6 @@
 // [PACKAGE] com.homebox.lens.domain.model
 // [FILE] Statistics.kt
-// [SEMANTICS] domain, model
+// [SEMANTICS] domain, model, statistics
 package com.homebox.lens.domain.model
 
 // [IMPORTS]
@@ -9,11 +9,14 @@ import java.math.BigDecimal
 
 // [ENTITY: DataClass('Statistics')]
 /**
- * @summary Представляет собой статистику по инвентарю.
- * @param totalValue Общая стоимость всех вещей.
- * @param totalItems Общее количество вещей.
- * @param locations Общее количество местоположений.
- * @param labels Общее количество меток.
+ * @summary Represents inventory statistics.
+ * @param totalValue The total value of all items.
+ * @param totalItems The total number of items.
+ * @param locations The total number of locations.
+ * @param labels The total number of labels.
+ * @invariant 'totalItems' must be non-negative.
+ * @invariant 'locations' must be non-negative.
+ * @invariant 'labels' must be non-negative.
  */
 data class Statistics(
     val totalValue: BigDecimal,

domain/src/main/java/com/homebox/lens/domain/model/TokenResponse.kt

@@ -1,14 +1,14 @@
 // [PACKAGE] com.homebox.lens.domain.model
 // [FILE] TokenResponse.kt
-// [SEMANTICS] data_transfer_object, authentication, model
+// [SEMANTICS] domain, model, authentication
 
 package com.homebox.lens.domain.model
 
 // [ENTITY: DataClass('TokenResponse')]
 /**
- * @summary Модель данных, представляющая ответ от сервера с токеном аутентификации.
- * @param token Строка, содержащая JWT или другой токен доступа.
- * @invariant `token` не должен быть пустым.
+ * @summary Data model representing a response from the server with an authentication token.
+ * @param token A string containing a JWT or other access token.
+ * @invariant `token` must not be blank.
  */
 data class TokenResponse(val token: String) {
     init {

domain/src/main/java/com/homebox/lens/domain/repository/AuthRepository.kt

@@ -1,6 +1,6 @@
 // [PACKAGE] com.homebox.lens.domain.repository
 // [FILE] AuthRepository.kt
-// [SEMANTICS] authentication, data_access, repository
+// [SEMANTICS] domain, repository, authentication
 
 package com.homebox.lens.domain.repository
 
@@ -17,27 +17,27 @@ import kotlinx.coroutines.flow.Flow
 interface AuthRepository {
     // [ENTITY: Function('login')]
     /**
-     * @summary Выполняет вход в систему, используя предоставленные учетные данные.
-     * @param credentials Учетные данные пользователя (URL сервера, логин, пароль).
-     * @return [Result] с [TokenResponse] в случае успеха, или с [Exception] в случае ошибки.
-     * @throws IllegalArgumentException если `credentials` невалидны (предусловие).
+     * @summary Performs a login using the provided credentials.
+     * @param credentials The user's credentials (server URL, username, password).
+     * @return A [Result] with a [TokenResponse] on success, or an [Exception] on failure.
+     * @throws IllegalArgumentException if `credentials` are invalid (precondition).
      */
-    suspend fun login(credentials: Credentials): Result<TokenResponse>
+    suspend fun login(credentials: Credentials): com.homebox.lens.domain.model.Result<TokenResponse>
     // [END_ENTITY: Function('login')]
 
     // [ENTITY: Function('saveToken')]
     /**
-     * @summary Сохраняет токен аутентификации.
-     * @param token Токен для сохранения.
-     * @throws IllegalArgumentException если `token` пустой (предусловие).
+     * @summary Saves the authentication token.
+     * @param token The token to save.
+     * @throws IllegalArgumentException if `token` is blank (precondition).
      */
     suspend fun saveToken(token: String)
     // [END_ENTITY: Function('saveToken')]
 
     // [ENTITY: Function('getToken')]
     /**
-     * @summary Получает токен аутентификации.
-     * @return [Flow], который эммитит токен в виде строки, или `null`, если токен отсутствует.
+     * @summary Gets the authentication token.
+     * @return A [Flow] that emits the token as a string, or `null` if the token is not present.
      */
     fun getToken(): Flow<String?>
     // [END_ENTITY: Function('getToken')]

domain/src/main/java/com/homebox/lens/domain/repository/ItemRepository.kt

@@ -1,6 +1,6 @@
 // [PACKAGE] com.homebox.lens.domain.repository
 // [FILE] ItemRepository.kt
-// [SEMANTICS] data_access, abstraction, repository
+// [SEMANTICS] domain, repository, item
 package com.homebox.lens.domain.repository
 
 // [IMPORTS]

domain/src/main/java/com/homebox/lens/domain/usecase/CreateItemUseCase.kt

@@ -1,6 +1,6 @@
 // [PACKAGE] com.homebox.lens.domain.usecase
 // [FILE] CreateItemUseCase.kt
-// [SEMANTICS] business_logic, use_case, item_creation
+// [SEMANTICS] domain, usecase, item, create
 
 package com.homebox.lens.domain.usecase
 
@@ -14,18 +14,18 @@ import javax.inject.Inject
 // [ENTITY: UseCase('CreateItemUseCase')]
 // [RELATION: UseCase('CreateItemUseCase')] -> [DEPENDS_ON] -> [Interface('ItemRepository')]
 /**
- * @summary Use case для создания новой вещи.
- * @param itemRepository Репозиторий для работы с данными о вещах.
+ * @summary Use case for creating a new item.
+ * @param itemRepository The repository for working with item data.
  */
 class CreateItemUseCase @Inject constructor(
     private val itemRepository: ItemRepository
 ) {
     // [ENTITY: Function('invoke')]
     /**
-     * @summary Выполняет операцию создания вещи.
-     * @param itemCreate Данные для создания новой вещи.
-     * @return Возвращает сокращенную модель созданной вещи.
-     * @throws IllegalArgumentException если название вещи пустое.
+     * @summary Executes the item creation operation.
+     * @param itemCreate The data for creating the new item.
+     * @return A summary of the created item.
+     * @throws IllegalArgumentException if the item name is blank.
      */
     suspend operator fun invoke(itemCreate: ItemCreate): ItemSummary {
         require(itemCreate.name.isNotBlank()) { "Item name cannot be blank." }

domain/src/main/java/com/homebox/lens/domain/usecase/CreateLabelUseCase.kt

@@ -1,6 +1,6 @@
 // [PACKAGE] com.homebox.lens.domain.usecase
 // [FILE] CreateLabelUseCase.kt
-// [SEMANTICS] business_logic, use_case, label, create
+// [SEMANTICS] domain, usecase, label, create
 package com.homebox.lens.domain.usecase
 
 // [IMPORTS]
@@ -13,19 +13,19 @@ import javax.inject.Inject
 // [ENTITY: UseCase('CreateLabelUseCase')]
 // [RELATION: UseCase('CreateLabelUseCase')] -> [DEPENDS_ON] -> [Interface('ItemRepository')]
 /**
- * @summary Сценарий использования для создания новой метки.
- * @param repository Репозиторий для доступа к данным.
+ * @summary Use case for creating a new label.
+ * @param repository The repository for data access.
  */
 class CreateLabelUseCase @Inject constructor(
     private val repository: ItemRepository
 ) {
     // [ENTITY: Function('invoke')]
     /**
-     * @summary Выполняет создание метки.
-     * @param newLabelData Данные для создания новой метки.
-     * @return Возвращает краткую информацию о созданной метке [LabelSummary].
-     * @throws Exception в случае ошибки на уровне репозитория (сеть, API).
-     * @precondition `newLabelData.name` не должен быть пустым.
+     * @summary Executes the label creation.
+     * @param newLabelData The data for creating the new label.
+     * @return A summary of the created label [LabelSummary].
+     * @throws Exception in case of a repository-level error (network, API).
+     * @precondition `newLabelData.name` must not be blank.
      */
     suspend operator fun invoke(newLabelData: LabelCreate): LabelSummary {
         require(newLabelData.name.isNotBlank()) { "Label name cannot be blank." }

domain/src/main/java/com/homebox/lens/domain/usecase/CreateLocationUseCase.kt

@@ -1,6 +1,6 @@
 // [PACKAGE] com.homebox.lens.domain.usecase
 // [FILE] CreateLocationUseCase.kt
-// [SEMANTICS] business_logic, use_case, location, create
+// [SEMANTICS] domain, usecase, location, create
 package com.homebox.lens.domain.usecase
 
 // [IMPORTS]
@@ -13,19 +13,19 @@ import javax.inject.Inject
 // [ENTITY: UseCase('CreateLocationUseCase')]
 // [RELATION: UseCase('CreateLocationUseCase')] -> [DEPENDS_ON] -> [Interface('ItemRepository')]
 /**
- * @summary Сценарий использования для создания нового местоположения.
- * @param repository Репозиторий для доступа к данным.
+ * @summary Use case for creating a new location.
+ * @param repository The repository for data access.
  */
 class CreateLocationUseCase @Inject constructor(
     private val repository: ItemRepository
 ) {
     // [ENTITY: Function('invoke')]
     /**
-     * @summary Выполняет создание местоположения.
-     * @param newLocationData Данные для создания нового местоположения.
-     * @return Возвращает информацию о созданом местоположении [LocationOut].
-     * @throws Exception в случае ошибки на уровне репозитория (сеть, API).
-     * @precondition `newLocationData.name` не должен быть пустым.
+     * @summary Executes the location creation.
+     * @param newLocationData The data for creating the new location.
+     * @return Information about the created location [LocationOut].
+     * @throws Exception in case of a repository-level error (network, API).
+     * @precondition `newLocationData.name` must not be blank.
      */
     suspend operator fun invoke(newLocationData: LocationCreate): LocationOut {
         require(newLocationData.name.isNotBlank()) { "Location name cannot be blank." }

domain/src/main/java/com/homebox/lens/domain/usecase/DeleteItemUseCase.kt

@@ -1,6 +1,6 @@
 // [PACKAGE] com.homebox.lens.domain.usecase
 // [FILE] DeleteItemUseCase.kt
-// [SEMANTICS] business_logic, use_case, item_deletion
+// [SEMANTICS] domain, usecase, item, delete
 
 package com.homebox.lens.domain.usecase
 
@@ -12,17 +12,17 @@ import javax.inject.Inject
 // [ENTITY: UseCase('DeleteItemUseCase')]
 // [RELATION: UseCase('DeleteItemUseCase')] -> [DEPENDS_ON] -> [Interface('ItemRepository')]
 /**
- * @summary Use case для удаления вещи.
- * @param itemRepository Репозиторий для работы с данными о вещах.
+ * @summary Use case for deleting an item.
+ * @param itemRepository The repository for working with item data.
  */
 class DeleteItemUseCase @Inject constructor(
     private val itemRepository: ItemRepository
 ) {
     // [ENTITY: Function('invoke')]
     /**
-     * @summary Выполняет операцию удаления вещи.
-     * @param itemId ID удаляемой вещи.
-     * @throws IllegalArgumentException если ID вещи пустое.
+     * @summary Executes the item deletion operation.
+     * @param itemId The ID of the item to be deleted.
+     * @throws IllegalArgumentException if the item ID is blank.
      */
     suspend operator fun invoke(itemId: String) {
         require(itemId.isNotBlank()) { "Item ID cannot be blank." }

domain/src/main/java/com/homebox/lens/domain/usecase/DeleteLabelUseCase.kt

@@ -1,6 +1,6 @@
 // [PACKAGE] com.homebox.lens.domain.usecase
 // [FILE] DeleteLabelUseCase.kt
-// [SEMANTICS] business_logic, use_case, label, delete
+// [SEMANTICS] domain, usecase, label, delete
 package com.homebox.lens.domain.usecase
 
 // [IMPORTS]
@@ -11,17 +11,17 @@ import javax.inject.Inject
 // [ENTITY: UseCase('DeleteLabelUseCase')]
 // [RELATION: UseCase('DeleteLabelUseCase')] -> [DEPENDS_ON] -> [Interface('ItemRepository')]
 /**
- * @summary Сценарий использования для удаления метки.
- * @param repository Репозиторий для доступа к данным.
+ * @summary Use case for deleting a label.
+ * @param repository The repository for data access.
  */
 class DeleteLabelUseCase @Inject constructor(
     private val repository: ItemRepository
 ) {
     // [ENTITY: Function('invoke')]
     /**
-     * @summary Выполняет удаление метки.
-     * @param labelId ID метки для удаления.
-     * @throws Exception в случае ошибки на уровне репозитория (сеть, API).
+     * @summary Executes the label deletion.
+     * @param labelId The ID of the label to delete.
+     * @throws Exception in case of a repository-level error (network, API).
      */
     suspend operator fun invoke(labelId: String) {
         repository.deleteLabel(labelId)

domain/src/main/java/com/homebox/lens/domain/usecase/DeleteLocationUseCase.kt

@@ -1,6 +1,6 @@
 // [PACKAGE] com.homebox.lens.domain.usecase
 // [FILE] DeleteLocationUseCase.kt
-// [SEMANTICS] business_logic, use_case, location, delete
+// [SEMANTICS] domain, usecase, location, delete
 package com.homebox.lens.domain.usecase
 
 // [IMPORTS]
@@ -11,17 +11,17 @@ import javax.inject.Inject
 // [ENTITY: UseCase('DeleteLocationUseCase')]
 // [RELATION: UseCase('DeleteLocationUseCase')] -> [DEPENDS_ON] -> [Interface('ItemRepository')]
 /**
- * @summary Сценарий использования для удаления местоположения.
- * @param repository Репозиторий для доступа к данным.
+ * @summary Use case for deleting a location.
+ * @param repository The repository for data access.
  */
 class DeleteLocationUseCase @Inject constructor(
     private val repository: ItemRepository
 ) {
     // [ENTITY: Function('invoke')]
     /**
-     * @summary Выполняет удаление местоположения.
-     * @param locationId ID местоположения для удаления.
-     * @throws Exception в случае ошибки на уровне репозитория (сеть, API).
+     * @summary Executes the location deletion.
+     * @param locationId The ID of the location to delete.
+     * @throws Exception in case of a repository-level error (network, API).
      */
     suspend operator fun invoke(locationId: String) {
         repository.deleteLocation(locationId)

domain/src/main/java/com/homebox/lens/domain/usecase/GetAllLabelsUseCase.kt

@@ -1,6 +1,6 @@
 // [PACKAGE] com.homebox.lens.domain.usecase
 // [FILE] GetAllLabelsUseCase.kt
-// [SEMANTICS] domain, usecase
+// [SEMANTICS] domain, usecase, label, list
 package com.homebox.lens.domain.usecase
 
 // [IMPORTS]
@@ -10,16 +10,16 @@ import javax.inject.Inject
 // [END_IMPORTS]
 
 // [ENTITY: UseCase('GetAllLabelsUseCase')]
-// [RELATION: UseCase('GetAllLabelsUseCase')] -> [DEPENDS_ON] -> [Repository('ItemRepository')]
+// [RELATION: UseCase('GetAllLabelsUseCase')] -> [DEPENDS_ON] -> [Interface('ItemRepository')]
 class GetAllLabelsUseCase @Inject constructor(private val repository: ItemRepository) {
 
     // [ENTITY: Function('invoke')]
     // [RELATION: Function('invoke')] -> [RETURNS] -> [DataStructure('List<LabelOut>')]
     /**
-     * @summary Получает список всех меток.
-     * @return Список [LabelOut].
-     * @throws Exception в случае ошибки сети или API.
-     * @sideeffect Отсутствуют.
+     * @summary Gets a list of all labels.
+     * @return A list of [LabelOut].
+     * @throws Exception in case of a network or API error.
+     * @sideeffect None.
      */
     suspend operator fun invoke(): List<LabelOut> {
         // [AI_NOTE]: Упрощено.

domain/src/main/java/com/homebox/lens/domain/usecase/GetAllLocationsUseCase.kt

@@ -1,6 +1,6 @@
 // [PACKAGE] com.homebox.lens.domain.usecase
 // [FILE] GetAllLocationsUseCase.kt
-// [SEMANTICS] domain, usecase
+// [SEMANTICS] domain, usecase, location, list
 package com.homebox.lens.domain.usecase
 
 // [IMPORTS]
@@ -10,16 +10,16 @@ import javax.inject.Inject
 // [END_IMPORTS]
 
 // [ENTITY: UseCase('GetAllLocationsUseCase')]
-// [RELATION: UseCase('GetAllLocationsUseCase')] -> [DEPENDS_ON] -> [Repository('ItemRepository')]
+// [RELATION: UseCase('GetAllLocationsUseCase')] -> [DEPENDS_ON] -> [Interface('ItemRepository')]
 class GetAllLocationsUseCase @Inject constructor(private val repository: ItemRepository) {
 
     // [ENTITY: Function('invoke')]
     // [RELATION: Function('invoke')] -> [RETURNS] -> [DataStructure('List<LocationOutCount>')]
     /**
-     * @summary Получает список всех локаций.
-     * @return Список [LocationOutCount].
-     * @throws Exception в случае ошибки сети или API.
-     * @sideeffect Отсутствуют.
+     * @summary Gets a list of all locations.
+     * @return A list of [LocationOutCount].
+     * @throws Exception in case of a network or API error.
+     * @sideeffect None.
      */
     suspend operator fun invoke(): List<LocationOutCount> {
         // [AI_NOTE]: Упрощено.

domain/src/main/java/com/homebox/lens/domain/usecase/GetItemDetailsUseCase.kt

@@ -1,6 +1,6 @@
 // [PACKAGE] com.homebox.lens.domain.usecase
 // [FILE] GetItemDetailsUseCase.kt
-// [SEMANTICS] business_logic, use_case, item_retrieval
+// [SEMANTICS] domain, usecase, item, details
 
 package com.homebox.lens.domain.usecase
 
@@ -13,18 +13,18 @@ import javax.inject.Inject
 // [ENTITY: UseCase('GetItemDetailsUseCase')]
 // [RELATION: UseCase('GetItemDetailsUseCase')] -> [DEPENDS_ON] -> [Interface('ItemRepository')]
 /**
- * @summary Use case для получения детальной информации о вещи.
- * @param itemRepository Репозиторий для работы с данными о вещах.
+ * @summary Use case for getting detailed information about an item.
+ * @param itemRepository The repository for working with item data.
  */
 class GetItemDetailsUseCase @Inject constructor(
     private val itemRepository: ItemRepository
 ) {
     // [ENTITY: Function('invoke')]
     /**
-     * @summary Выполняет операцию получения детальной информации о вещи.
-     * @param itemId ID запрашиваемой вещи.
-     * @return Возвращает полную модель вещи.
-     * @throws IllegalArgumentException если ID вещи пустое.
+     * @summary Executes the operation to get detailed information about an item.
+     * @param itemId The ID of the requested item.
+     * @return The full model of the item.
+     * @throws IllegalArgumentException if the item ID is blank.
      */
     suspend operator fun invoke(itemId: String): ItemOut {
         require(itemId.isNotBlank()) { "Item ID cannot be blank." }

domain/src/main/java/com/homebox/lens/domain/usecase/GetLabelDetailsUseCase.kt

@@ -1,6 +1,6 @@
 // [PACKAGE] com.homebox.lens.domain.usecase
 // [FILE] GetLabelDetailsUseCase.kt
-// [SEMANTICS] business_logic, use_case, label, get
+// [SEMANTICS] domain, usecase, label, details
 package com.homebox.lens.domain.usecase
 
 // [IMPORTS]
@@ -12,19 +12,19 @@ import javax.inject.Inject
 // [ENTITY: UseCase('GetLabelDetailsUseCase')]
 // [RELATION: UseCase('GetLabelDetailsUseCase')] -> [DEPENDS_ON] -> [Interface('ItemRepository')]
 /**
- * @summary Сценарий использования для получения деталей метки.
- * @param repository Репозиторий для доступа к данным.
+ * @summary Use case for getting the details of a label.
+ * @param repository The repository for data access.
  */
 class GetLabelDetailsUseCase @Inject constructor(
     private val repository: ItemRepository
 ) {
     // [ENTITY: Function('invoke')]
     /**
-     * @summary Выполняет получение деталей метки.
-     * @param labelId ID метки для получения деталей.
-     * @return Возвращает полную информацию о метке [LabelOut].
-     * @throws Exception в случае ошибки на уровне репозитория (сеть, API).
-     * @precondition `labelId` не должен быть пустым.
+     * @summary Executes the retrieval of label details.
+     * @param labelId The ID of the label to get details for.
+     * @return The full information about the label [LabelOut].
+     * @throws Exception in case of a repository-level error (network, API).
+     * @precondition `labelId` must not be blank.
      */
     suspend operator fun invoke(labelId: String): LabelOut {
         require(labelId.isNotBlank()) { "Label ID cannot be blank." }

domain/src/main/java/com/homebox/lens/domain/usecase/GetRecentlyAddedItemsUseCase.kt

@@ -1,6 +1,6 @@
 // [PACKAGE] com.homebox.lens.domain.usecase
 // [FILE] GetRecentlyAddedItemsUseCase.kt
-// [SEMANTICS] domain, usecase
+// [SEMANTICS] domain, usecase, item, list
 package com.homebox.lens.domain.usecase
 
 // [IMPORTS]
@@ -11,10 +11,10 @@ import javax.inject.Inject
 // [END_IMPORTS]
 
 // [ENTITY: UseCase('GetRecentlyAddedItemsUseCase')]
-// [RELATION: UseCase('GetRecentlyAddedItemsUseCase')] -> [DEPENDS_ON] -> [Repository('ItemRepository')]
+// [RELATION: UseCase('GetRecentlyAddedItemsUseCase')] -> [DEPENDS_ON] -> [Interface('ItemRepository')]
 /**
- * @summary Сценарий использования для получения списка недавно добавленных товаров.
- * @param itemRepository Репозиторий для доступа к данным о товарах.
+ * @summary Use case for getting a list of recently added items.
+ * @param itemRepository The repository for accessing item data.
  */
 class GetRecentlyAddedItemsUseCase @Inject constructor(
     private val itemRepository: ItemRepository
@@ -22,12 +22,12 @@ class GetRecentlyAddedItemsUseCase @Inject constructor(
     // [ENTITY: Function('invoke')]
     // [RELATION: Function('invoke')] -> [RETURNS] -> [DataStructure('Flow<List<ItemSummary>>')]
     /**
-     * @summary Возвращает поток (Flow) со списком недавно добавленных товаров.
-     * @param limit Количество запрашиваемых элементов.
-     * @return Поток (Flow), содержащий список [ItemSummary].
-     * @precondition Количество запрашиваемых элементов (limit) должно быть положительным.
-     * @postcondition Возвращает Flow со списком товаров, отсортированных по дате создания в порядке убывания. Если товаров нет, возвращает пустой список.
-     * @sideeffect Отсутствуют.
+     * @summary Returns a Flow with a list of recently added items.
+     * @param limit The number of items to retrieve.
+     * @return A Flow containing a list of [ItemSummary].
+     * @precondition The number of requested items (limit) must be positive.
+     * @postcondition Returns a Flow with a list of items sorted by creation date in descending order. If there are no items, it returns an empty list.
+     * @sideeffect None.
      */
     operator fun invoke(limit: Int): Flow<List<ItemSummary>> {
         require(limit > 0) { "Limit must be positive." }

domain/src/main/java/com/homebox/lens/domain/usecase/GetStatisticsUseCase.kt

@@ -1,6 +1,6 @@
 // [PACKAGE] com.homebox.lens.domain.usecase
 // [FILE] GetStatisticsUseCase.kt
-// [SEMANTICS] domain, usecase
+// [SEMANTICS] domain, usecase, statistics
 package com.homebox.lens.domain.usecase
 
 // [IMPORTS]
@@ -10,16 +10,16 @@ import javax.inject.Inject
 // [END_IMPORTS]
 
 // [ENTITY: UseCase('GetStatisticsUseCase')]
-// [RELATION: UseCase('GetStatisticsUseCase')] -> [DEPENDS_ON] -> [Repository('ItemRepository')]
+// [RELATION: UseCase('GetStatisticsUseCase')] -> [DEPENDS_ON] -> [Interface('ItemRepository')]
 class GetStatisticsUseCase @Inject constructor(private val repository: ItemRepository) {
 
     // [ENTITY: Function('invoke')]
     // [RELATION: Function('invoke')] -> [RETURNS] -> [DataClass('GroupStatistics')]
     /**
-     * @summary Получает статистику инвентаря.
-     * @return [GroupStatistics] объект.
-     * @throws Exception в случае ошибки сети или API.
-     * @sideeffect Отсутствуют.
+     * @summary Gets inventory statistics.
+     * @return A [GroupStatistics] object.
+     * @throws Exception in case of a network or API error.
+     * @sideeffect None.
      */
     suspend operator fun invoke(): GroupStatistics {
         // [AI_NOTE]: Упрощено. Просто вызываем репозиторий и возвращаем его результат. Обработка ошибок делегирована вызывающей стороне (ViewModel).

domain/src/main/java/com/homebox/lens/domain/usecase/LoginUseCase.kt

@@ -13,33 +13,33 @@ import javax.inject.Inject
 // [ENTITY: UseCase('LoginUseCase')]
 // [RELATION: UseCase('LoginUseCase')] -> [DEPENDS_ON] -> [Interface('AuthRepository')]
 /**
- * @summary Use case для выполнения входа пользователя.
- * @param authRepository Репозиторий для выполнения сетевого запроса на вход и сохранения токена.
+ * @summary Use case for user login.
+ * @param authRepository The repository for handling the login network request and saving the token.
  */
 class LoginUseCase @Inject constructor(
     private val authRepository: AuthRepository
 ) {
     // [ENTITY: Function('invoke')]
     /**
-     * @summary Выполняет процесс входа в систему.
-     * @param credentials Учетные данные пользователя.
-     * @return [Result] с [Unit] в случае успеха или с [Exception] в случае ошибки.
-     * @sideeffect В случае успеха, сохраняет токен авторизации через `authRepository`.
+     * @summary Executes the login process.
+     * @param credentials The user's credentials.
+     * @return A [Result] with [Unit] on success or an [Exception] on failure.
+     * @sideeffect On success, saves the authorization token via `authRepository`.
      */
     suspend operator fun invoke(credentials: Credentials): Result<Unit> {
         require(credentials.serverUrl.isNotBlank() && credentials.username.isNotBlank()) {
             "Server URL and username must not be blank."
         }
 
-        val loginResult: Result<TokenResponse> = authRepository.login(credentials)
+        val loginResult: com.homebox.lens.domain.model.Result<TokenResponse> = authRepository.login(credentials)
 
         return loginResult.fold(
             onSuccess = {
                 authRepository.saveToken(it.token)
-                Result.success(Unit)
+                com.homebox.lens.domain.model.Result.Success(Unit)
             },
             onFailure = {
-                Result.failure(it)
+                com.homebox.lens.domain.model.Result.Error(it as Exception)
             }
         )
     }

domain/src/main/java/com/homebox/lens/domain/usecase/SearchItemsUseCase.kt

@@ -1,6 +1,6 @@
 // [PACKAGE] com.homebox.lens.domain.usecase
 // [FILE] SearchItemsUseCase.kt
-// [SEMANTICS] business_logic, use_case, search
+// [SEMANTICS] domain, usecase, item, search
 
 package com.homebox.lens.domain.usecase
 
@@ -14,17 +14,17 @@ import javax.inject.Inject
 // [ENTITY: UseCase('SearchItemsUseCase')]
 // [RELATION: UseCase('SearchItemsUseCase')] -> [DEPENDS_ON] -> [Interface('ItemRepository')]
 /**
- * @summary Use case для поиска вещей по текстовому запросу.
- * @param itemRepository Репозиторий для работы с данными.
+ * @summary Use case for searching items by a text query.
+ * @param itemRepository The repository for data operations.
  */
 class SearchItemsUseCase @Inject constructor(
     private val itemRepository: ItemRepository
 ) {
     // [ENTITY: Function('invoke')]
     /**
-     * @summary Выполняет операцию поиска.
-     * @param query Поисковый запрос.
-     * @return Возвращает объект с результатами пагинации.
+     * @summary Executes the search operation.
+     * @param query The search query.
+     * @return A pagination result object.
      */
     suspend operator fun invoke(query: String): PaginationResult<ItemSummary> {
         return itemRepository.searchItems(query)

domain/src/main/java/com/homebox/lens/domain/usecase/SyncInventoryUseCase.kt

@@ -1,6 +1,6 @@
 // [PACKAGE] com.homebox.lens.domain.usecase
 // [FILE] SyncInventoryUseCase.kt
-// [SEMANTICS] business_logic, use_case, data_sync
+// [SEMANTICS] domain, usecase, item, sync
 
 package com.homebox.lens.domain.usecase
 
@@ -14,19 +14,19 @@ import javax.inject.Inject
 // [ENTITY: UseCase('SyncInventoryUseCase')]
 // [RELATION: UseCase('SyncInventoryUseCase')] -> [DEPENDS_ON] -> [Interface('ItemRepository')]
 /**
- * @summary Use case для синхронизации (получения) списка вещей.
- * @param itemRepository Репозиторий для работы с данными о вещах.
+ * @summary Use case for synchronizing (fetching) the list of items.
+ * @param itemRepository The repository for item data operations.
  */
 class SyncInventoryUseCase @Inject constructor(
     private val itemRepository: ItemRepository
 ) {
     // [ENTITY: Function('invoke')]
     /**
-     * @summary Выполняет операцию получения страницы со списком вещей.
-     * @param page Номер страницы.
-     * @param pageSize Размер страницы.
-     * @return Возвращает объект с результатами пагинации.
-     * @throws IllegalArgumentException если параметры пагинации некорректны.
+     * @summary Executes the operation to get a page from the item list.
+     * @param page The page number.
+     * @param pageSize The page size.
+     * @return A pagination result object.
+     * @throws IllegalArgumentException if the pagination parameters are incorrect.
      */
     suspend operator fun invoke(page: Int, pageSize: Int): PaginationResult<ItemSummary> {
         require(page > 0 && pageSize > 0) { "Page and pageSize must be positive." }

domain/src/main/java/com/homebox/lens/domain/usecase/UpdateItemUseCase.kt

@@ -1,6 +1,6 @@
 // [PACKAGE] com.homebox.lens.domain.usecase
 // [FILE] UpdateItemUseCase.kt
-// [SEMANTICS] business_logic, use_case, item_management
+// [SEMANTICS] domain, usecase, item, update
 
 package com.homebox.lens.domain.usecase
 
@@ -16,18 +16,18 @@ import javax.inject.Inject
 // [RELATION: UseCase('UpdateItemUseCase')] -> [DEPENDS_ON] -> [Interface('ItemRepository')]
 // [RELATION: UseCase('UpdateItemUseCase')] -> [CALLS] -> [Function('ItemRepository.updateItem')]
 /**
- * @summary Use case для обновления существующей вещи.
- * @param itemRepository Репозиторий для работы с данными о вещах.
+ * @summary Use case for updating an existing item.
+ * @param itemRepository The repository for working with item data.
  */
 class UpdateItemUseCase @Inject constructor(
     private val itemRepository: ItemRepository
 ) {
     // [ENTITY: Function('invoke')]
     /**
-     * @summary Выполняет операцию обновления вещи.
-     * @param item Данные для обновления существующей вещи.
-     * @return Возвращает обновленную модель вещи.
-     * @throws IllegalArgumentException если название вещи пустое.
+     * @summary Executes the item update operation.
+     * @param item The data for updating the existing item.
+     * @return The updated item model.
+     * @throws IllegalArgumentException if the item name is blank.
      */
     suspend operator fun invoke(item: Item): ItemOut {
         require(item.name.isNotBlank()) { "Item name cannot be blank." }

domain/src/main/java/com/homebox/lens/domain/usecase/UpdateLabelUseCase.kt

@@ -1,6 +1,6 @@
 // [PACKAGE] com.homebox.lens.domain.usecase
 // [FILE] UpdateLabelUseCase.kt
-// [SEMANTICS] business_logic, use_case, label, update
+// [SEMANTICS] domain, usecase, label, update
 package com.homebox.lens.domain.usecase
 
 // [IMPORTS]
@@ -13,19 +13,19 @@ import javax.inject.Inject
 // [ENTITY: UseCase('UpdateLabelUseCase')]
 // [RELATION: UseCase('UpdateLabelUseCase')] -> [DEPENDS_ON] -> [Interface('ItemRepository')]
 /**
- * @summary Сценарий использования для обновления метки.
- * @param repository Репозиторий для доступа к данным.
+ * @summary Use case for updating a label.
+ * @param repository The repository for data access.
  */
 class UpdateLabelUseCase @Inject constructor(
     private val repository: ItemRepository
 ) {
     // [ENTITY: Function('invoke')]
     /**
-     * @summary Выполняет обновление метки.
-     * @param labelId ID метки для обновления.
-     * @param labelData Данные для обновления метки.
-     * @return Возвращает информацию об обновленной метке [LabelOut].
-     * @throws Exception в случае ошибки на уровне репозитория (сеть, API).
+     * @summary Executes the label update.
+     * @param labelId The ID of the label to update.
+     * @param labelData The data for updating the label.
+     * @return Information about the updated label [LabelOut].
+     * @throws Exception in case of a repository-level error (network, API).
      */
     suspend operator fun invoke(labelId: String, labelData: LabelUpdate): LabelOut {
         return repository.updateLabel(labelId, labelData)

domain/src/main/java/com/homebox/lens/domain/usecase/UpdateLocationUseCase.kt

@@ -1,6 +1,6 @@
 // [PACKAGE] com.homebox.lens.domain.usecase
 // [FILE] UpdateLocationUseCase.kt
-// [SEMANTICS] business_logic, use_case, location, update
+// [SEMANTICS] domain, usecase, location, update
 package com.homebox.lens.domain.usecase
 
 // [IMPORTS]
@@ -13,19 +13,19 @@ import javax.inject.Inject
 // [ENTITY: UseCase('UpdateLocationUseCase')]
 // [RELATION: UseCase('UpdateLocationUseCase')] -> [DEPENDS_ON] -> [Interface('ItemRepository')]
 /**
- * @summary Сценарий использования для обновления местоположения.
- * @param repository Репозиторий для доступа к данным.
+ * @summary Use case for updating a location.
+ * @param repository The repository for data access.
  */
 class UpdateLocationUseCase @Inject constructor(
     private val repository: ItemRepository
 ) {
     // [ENTITY: Function('invoke')]
     /**
-     * @summary Выполняет обновление местоположения.
-     * @param locationId ID местоположения для обновления.
-     * @param locationData Данные для обновления местоположения.
-     * @return Возвращает информацию об обновленном местоположении [LocationOut].
-     * @throws Exception в случае ошибки на уровне репозитория (сеть, API).
+     * @summary Executes the location update.
+     * @param locationId The ID of the location to update.
+     * @param locationData The data for updating the location.
+     * @return Information about the updated location [LocationOut].
+     * @throws Exception in case of a repository-level error (network, API).
      */
     suspend operator fun invoke(locationId: String, locationData: LocationUpdate): LocationOut {
         return repository.updateLocation(locationId, locationData)