LAYERED_HIERARCHY.md

Стандарт организации документации и кода в иерархии от бизнеса до компонентов.

Решаемая проблема: Путаница между документами текущего уровня и переходами на дочерние уровни.

Решение: Разделение через специальную папку @/ для контента текущего уровня.

ПРИНЦИП

{entity}/
├── {ENTITY}.yaml        ← Мастер-файл уровня
├── @/                   ← Контент ЭТОГО уровня
│   ├── business/
│   ├── specs/
│   └── prompts/
├── src/                 ← Код ЭТОГО уровня (опционально)
└── {children}/          ← Переход на СЛЕДУЮЩИЙ уровень
    └── {child}/

Правило:
- @/ — всё ПРО эту сущность (документы, спеки, промпты)
- src/ — код этой сущности (если генерируется)
- {plural}/ — дочерние сущности (tools/, modules/, components/)

УРОВНИ И СТРУКТУРЫ

ORGANIZATION (уровень 1)

lideravto/
├── ORG.yaml
├── @/
│   ├── business/
│   │   ├── VISION.md
│   │   ├── STRATEGY.md
│   │   └── MARKETS.md
│   ├── operations/
│   │   ├── PROCESSES.md
│   │   └── CUSTOMERS.md
│   └── structure/
│       ├── DEPARTMENTS.md
│       └── ROLES.md
└── domains/             ← → domain
    ├── it/
    ├── sales/
    └── logistics/

Слои в @/: business, operations, structure
Код: нет
Дочерние: domains/

DOMAIN (уровень 2)

it/web/cscart/
├── DOMAIN.yaml
├── @/
│   ├── business/
│   │   └── REQUIREMENTS.md
│   └── architecture/
│       ├── TECH-STACK.md
│       └── INFRASTRUCTURE.md
└── projects/            ← → project
    ├── catalog-system/
    └── crm-integration/

Слои в @/: business, architecture
Код: нет
Дочерние: projects/

PROJECT (уровень 3)

catalog-system/
├── PROJECT.yaml
├── @/
│   ├── business/
│   │   ├── BRIEF.md
│   │   └── VALUE.md
│   ├── project/
│   │   ├── PROJECT.md
│   │   ├── ROADMAP.md
│   │   └── TEAM.md
│   ├── architecture/
│   │   ├── ARCHITECTURE.md
│   │   ├── COMPONENTS.md
│   │   └── DATA-MODEL.md
│   └── blocks/
│       ├── BLOCK-import/
│       └── BLOCK-catalog/
├── src/                 ← Код проекта (опционально)
│   └── lib/
└── tools/               ← → tool
    ├── import-system/
    └── catalog-manager/

Слои в @/: business, project, architecture, blocks
Код: опционально в src/
Дочерние: tools/

TOOL (уровень 4)

import-system/
├── TOOL.yaml
├── @/
│   ├── business/
│   │   └── PURPOSE.md
│   ├── design/
│   │   ├── ARCHITECTURE.md
│   │   ├── API.md
│   │   └── DATA.md
│   ├── blocks/
│   │   ├── BLOCK-parser/
│   │   └── BLOCK-validator/
│   └── specs/
│       ├── SPEC-parser.md
│       └── SPEC-validator.md
├── src/                 ← Общий код tool
│   └── lib/
└── modules/             ← → module
    ├── lider_setup/
    └── lider_import/

Слои в @/: business, design, blocks, specs
Код: в src/ (библиотеки, утилиты)
Дочерние: modules/

MODULE (уровень 5)

lider_setup/
├── MODULE.yaml
├── @/
│   ├── business/
│   │   └── PURPOSE.md
│   ├── design/
│   │   ├── FUNCTIONS.md
│   │   └── DATA.md
│   ├── specs/
│   │   ├── SPEC-features.md
│   │   ├── SPEC-categories.md
│   │   └── API.md
│   └── prompts/         ← ПОЯВЛЯЮТСЯ промпты
│       ├── CODE-PROMPT-install.md
│       ├── CODE-PROMPT-features.md
│       └── TEST-PROMPT.md
├── src/                 ← Код модуля
│   ├── addon.xml
│   ├── func.php
│   └── init.php
└── components/          ← → component
    ├── feature-creator/
    └── category-creator/

Слои в @/: business, design, specs, prompts
Код: в src/ (основной код модуля)
Дочерние: components/

COMPONENT (уровень 6)

feature-creator/
├── COMPONENT.yaml
├── @/
│   ├── spec/
│   │   └── SPEC.md
│   └── prompt/
│       └── CODE-PROMPT.md
└── src/                 ← Код компонента
    ├── FeatureCreator.php
    └── tests/
        └── FeatureCreatorTest.php

Слои в @/: spec, prompt
Код: в src/ (только код компонента)
Дочерние: нет (конечный уровень)

МАТРИЦА СЛОЁВ ПО УРОВНЯМ

Уровень	Тип	Слои в `@/`	Код в `src/`	Дочерние
1	organization	business, operations, structure	❌	domains/
2	domain	business, architecture	❌	projects/
3	project	business, project, architecture, blocks	⚠️	tools/
4	tool	business, design, blocks, specs	✅	modules/
5	module	business, design, specs, prompts	✅	components/
6	component	spec, prompt	✅	❌

Легенда:
- ✅ Обязательно есть код
- ⚠️ Опционально (может быть общий код проекта)
- ❌ Нет кода

МАСТЕР-ФАЙЛЫ

Структура .yaml

entity:
  type: {organization|domain|project|tool|module|component}
  id: {entity-id}
  name: "Название"
  level: {1-6}
  parent: {parent-id}          # Опционально

meta_folder: "@"                # Всегда "@"
code_folder: "src"              # Если есть код

structure:                      # Слои в @/
  business: [список файлов]
  specs: [список файлов]
  prompts: [список файлов]

children:                       # Дочерние сущности
  {type}:
    - {child-id-1}
    - {child-id-2}

Пример: MODULE.yaml

entity:
  type: module
  id: lider_setup
  name: "LiderAvto Setup"
  level: 5
  parent: import-system

meta_folder: "@"
code_folder: "src"

structure:
  business: [PURPOSE.md]
  design: [FUNCTIONS.md, DATA.md]
  specs: [SPEC-features.md, SPEC-categories.md, API.md]
  prompts: [CODE-PROMPT-install.md, CODE-PROMPT-features.md]

code:
  main: [addon.xml, func.php, init.php]

children:
  components:
    - feature-creator
    - category-creator

НАВИГАЦИЯ

Документация текущего уровня

# Бизнес-требования проекта
cat catalog-system/@/business/BRIEF.md

# Спецификация модуля
cat lider_setup/@/specs/SPEC-features.md

# Промпт компонента
cat feature-creator/@/prompt/CODE-PROMPT.md

Код текущего уровня

# Код модуля
ls lider_setup/src/
# addon.xml  func.php  init.php

# Код компонента
ls feature-creator/src/
# FeatureCreator.php  tests/

Переход на следующий уровень

# Инструменты проекта
ls catalog-system/tools/
# import-system/  catalog-manager/

# Модули инструмента
ls import-system/modules/
# lider_setup/  lider_import/

# Компоненты модуля
ls lider_setup/components/
# feature-creator/  category-creator/

ПРАВИЛА ИМЕНОВАНИЯ

Папки

Файлы

ПРЕИМУЩЕСТВА

Назначение	Формат	Пример
Контент уровня	`@/`	Всегда `@/`
Код уровня	`src/`	Всегда `src/`
Дочерние (plural)	`{type}s/`	domains/, projects/, tools/, modules/, components/
Слои в `@/`	`{layer}/`	business/, specs/, prompts/

Тип	Формат	Пример
Мастер-файл	`{TYPE}.yaml`	ORG.yaml, PROJECT.yaml, MODULE.yaml
Документы	`{NAME}.md`	VISION.md, SPEC-features.md
Код	По языку	.php, .py, .js

✅ Нет путаницы: @/ явно отделяет контент от переходов
✅ Единообразие: На всех уровнях одна логика
✅ Навигация: ls сразу показывает что к чему
✅ Git-friendly: Текстовые файлы, понятная структура
✅ Масштабируемость: Легко добавлять новые уровни

МИГРАЦИЯ СУЩЕСТВУЮЩИХ ПРОЕКТОВ

1. Создать структуру

cd {entity}
mkdir -p @/{business,specs,prompts} src

2. Переместить документы

mv business/ @/
mv specs/ @/
mv prompts/ @/

3. Переместить код

mv *.php src/
mv *.py src/

4. Создать мастер-файл

cat > MODULE.yaml << EOF
entity:
  type: module
  id: lider_setup
  ...
EOF

LAYERED HIERARCHY STANDARD

НАЗНАЧЕНИЕ