architect/arh/operations/proposals/PLATFORM_RESTRUCTURE_2025.md

ПРЕДЛОЖЕНИЯ ПО ПЕРЕСТРОЙКЕ ПЛАТФОРМЫ

Дата: 2025-12-22
Статус: DRAFT (обсуждение)
Автор: Совместная разработка

ОБЗОР

Документ содержит предложения по фундаментальной реорганизации структуры платформы на основе:
- Четких вертикальных уровней абстракции (L0→L3)
- Принципа наследования (как в ООП)
- Точной терминологии
- Разделения кода и данных
- Канонических мест размещения сущностей

КРАТКАЯ СВОДКА КЛЮЧЕВЫХ РЕШЕНИЙ

1. Платформенные приложения vs Сервисы бизнеса

КРИТИЧЕСКОЕ ОТКРЫТИЕ:
- PIM не является платформенным сервисом — это сервис конкретной бизнес-единицы
- Нужна папка /PLATFORM/applications/ для переиспользуемых приложений (NocoDB, n8n, Metabase)
- Сервисы бизнеса размещаются в /L0-ORG/business-units/{name}/services/

2. Определение vs Использование

Два уровня абстракции:
- DEFINITION (класс): /PLATFORM/applications/pim/SPECIFICATION.md — что делает сервис
- USAGE (инстанс): /L0-ORG/.../connections/pim.yaml — где и как развернут

3. Терминология БД

Правильные термины (от меньшего к большему):
1. Префикс таблиц (Table Prefix): pim_products — минимальная изоляция
2. Схема (Schema): bu_piro — namespace в базе
3. База данных (Database): pirotehnika_db — catalog
4. Инстанс (Instance): postgres:5432 — процесс СУБД
5. Сервер (Server): postgresql-001 — физический/виртуальный сервер

Для pirotehnika:
- ✅ "У pirotehnika есть своя схема bu_piro в общей БД"
- ❌ "У pirotehnika есть своя база данных"

4. Границы изоляции по уровням

Уровень Минимум По умолчанию Максимум
L0: ORG Shared (prefix) Isolated (schema) Standalone (server)
L1: SERVICE Shared (prefix) Isolated (schema) Dedicated (instance)
L2: DATA Shared (prefix) Isolated (schema) Isolated (schema)
L3: INFRA Shared (process) Dedicated (instance) Standalone (server)

Правила:
- ✅ Можно ПОВЫШАТЬ изоляцию
- ❌ Нельзя ПОНИЖАТЬ для production
- ⚠️ L1-SERVICE максимум Dedicated (НЕ Standalone)

5. Обновленная структура

workspace/
├── PLATFORM/              ← НОВОЕ!
│   ├── applications/      ← NocoDB, n8n, Metabase
│   └── infrastructure/    ← PostgreSQL, Redis, Nginx
│
├── L0-ORG/
│   └── business-units/
│       └── pirotehnika/
│           ├── services/  ← PIM (сервис бизнеса)
│           └── connections/ ← Подключения к платформенным приложениям
│
├── L1-SERVICE/            ← DEPRECATED (переносим)
├── L2-DATA/
└── L3-INFRA/

6. PIM: Правильное размещение

Вариант A (временно): PIM как сервис pirotehnika

/L0-ORG/business-units/pirotehnika/services/pim/
└── uses_platform_apps: [nocodb]

Вариант B (потом): PIM как платформенное приложение

/PLATFORM/applications/pim/
  (когда понадобится в других бизнесах)

7. Работа оператора (уровни)

Оператор (L0-ORG)
  ↓ открывает UI
https://pim.pirotehnika.spb.ru
  ↓ обращается к API
https://pim.pirotehnika.internal/api
  ↓ читает данные через CONNECTION (L2-DATA)
/connections/pim.yaml
  ↓ из таблиц (L3-INFRA)
bu_piro.pim_products
  ↓ по DEFINITION (L1-SERVICE)
/PLATFORM/applications/pim/

1. ПРОБЛЕМЫ ТЕКУЩЕЙ СТРУКТУРЫ

1.1. Смешивание слоёв

projects/pirotehnika/
├── retail/
│   └── @site/
│       ├── solution/         ← КОД
│       └── data/             ← ЧТО ЭТО? Схемы? Коннекторы? Сами данные?

Проблема: Непонятно что в data/ — схемы БД, коннекторы, обработки или сами данные?

1.2. Размытая терминология

❌ "Проект" — что это?
   - Бизнес (pirotehnika)?
   - Система (PIM)?
   - Клиентская работа?
   - PROJECT.md файл?

❌ "Данные" — что это?
   - Файлы?
   - Таблицы в БД?
   - Коннекторы?
   - Схемы?

1.3. Нет четкой иерархии зависимостей

@site зависит от:
├── @pim.service      (функциональная зависимость)
├── pim_db            (данные)
└── @beget.server     (физическое размещение)

Вопрос: Где каноническое место @site?

1.4. Данные в проектах

projects/pirotehnika/data/products.csv    ← Сами данные в репо!

Проблема: Код и данные смешаны, нет разделения.

2. КЛЮЧЕВЫЕ ПРИНЦИПЫ РЕОРГАНИЗАЦИИ

2.1. Вертикальные уровни (L0→L3)

L0: ORG           ← Самый абстрактный (бизнес-сущности)
    ↓ extends
L1: SERVICE       ← Бизнес-логика и интерфейсы
    ↓ extends
L2: DATA          ← Структуры данных, подключения
    ↓ extends
L3: INFRA         ← Физическое железо (самый конкретный)

Правило: Каждый уровень наследует и специализирует предыдущий.

2.2. Принцип наследования (как ООП)

L3: INFRA/database-engines/postgresql-001
    ├─ Базовый драйвер PostgreSQL
    └─ host: localhost, port: 5433
          ↓ extends

L2: DATA/connections/pim-db
    ├─ extends: postgresql-001
    ├─ database: nocodb
    └─ schema: pt7k98pv0fwi1el
          ↓ extends

L1: SERVICE/pim/data-access
    ├─ extends: pim-db connection
    ├─ models: Product, Brand
    └─ queries: get_product()
          ↓ extends

L0: ORG/business-units/pirotehnika/operations/pim
    ├─ extends: SERVICE/pim
    ├─ owner: pirotehnika
    └─ purpose: "Управление товарами"

2.3. Код vs Данные

КОД (в репозитории):
├── Коннекторы (как подключаться)
├── Схемы (структура данных)
├── Обработки (ETL)
└── Интерфейсы (API, UI, CLI)

ДАННЫЕ (ВНЕ репозитория):
├── PostgreSQL (таблицы)
├── S3/Hub (файлы)
├── Filesystem (локальные файлы)
└── Внешние API

Правило: Данные НИКОГДА не лежат в проекте. В проекте только КОД работы с данными.

2.4. Каноническое место

┌────────────────────────────────────────────────────┐
│ Каждая сущность имеет ОДНО каноническое место      │
│                                                    │
│ PostgreSQL инстанс → /L3-INFRA/database-engines/   │
│ PIM Connection     → /L2-DATA/connections/         │
│ PIM Service        → /L1-SERVICE/systems/          │
│ PIM в бизнесе      → /L0-ORG/business-units/.../   │
│                                                    │
│ Все остальные места → ССЫЛКИ (mount/link)          │
└────────────────────────────────────────────────────┘

3. НОВАЯ ТЕРМИНОЛОГИЯ

3.1. Слово "ПРОЕКТ"

ЗАПРЕЩЕНО использовать "проект" без уточнения!

Контекст Было (неточно) Стало (точно)
Бизнес Бизнес-проект Бизнес-единица (Business Unit)
ИТ ИТ-проект ИТ-система (System)
Данные Проект данных Набор данных (Dataset)
Инфраструктура Проект инфры Инфраструктурный ресурс (Resource)
Клиентская работа Проект ПРОЕКТ (единственное использование!)
Методология Проект Архитектор Методология

Правило:

"ПРОЕКТ" (без уточнения) = ТОЛЬКО клиентская работа

Все остальное — точные термины:
✅ Бизнес-единица
✅ ИТ-система
✅ Набор данных
✅ Инфраструктурный ресурс
✅ Методология

3.2. DATA в проекте

Было:

data/ — непонятно что

Стало:

data/
├── connections/    ← Подключения к ресурсам (экземпляры коннекторов)
├── schemas/        ← Описание структур данных
└── processors/     ← Обработки данных (ETL)

НЕТ в data/:
- ❌ Самих данных (таблиц, файлов)
- ❌ Интерфейсов (API, UI)

3.3. SERVICE в проекте

Было:

service/ — всё подряд

Стало:

service/
├── api/            ← REST/GraphQL endpoints (backend)
├── ui/             ← Web/Mobile интерфейсы (frontend)
├── cli/            ← Командная строка
└── workers/        ← Фоновые процессы (с интерфейсом управления)

Правило: SERVICE = всё что имеет интерфейс (API, UI, CLI).

3.4. Коннекторы

Термин Значение Где лежит
Connector Template Шаблон/класс коннектора /GROUP/shared/connectors/
Connection Экземпляр коннектора /L2-DATA/connections/
Adapter Переходник между системами /L1-SERVICE/{system}/adapters/

Пример:

Connector Template:  /GROUP/shared/connectors/postgresql/driver.py
                     ↓ extends
Connection:          /L2-DATA/connections/pim-db/config.yaml
                     ↓ uses
Adapter:             /L1-SERVICE/pim/adapters/db_adapter.py

3.5. Типы связей (по аналогии с Unix)

Термин Значение Аналогия Unix Пример
Resource Физическая/логическая сущность файл, устройство БД, сервер, API
Canonical path Каноническое место /usr/bin/bash /L3-INFRA/compute/server-001
Link Ссылка на ресурс symlink pim → /L1-SERVICE/pim
Mount Монтирование ресурса mount data → /L2-DATA/datasets/pim
Reference Логическая ссылка путь в конфиге depends_on: /L1-SERVICE/analytics
Share Расшаренный ресурс shared folder /GROUP/shared/connectors/

4. НОВАЯ СТРУКТУРА WORKSPACE

4.1. Верхний уровень (4 уровня)

workspace/
│
├── L0-ORG/                     ← Уровень 0: Организация (абстракция)
│   ├── business-units/
│   ├── client-projects/
│   └── methodology/
│
├── L1-SERVICE/                 ← Уровень 1: Сервисы (логика)
│   └── systems/
│
├── L2-DATA/                    ← Уровень 2: Данные (структуры)
│   ├── connections/
│   ├── datasets/
│   └── schemas/
│
├── L3-INFRA/                   ← Уровень 3: Инфраструктура (физика)
│   ├── compute/
│   ├── storage/
│   ├── network/
│   └── database-engines/
│
└── GROUP/                      ← Общие ресурсы группы
    └── shared/
        ├── connectors/         ← Connector Templates
        ├── processors/
        └── templates/

4.2. Детальная структура уровней

L3: INFRA (фундамент)

L3-INFRA/
│
├── compute/                    ← Вычислительные ресурсы
│   ├── servers/
│   │   ├── beget-kondurov/
│   │   │   ├── SPECIFICATION.md
│   │   │   └── config.yaml
│   │   └── dev-pro/
│   ├── vm/
│   └── containers/
│       └── docker/
│
├── network/                    ← Сетевые ресурсы
│   ├── domains/
│   │   └── pirotehnika.spb.ru/
│   ├── routers/
│   └── vpn/
│
├── storage/                    ← Хранилища
│   ├── block/
│   ├── object/
│   │   └── s3/
│   │       └── hub/            ← MinIO instance
│   └── file/
│       └── nfs/
│
└── database-engines/           ← СУБД инстансы
    ├── postgresql-001/
    │   ├── SPECIFICATION.md
    │   ├── config.yaml
    │   └── host: localhost
    │       port: 5433
    ├── mysql-001/
    └── redis-001/

Характеристика L3:
- ✅ Физические ресурсы
- ✅ СУБД инстансы (НЕ данные!)
- ✅ Независим (нижний слой)
- ❌ Не знает о верхних уровнях

L2: DATA (структуры)

L2-DATA/
│
├── connections/                ← Connection экземпляры
│   ├── pim-db/
│   │   ├── config.yaml
│   │   │   connector_template: /GROUP/shared/connectors/postgresql
│   │   │   mount: /L3-INFRA/database-engines/postgresql-001
│   │   │   database: nocodb
│   │   │   schema: pt7k98pv0fwi1el
│   │   └── credentials.enc
│   │
│   ├── hub-s3/
│   │   ├── config.yaml
│   │   │   mount: /L3-INFRA/storage/object/s3/hub
│   │   └── credentials.enc
│   │
│   └── 1c-odata/
│       ├── config.yaml
│       │   url: https://saas.is1c.ru/...
│       └── credentials.enc
│
├── datasets/                   ← Наборы данных (логические)
│   ├── pim/
│   │   ├── SPECIFICATION.md    (5 вопросов)
│   │   ├── schema.sql
│   │   ├── migrations/
│   │   └── connection → /L2-DATA/connections/pim-db
│   │
│   └── customers/
│       └── ...
│
└── schemas/                    ← Схемы данных
    ├── openapi/
    ├── json-schema/
    └── sql/

Характеристика L2:
- ✅ Подключения к L3:INFRA
- ✅ Схемы структур данных
- ✅ Описание наборов данных
- ❌ НЕТ бизнес-логики
- ❌ НЕТ интерфейсов
- ❌ НЕТ самих данных

L1: SERVICE (логика)

L1-SERVICE/
│
└── systems/                    ← ИТ-системы
    ├── pim/
    │   ├── SPECIFICATION.md    (7 вопросов)
    │   ├── ARCHITECTURE.md
    │   │
    │   ├── api/                ← REST API
    │   │   ├── fastapi_app/
    │   │   └── mount: /L2-DATA/datasets/pim
    │   │
    │   ├── ui/                 ← Frontend
    │   │   └── nocodb/
    │   │       └── mount: /L2-DATA/datasets/pim
    │   │
    │   ├── cli/                ← CLI
    │   │   └── commands/
    │   │
    │   ├── processors/         ← ETL обработки
    │   │   ├── import_from_1c.py
    │   │   │   mount: /L2-DATA/connections/1c-odata
    │   │   ├── sync_to_1c.py
    │   │   └── enrich_data.py
    │   │
    │   └── adapters/           ← Адаптеры
    │       ├── db_adapter.py
    │       └── s3_adapter.py
    │
    ├── analytics/
    │   └── ...
    │
    └── email/
        └── api/

Характеристика L1:
- ✅ Бизнес-логика
- ✅ API, UI, CLI (интерфейсы)
- ✅ Обработки данных (ETL)
- ✅ Монтирует L2:DATA
- ❌ НЕТ самих данных

L0: ORG (композиция)

L0-ORG/
│
├── business-units/             ← Бизнес-единицы
│   ├── pirotehnika/
│   │   ├── SPECIFICATION.md    (9 вопросов)
│   │   ├── CLAUDE.md
│   │   ├── index.yaml
│   │   │
│   │   ├── channels/           ← Каналы продаж
│   │   │   ├── retail/
│   │   │   │   └── site/
│   │   │   │       ├── mount: /L1-SERVICE/systems/opencart
│   │   │   │       └── mount: /L2-DATA/datasets/opencart
│   │   │   └── ozon/
│   │   │       ├── mount: /L1-SERVICE/systems/ozon-integration
│   │   │       └── mount: /L2-DATA/connections/ozon-api
│   │   │
│   │   └── operations/
│   │       └── pim/
│   │           ├── mount: /L1-SERVICE/systems/pim
│   │           └── mount: /L2-DATA/datasets/pim
│   │
│   └── lideravto/
│       └── ...
│
├── client-projects/            ← ПРОЕКТЫ (клиентские работы)
│   ├── ozon-integration/
│   │   ├── BRIEF.md
│   │   ├── SPECIFICATION.md
│   │   ├── PLAN.md
│   │   └── REPORT.md
│   └── site-redesign/
│       └── ...
│
└── methodology/                ← Методология
    └── architect/
        ├── theory/
        ├── standards/
        └── patterns/

Характеристика L0:
- ✅ Организационная структура
- ✅ Монтирует L1:SERVICE, L2:DATA
- ✅ Бизнес-контекст использования
- ❌ НЕТ кода
- ❌ НЕТ данных
- Только композиция (mount/link)

5. ПРАВИЛА СВЯЗЕЙ

5.1. Вертикальные связи (обязательные)

Направление: СВЕРХУ ВНИЗ (от абстрактного к конкретному)

L0 extends L1  (ORG специализирует SERVICE)
L1 extends L2  (SERVICE специализирует DATA)
L2 extends L3  (DATA специализирует INFRA)

Обратно: ЗАПРЕЩЕНО
L3 НЕ знает о L2, L1, L0
L2 НЕ знает о L1, L0
L1 НЕ знает о L0

5.2. Горизонтальные связи (опциональные)

Внутри уровня:

L1: SERVICE/pim → SERVICE/analytics        ✅ OK
L2: DATA/pim    → DATA/customers           ✅ OK

Типы связей:
- calls        (вызов API)
- depends_on   (зависимость)
- provides_to  (предоставляет сервис)
- uses         (использует ресурс)

5.3. Диагональные связи (исключения)

Можно пропускать уровни ВНИЗ:

L0 → L3    ✅ OK (direct mount к серверу)
L1 → L3    ✅ OK (bypass L2)

НО НЕ ВВЕРХ:
L3 → L0    ❌ ЗАПРЕЩЕНО

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

6.1. Файлы документации

Файл Назначение Используется для
SPECIFICATION.md Спецификация сущности Любая сущность (9/7/5/4 вопросов)
ARCHITECTURE.md Архитектура ИТ-системы
README.md Краткое введение Любая сущность
CLAUDE.md Контекст для AI Проекты, системы
index.yaml Структурированные метаданные Все сущности
BRIEF.md Бриф от клиента Клиентские проекты
PLAN.md План работ Клиентские проекты

ЗАПРЕЩЕНО:
- ❌ PROJECT.md для систем/данных
- ❌ Использовать "проект" без уточнения

6.2. Директории

Уровни:
L0-ORG/
L1-SERVICE/
L2-DATA/
L3-INFRA/

Внутри уровней:
business-units/         (не "projects"!)
client-projects/        (единственное "projects")
systems/                (не "services"!)
datasets/
connections/
database-engines/       (не "databases"!)

7. ПРИМЕРЫ РЕОРГАНИЗАЦИИ

7.1. Пример: PIM

Было (старая структура):

projects/pirotehnika/
└── services/
    └── @pim.service/
        ├── solution/
        │   ├── app/            ← API
        │   ├── scripts/        ← Обработки
        │   └── config/
        └── data/               ← ЧТО ЭТО???

Стало (новая структура):

L3-INFRA/database-engines/postgresql-001/
    ├── SPECIFICATION.md
    └── config.yaml (host, port)

L2-DATA/connections/pim-db/
    ├── config.yaml
    │   mount: /L3-INFRA/database-engines/postgresql-001
    │   database: nocodb, schema: pt7k98pv0fwi1el
    └── credentials.enc

L2-DATA/datasets/pim/
    ├── SPECIFICATION.md (5 вопросов)
    ├── schema.sql
    ├── migrations/
    └── connection → /L2-DATA/connections/pim-db

L1-SERVICE/systems/pim/
    ├── SPECIFICATION.md (7 вопросов)
    ├── ARCHITECTURE.md
    │
    ├── api/
    │   └── mount: /L2-DATA/datasets/pim
    │
    ├── processors/
    │   ├── import_from_1c.py
    │   │   mount: /L2-DATA/connections/1c-odata
    │   └── sync_to_1c.py
    │
    └── ui/nocodb/

L0-ORG/business-units/pirotehnika/operations/pim/
    ├── SPECIFICATION.md (контекст использования)
    ├── mount: /L1-SERVICE/systems/pim
    └── mount: /L2-DATA/datasets/pim

7.2. Пример: Сайт pirotehnika.spb.ru

Было:

projects/pirotehnika/retail/@site/
├── solution/opencart/
└── data/                   ← ???

Стало:

L3-INFRA/compute/servers/beget-kondurov/
    └── SPECIFICATION.md

L3-INFRA/database-engines/mysql-opencart/
    └── mount: beget-kondurov

L2-DATA/datasets/opencart/
    ├── schema.sql
    └── connection → mysql-opencart

L1-SERVICE/systems/opencart/
    ├── ui/web/             ← OpenCart код
    ├── ui/admin/
    └── mount: /L2-DATA/datasets/opencart

L0-ORG/business-units/pirotehnika/channels/retail/site/
    ├── mount: /L1-SERVICE/systems/opencart
    ├── mount: /L2-DATA/datasets/opencart
    └── deployed_on: /L3-INFRA/compute/servers/beget-kondurov

8. МИГРАЦИЯ

8.1. Этапы миграции

Этап 1: Создать новую структуру L0-L3
Этап 2: Переместить INFRA → L3
Этап 3: Переместить DATA → L2
Этап 4: Переместить SERVICE → L1
Этап 5: Реорганизовать ORG → L0
Этап 6: Обновить все ссылки (mount/link)
Этап 7: Удалить старую структуру

8.2. План действий

Фаза 1: Подготовка (без изменений)
1. Создать /architect/operations/proposals/PLATFORM_RESTRUCTURE_2025.md ✅
2. Обсудить и утвердить концепцию
3. Создать детальный план миграции

Фаза 2: Создание новой структуры (параллельно со старой)
1. Создать L0-ORG/, L1-SERVICE/, L2-DATA/, L3-INFRA/
2. Инвентаризировать все ресурсы
3. Начать переносить по одному ресурсу

Фаза 3: Миграция
1. Начать с L3:INFRA (фундамент)
2. Затем L2:DATA
3. Затем L1:SERVICE
4. Последним L0:ORG

Фаза 4: Переключение
1. Обновить все ссылки
2. Протестировать
3. Удалить старую структуру

9. ОТКРЫТЫЕ ВОПРОСЫ

9.1. Терминология

9.2. Структура

9.3. Связи

10. ПЛАТФОРМЕННЫЕ ПРИЛОЖЕНИЯ vs СЕРВИСЫ БИЗНЕСА

10.1. Критическое различие

ПЛАТФОРМЕННОЕ ПРИЛОЖЕНИЕ:
- Переиспользуемый сервис для всех проектов
- Примеры: NocoDB, n8n, Metabase, MinIO
- Размещение: /PLATFORM/applications/
- Изоляция: Isolated/Dedicated (своя схема, свой контейнер)
- Multi-tenancy: Да (workspaces)

СЕРВИС БИЗНЕС-ЕДИНИЦЫ:
- Принадлежит конкретной бизнес-единице
- Примеры: PIM для pirotehnika, Loyalty для lideravto
- Размещение: /L0-ORG/business-units/{name}/services/
- Изоляция: Shared/Isolated (префикс в схеме бизнеса)
- Multi-tenancy: Нет

10.2. Структура

/PLATFORM/
├── applications/          ← ПЛАТФОРМЕННЫЕ ПРИЛОЖЕНИЯ
│   ├── nocodb/
│   │   ├── SPECIFICATION.md
│   │   ├── schema/
│   │   ├── api/
│   │   └── ui/
│   ├── n8n/
│   ├── metabase/
│   └── minio/
│
└── infrastructure/        ← Базовая инфраструктура
    ├── postgresql/
    ├── redis/
    └── nginx/

/L0-ORG/business-units/pirotehnika/
├── SPECIFICATION.md
├── services/              ← СЕРВИСЫ БИЗНЕС-ЕДИНИЦЫ
│   ├── pim/              ← Использует NocoDB
│   ├── analytics/
│   └── integration-hub/
├── channels/
│   └── retail/
└── connections/           ← КОННЕКТОРЫ к платформенным приложениям
    └── pim.yaml

10.3. Пример: PIM

Неправильно (старое понимание):

/L1-SERVICE/systems/pim/   ← ❌ PIM не является платформенным сервисом!

Правильно (новое понимание):

Вариант A: PIM как платформенное приложение

/PLATFORM/applications/pim/
├── SPECIFICATION.md       ← Определение (класс)
├── schema/
│   ├── pim_products
│   ├── pim_brands
│   └── pim_categories
├── api/
│   └── endpoints.yaml
└── ui/
    └── components/

/L0-ORG/business-units/pirotehnika/connections/pim.yaml
  ← Использование (инстанс) для pirotehnika

/L0-ORG/business-units/lideravto/connections/pim.yaml
  ← Использование (инстанс) для lideravto

Вариант B: PIM как сервис бизнес-единицы (пока)

/L0-ORG/business-units/pirotehnika/
├── services/pim/          ← Принадлежит только pirotehnika
│   ├── index.yaml
│   └── uses_platform_apps:
│       └── nocodb         ← Использует NocoDB для хранения
└── connections/
    └── pim-nocodb.yaml    ← Коннектор к NocoDB

Решение: Сначала Вариант B (потом, когда появится необходимость у других бизнесов, мигрируем в Вариант A)

10.4. Ресурсы

Тип Database Storage Compute Примечание
Platform App Isolated schema Isolated path Dedicated container Своя схема platform_nocodb
Business Service Shared schema Sub-path Shared/Uses app Префикс pim_ в схеме bu_piro

11. ОПРЕДЕЛЕНИЕ vs ИСПОЛЬЗОВАНИЕ

11.1. Два уровня абстракции

ОПРЕДЕЛЕНИЕ (класс, спецификация):
- /PLATFORM/applications/pim/SPECIFICATION.md
- Что делает сервис
- Какие таблицы нужны (структура)
- Какие API endpoints
- Какой UI
- Независимо от конкретного развертывания

ИСПОЛЬЗОВАНИЕ (инстанс, подключение):
- /L0-ORG/business-units/pirotehnika/connections/pim.yaml
- ГДЕ развернут (схема bu_piro, префикс pim_)
- КАК подключиться (URL, credentials)
- КТО может использовать (roles)

11.2. Пример: PIM

Определение (класс):

# /PLATFORM/applications/pim/SPECIFICATION.md
components:
  database:
    tables:
      - pim_products (id, name, sku, brand_id)
      - pim_brands (id, name)
      - pim_categories

    functions:
      - get_product_by_id(id)
      - search_products(query)

  api:
    endpoints:
      - GET /products
      - GET /products/{id}
      - POST /products

  ui:
    pages:
      - products-list
      - product-editor

Использование (инстанс):

# /L0-ORG/business-units/pirotehnika/connections/pim.yaml
deployment:
  database:
    instance: /L3-INFRA/database-engines/postgresql-001
    schema: bu_piro              # Схема бизнеса
    prefix: pim_                 # Префикс таблиц

    # Реальные таблицы:
    tables:
      - bu_piro.pim_products
      - bu_piro.pim_brands
      - bu_piro.pim_categories

  api:
    url: https://pim.pirotehnika.internal
    credentials: vault:/business-units/pirotehnika/connections/pim

  ui:
    url: https://pim.pirotehnika.spb.ru
    access:
      roles: [manager, operator]

11.3. Работа оператора

Оператор → UI → API → CONNECTION → SERVICE definition

1. Оператор открывает:
   https://pim.pirotehnika.spb.ru

2. UI обращается к API:
   https://pim.pirotehnika.internal/api/products

3. API читает данные:
   SELECT * FROM bu_piro.pim_products

4. Через CONNECTION:
   /L0-ORG/business-units/pirotehnika/connections/pim.yaml

5. Ссылается на SERVICE:
   /PLATFORM/applications/pim/

Уровни:
- L3-INFRA: Физические таблицы bu_piro.pim_products
- L2-DATA: Коннектор /connections/pim.yaml
- L1-SERVICE: Определение /PLATFORM/applications/pim/
- L0-ORG: Работа оператора

12. ТЕРМИНОЛОГИЯ БД

12.1. Правильные термины

Server (сервер)              ← L3-INFRA
└── Instance (инстанс)       ← L3-INFRA
    └── Database (база)      ← L3-INFRA
        └── Schema (схема)   ← L0/L1/L2
            └── Tables       ← L0/L1/L2

Уровни изоляции (от меньшего к большему):

Уровень Термин (рус) Термин (eng) PostgreSQL Пример
L0 Префикс таблиц Table Prefix pim_products Минимальная
L1 Схема Schema bu_piro Низкая
L2 База данных Database pirotehnika_db Средняя
L3 Инстанс Instance postgres:5432 Высокая
L4 Сервер Server postgresql-001 Максимальная

12.2. Пример для pirotehnika

Что есть у pirotehnika:

Сервер: postgresql-001                    ← L3-INFRA
└── Инстанс: postgres:5432                ← L3-INFRA
    └── База: postgres                    ← L3-INFRA (общая)
        └── Схема: bu_piro                ← L0-ORG (namespace бизнес-единицы)
            ├── pim_products              ← Сервис PIM
            ├── pim_brands
            ├── pim_categories
            ├── retail_cart               ← Канал retail
            └── retail_orders

Правильная терминология:

❌ Неправильно ✅ Правильно
"У pirotehnika своя база данных" "У pirotehnika своя схема в общей БД"
"PIM использует отдельную базу" "PIM использует префикс pim_ в схеме bu_piro"
"Создать инстанс для PIM" "Создать таблицы pim_* в схеме bu_piro"

12.3. Изоляция по уровням сущностей

Сущность Минимум По умолчанию Максимум
L0: ORG (Business Unit) Shared (prefix) Isolated (schema) Standalone (server)
L1: SERVICE Shared (prefix) Isolated (schema) Dedicated (instance)
L2: DATA Shared (prefix) Isolated (schema) Isolated (schema)
L3: INFRA Shared (process) Dedicated (instance) Standalone (server)

Правила:
- ✅ Можно ПОВЫШАТЬ изоляцию (Shared → Isolated → Dedicated → Standalone)
- ❌ Нельзя ПОНИЖАТЬ изоляцию для production
- ⚠️ L1-SERVICE не может иметь Standalone (только до Dedicated)
- ⚠️ L2-DATA не владеет ресурсами (максимум Isolated для метаданных)

13. ОБНОВЛЕННАЯ СТРУКТУРА WORKSPACE

13.1. Топ-уровень

workspace/
├── L0-ORG/               ← Организация
│   ├── business-units/
│   ├── channels/
│   └── client-projects/
│
├── L1-SERVICE/           ← Сервисы (DEPRECATED - переносим в PLATFORM или L0)
│
├── L2-DATA/              ← Данные (коннекторы, схемы)
│   ├── connections/
│   ├── schemas/
│   └── datasets/
│
├── L3-INFRA/             ← Инфраструктура
│   ├── compute/
│   ├── storage/
│   ├── network/
│   └── database-engines/
│
├── PLATFORM/             ← НОВОЕ: Платформа
│   ├── applications/     ← Платформенные приложения
│   └── infrastructure/   ← Базовая инфраструктура платформы
│
└── GROUP/                ← Общие ресурсы
    ├── shared/
    ├── templates/
    └── docs/

13.2. Business Unit с сервисами

/L0-ORG/business-units/pirotehnika/
├── SPECIFICATION.md       ← 9 вопросов (бизнес-единица)
├── index.yaml            ← Метаданные
│
├── services/             ← СЕРВИСЫ БИЗНЕС-ЕДИНИЦЫ
│   ├── pim/
│   │   ├── index.yaml
│   │   ├── schema/       ← Схема таблиц pim_*
│   │   ├── api/          ← API endpoints (если есть свой API)
│   │   └── config/       ← Конфигурация
│   │
│   ├── analytics/
│   └── integration-hub/
│
├── channels/             ← КАНАЛЫ ПРОДАЖ
│   ├── retail/
│   ├── wholesale/
│   └── ozon/
│
└── connections/          ← КОННЕКТОРЫ
    ├── pim-nocodb.yaml   ← Подключение PIM к NocoDB
    ├── site-db.yaml      ← Подключение сайта к БД
    └── s3.yaml           ← Подключение к S3

13.3. Platform Applications

/PLATFORM/applications/
├── nocodb/
│   ├── SPECIFICATION.md   ← Что делает, какие компоненты
│   ├── docker-compose.yml
│   ├── config/
│   └── workspaces/        ← Multi-tenancy
│       ├── piro-pim/
│       └── lider-crm/
│
├── n8n/
│   ├── SPECIFICATION.md
│   ├── workflows/
│   └── credentials/
│
├── metabase/
└── minio/

14. МИГРАЦИОННЫЙ ПЛАН

14.1. Фаза 1: Создать структуру PLATFORM

# Создать /PLATFORM/
mkdir -p /PLATFORM/applications
mkdir -p /PLATFORM/infrastructure

# Переместить NocoDB
mv /system/nocodb /PLATFORM/applications/nocodb

# Обновить документацию
# SPECIFICATION.md для каждого приложения

14.2. Фаза 2: Реорганизовать PIM

Текущее (неправильно):

/L1-SERVICE/systems/pim/

Вариант A: Временно как сервис бизнеса

/L0-ORG/business-units/pirotehnika/services/pim/
├── index.yaml
├── uses_platform_apps: [nocodb]
└── schema/
    └── pim-tables.sql

Вариант B: Как платформенное приложение (если нужно переиспользование)

/PLATFORM/applications/pim/
└── (потом, когда понадобится в других бизнесах)

14.3. Фаза 3: Обновить connections

Создать коннекторы:

# /L0-ORG/business-units/pirotehnika/connections/pim-nocodb.yaml
connection:
  name: pim-nocodb
  service: /PLATFORM/applications/nocodb
  workspace: piro-pim

  database:
    schema: bu_piro
    prefix: pim_
    tables:
      - pim_products
      - pim_brands

  credentials:
    vault_path: /business-units/pirotehnika/connections/pim-nocodb

14.4. Фаза 4: Документировать стандарты

15. СЛЕДУЮЩИЕ ШАГИ

  1. Обсудить концепцию
  2. Уточнить терминологию (открытые вопросы)
  3. Определить структуру GROUP/shared vs SYSTEM/lib
  4. Создать детальный план миграции
  5. Выбрать пилотный проект для миграции
  6. Начать перенос по этапам

ПРИЛОЖЕНИЯ

A. Сравнение старой и новой структуры

Аспект Старая структура Новая структура
Уровни Размыты 4 четких уровня (L0-L3)
Термины "Проект" для всего Точные термины
Данные В репо (projects/*/data/) ВНЕ репо (L2-DATA/datasets/)
Связи Неявные Явные (mount/link/extends)
Иерархия Плоская Вертикальная (наследование)

B. Глоссарий

Сущности

Термин Определение
Business Unit Бизнес-единица (не "бизнес-проект")
Platform Application Платформенное приложение (переиспользуемое)
Business Unit Service Сервис бизнес-единицы (принадлежит одному бизнесу)
System ИТ-система (не "ИТ-проект") — DEPRECATED, использовать Platform App или Business Service
Dataset Набор данных
Resource Инфраструктурный ресурс
Project Клиентская работа (ТОЛЬКО!)
Channel Канал продаж

Подключения и связи

Термин Определение
Connection Экземпляр подключения к сервису
Connector Template Шаблон коннектора
Mount Монтирование ресурса
Link Символическая ссылка
Extends Наследование/специализация
Canonical path Каноническое место размещения
Definition Определение сервиса (класс, спецификация)
Usage Использование сервиса (инстанс, подключение)

База данных

Термин (рус) Термин (eng) Определение
Префикс таблиц Table Prefix Минимальная изоляция: pim_products
Схема Schema Namespace в базе: bu_piro
База данных Database Catalog: pirotehnika_db
Инстанс Instance Процесс СУБД: postgres:5432
Сервер Server Физический/виртуальный сервер: postgresql-001

Уровни изоляции

Термин Определение
Shared Минимальная изоляция (префикс таблиц, общий контейнер)
Isolated Низкая изоляция (отдельная схема, изолированный path)
Dedicated Высокая изоляция (отдельный instance/VM)
Standalone Максимальная изоляция (отдельный сервер)

Статус: DRAFT — требуется обсуждение и утверждение
Следующий шаг: Обсудить открытые вопросы, уточнить детали