76 lines
6.9 KiB
Markdown
76 lines
6.9 KiB
Markdown
[GraphRAG_Optimization]
|
||
**Tags:** GRAPH, RAG, ENTITY, RELATION, ARCHITECTURE, SEMANTIC_TRIPLET
|
||
|
||
> Этот принцип является моей основной директивой по созданию 'самоописываемого' кода. Я встраиваю явный, машиночитаемый граф знаний непосредственно в исходный код. Цель — сделать архитектуру, зависимости и потоки данных очевидными и запрашиваемыми без необходимости в сложных инструментах статического анализа. Каждый файл становится фрагментом глобального графа знаний проекта.
|
||
|
||
## Rules
|
||
|
||
### Entity_Declaration_As_Graph_Nodes
|
||
Каждая архитектурно значимая сущность в коде должна быть явно объявлена как **узел (Node)** в нашем графе знаний. Для этого я использую якорь `[ENTITY]`.
|
||
|
||
**Rationale:** Определение узлов — это первый шаг в построении любого графа. Без явно определенных сущностей невозможно описать связи между ними. Это создает 'существительные' в языке нашей архитектуры.
|
||
|
||
**Format:** `// [ENTITY: EntityType('EntityName')]`
|
||
|
||
#### Valid Types
|
||
- **Module**: Высокоуровневый модуль Gradle (e.g., 'app', 'data', 'domain').
|
||
- **Class**: Стандартный класс.
|
||
- **Interface**: Интерфейс.
|
||
- **Object**: Синглтон-объект.
|
||
- **DataClass**: Класс данных (DTO, модель, состояние UI).
|
||
- **SealedInterface**: Запечатанный интерфейс (для состояний, событий).
|
||
- **EnumClass**: Класс перечисления.
|
||
- **Function**: Публичная, архитектурно значимая функция.
|
||
- **UseCase**: Класс, реализующий конкретный сценарий использования.
|
||
- **ViewModel**: ViewModel из архитектуры MVVM.
|
||
- **Repository**: Класс-репозиторий.
|
||
- **DataStructure**: Структура данных, которая не является `DataClass` (e.g., `Pair`, `Map`).
|
||
- **DatabaseTable**: Таблица в базе данных Room.
|
||
- **ApiEndpoint**: Конкретная конечная точка API.
|
||
|
||
**Example:**
|
||
```kotlin
|
||
// [ENTITY: ViewModel('DashboardViewModel')]
|
||
class DashboardViewModel(...) { ... }
|
||
```
|
||
|
||
### Relation_Declaration_As_Graph_Edges
|
||
Все взаимодействия и зависимости между сущностями должны быть явно объявлены как **ребра (Edges)** в нашем графе знаний. Для этого я использую якорь `[RELATION]` в формате семантического триплета.
|
||
|
||
**Rationale:** Ребра — это 'глаголы' в языке нашей архитектуры. Они делают неявные связи (как вызов метода или использование DTO) явными и машиночитаемыми. Это позволяет автоматически строить диаграммы зависимостей, анализировать влияние изменений и находить архитектурные проблемы.
|
||
|
||
**Format:** `// [RELATION: 'SubjectType'('SubjectName')] -> [RELATION_TYPE] -> ['ObjectType'('ObjectName')]`
|
||
|
||
#### Valid Relations
|
||
- **CALLS**: Субъект вызывает функцию/метод объекта.
|
||
- **CREATES_INSTANCE_OF**: Субъект создает экземпляр объекта.
|
||
- **INHERITS_FROM**: Субъект наследуется от объекта (для классов).
|
||
- **IMPLEMENTS**: Субъект реализует объект (для интерфейсов).
|
||
- **READS_FROM**: Субъект читает данные из объекта (e.g., DatabaseTable, Repository).
|
||
- **WRITES_TO**: Субъект записывает данные в объект.
|
||
- **MODIFIES_STATE_OF**: Субъект изменяет внутреннее состояние объекта.
|
||
- **DEPENDS_ON**: Субъект имеет зависимость от объекта (e.g., использует как параметр, DTO, или внедряется через DI). Это наиболее частая связь.
|
||
- **DISPATCHES_EVENT**: Субъект отправляет событие/сообщение определенного типа.
|
||
- **OBSERVES**: Субъект подписывается на обновления от объекта (e.g., Flow, LiveData).
|
||
- **TRIGGERS**: Субъект (обычно UI-событие или компонент) инициирует выполнение объекта (обычно функции ViewModel).
|
||
- **EMITS_STATE**: Субъект (обычно ViewModel или UseCase) является источником/производителем определённого состояния (DataClass).
|
||
- **CONSUMES_STATE**: Субъект (обычно UI-компонент или экран) потребляет/подписывается на определённое состояние (DataClass).
|
||
|
||
**Example:**
|
||
```kotlin
|
||
// Пример для ViewModel, который зависит от UseCase и является источником состояния
|
||
// [ENTITY: ViewModel('DashboardViewModel')]
|
||
// [RELATION: ViewModel('DashboardViewModel')] -> [DEPENDS_ON] -> [UseCase('GetStatisticsUseCase')]
|
||
// [RELATION: ViewModel('DashboardViewModel')] -> [EMITS_STATE] -> [DataClass('DashboardUiState')]
|
||
class DashboardViewModel @Inject constructor(
|
||
private val getStatisticsUseCase: GetStatisticsUseCase
|
||
) : ViewModel() { ... }
|
||
```
|
||
|
||
### MarkupBlockCohesion
|
||
Вся семантическая разметка, относящаяся к одной сущности (`[ENTITY]` и все ее `[RELATION]` триплеты), должна быть сгруппирована в единый, непрерывный блок комментариев.
|
||
|
||
**Rationale:** Это создает атомарный 'блок метаданных' для каждой сущности. Это упрощает парсинг и гарантирует, что весь архитектурный контекст считывается как единое целое, прежде чем AI-инструмент приступит к анализу самого кода.
|
||
|
||
**Placement:** Этот блок всегда размещается непосредственно перед KDoc-блоком сущности или, если KDoc отсутствует, перед самой декларацией сущности.
|
||
[/End GraphRAG_Optimization] |