PRINCIPLES.md

Версия: 1.0.0
Дата: 2025-12-23
Статус: КЛЮЧЕВОЙ ДОКУМЕНТ
Extends: ../theory/MERKABA.md

ОСНОВАНО НА

Этот документ расширяет концепции из:
- theory/MERKABA.md — Геометрическая модель 8 вопросов

Платформа построена на 8 принципах, соответствующих 8 вершинам Меркабы — геометрической модели системного описания.

КОНЦЕПЦИЯ

Платформа — это проект, который создаёт проекты.

Вся иерархия платформы является проектами с точки зрения того, что мы их:
- Проектируем — определяем структуру и связи
- Разрабатываем — пишем код и документацию
- Управляем — отслеживаем статус и задачи
- Используем — собираем из них другие проекты

Платформа строит решения, собирая их из компонентов. Компоненты — тоже проекты. Сама платформа — тоже проект. Это рекурсивная структура:

ПЛАТФОРМА (проект)
    │
    ├── создаёт → КОМПОНЕНТЫ (проекты)
    │                 │
    │                 └── из которых собираются → РЕШЕНИЯ (проекты)
    │                                                 │
    │                                                 └── для → БИЗНЕСОВ (проекты)
    │
    └── сама состоит из → МОДУЛЕЙ (проекты)

Единый подход: Ко всему применяются одни и те же процессы — проектирование, разработка, управление. Разница только в ТИПЕ проекта.

ПРИНЦИПЫ

Согласно theory/MERKABA.md, система описывается через 8 вопросов, образующих геометрическую структуру — два вложенных тетраэдра (Инь и Янь). Платформа следует 8 фундаментальным принципам:

1. ВСЁ — ПРОЕКТ

# Каждая сущность имеет index.yaml
name: smart_images
type: extension          # тип проекта
status: stable           # стадия

Платформа автоматически применяет одни процессы ко всем проектам:
- Структура (CLAUDE.md, index.yaml)
- Управление (TODO, STATUS)
- Версионирование
- Документирование

2. ГРАФ > ДЕРЕВО

Реальность — многомерный граф связей. Файловая система — одномерное дерево.

Решение:
- Физическая структура (папки) = ОДИН срез
- Логическая структура (связи) = в метаданных

# index.yaml хранит граф связей
links:
  uses: [library/connectors/ozon]
  serves: [projects/org/pirotehnika]
  extends: [library/applications/fastapi-admin]

3. КАНОНИЧЕСКОЕ МЕСТО

Каждый тип сущности имеет ОДНО каноническое место хранения.
В других местах — только ссылки.

extensions/cms/cs-cart/smart_images/     ← КАНОНИЧЕСКИ (код здесь)
projects/org/lideravto/site/modules.yaml ← ССЫЛКА (extends: ...)

4. ВЛАДЕНИЕ КАК ФИЗИЧЕСКИЙ СРЕЗ

Физическая структура проектов — по владельцу:

projects/
├── my/     ← Личные проекты
└── org/    ← Организации

Все остальные измерения (тип, статус, связи) — в метаданных.

5. ПЛАТФОРМА / ПРОЕКТЫ

Где	Что	Пример
`library/`	Generic код (переиспользуемый)	smart_images модуль
`projects/`	Configured решения (для бизнеса)	lideravto/site

Проект использует компоненты из library, но не содержит их копии.

6. КОД / ДАННЫЕ / РЕЛИЗЫ

$WORKSPACE/library/    = Исходники    → git
$DATASPACE/releases/   = Сборки       → не git
$DATASPACE/projects/   = Данные       → не git

7. КЛАССЫ АРТЕФАКТОВ

Артефакт	Где	Git?
Исходный код	`$WORKSPACE/`	Да
Сборки для деплоя	`$DATASPACE/releases/`	Нет
Бинарные данные	`$DATASPACE/projects/`	Нет

library/
├── connectors/      ← К внешним API (ozon, telegram)
├── extensions/      ← К чужим платформам
│   ├── cms/         ←   CMS (cs-cart, drupal)
│   └── erp/         ←   ERP (odoo, 1c)
└── applications/    ← Наши приложения

8. LIFECYCLE

_draft/  →  _beta/  →  stable/  →  published
   │           │          │            │
черновик   тест на    готово     в marketplace
          проекте

СТРУКТУРА

$WORKSPACE/
│
├── architect/                 ← Методология (проект)
├── system/                    ← Ядро платформы (проект)
├── infra/                     ← Инфраструктура (проект)
│
├── library/                   ← Библиотека компонентов
│   ├── _draft/                ←   Черновики
│   ├── _beta/                 ←   Бета
│   ├── connectors/            ←   Коннекторы
│   ├── extensions/            ←   Расширения
│   │   ├── cms/{platform}/    ←     CMS модули
│   │   └── erp/{platform}/    ←     ERP модули
│   └── applications/          ←   Приложения
│
└── projects/                  ← Проекты
    ├── my/                    ←   Личные
    └── org/                   ←   Организации
        ├── pirotehnika/       ←     type: business
        └── lideravto/         ←     type: business

$DATASPACE/
├── projects/                  ← Данные проектов
│   └── {project}/
│       ├── inbox/
│       ├── images/
│       └── prices/
│
└── releases/                  ← Сборки для деплоя
    ├── connectors/
    ├── extensions/
    └── applications/

ТИПЫ ПРОЕКТОВ

СВЯЗИ

Тип	Описание	Пример
business	Бизнес-сущность	pirotehnika, lideravto
product	Наш продукт	mcrm, seller1
platform	Инструмент платформы	pro1
solution	Решение для бизнеса	mini-erp
connector	Коннектор к API	ozon-connector
extension	Расширение платформы	cs-cart/smart_images
application	Приложение-шаблон	fastapi-admin
experiment	Эксперимент	new-idea

links:
  uses:       # Что использую
  provides:   # Что предоставляю
  extends:    # От чего наследую
  serves:     # Кому служу
  contains:   # Что содержу
  depends_on: # От чего завишу

ПРИМЕНЕНИЕ

Создание нового проекта

Создание компонента

Использование в проекте

# projects/org/lideravto/site/modules.yaml
modules:
  - name: smart_images
    source: library/extensions/cms/cs-cart/smart_images
    version: 2.1.0
    config: {...}

Принципы платформы