Система связей (Links)

Версия: 1.0.0
Дата: 2025-12-20
Статус: active

Назначение

Явная декларация зависимостей и связей между модулями платформы.

Проблема: Модули переиспользуют ресурсы друг друга, но это нигде не зафиксировано.

Решение: Секция links: в index.yaml каждого модуля.

Типы связей

Тип	Описание	Пример
`uses`	Использую модуль/ресурс	credentials из infra/
`reads`	Читаю данные	прайсы из DATASPACE
`writes`	Пишу данные	заказы в NocoDB
`provides`	Предоставляю другим	REST API
`extends`	Расширяю/наследую	тема на основе Nova

Протоколы путей

Протокол	Описание	Пример
(нет)	Относительно $WORKSPACE	`infra/@beget.server`
`$DATASPACE/`	S3 хранилище данных	`$DATASPACE/pirotehnika/prices/`
`nocodb://`	База NocoDB	`nocodb://pirotehnika/Product`
`http://`	Внешний API/сервис	`http://api.ozon.ru/`
`server://`	Путь на сервере	`server://beget/home/kondurov/`
`env://`	Переменная окружения	`env://OZON_API_KEY`

Формат в index.yaml

name: "module-name"
type: service
version: "1.0.0"

links:
  uses:
    - path: "infra/@beget.server"
      what: "SSH, MySQL"
    - path: "system/scripts/backup.sh"
      what: "Скрипт бэкапа"

  reads:
    - path: "$DATASPACE/pirotehnika/prices/"
      what: "Прайсы поставщиков"
    - path: "nocodb://pirotehnika/Product"
      what: "Каталог товаров"

  writes:
    - path: "nocodb://pirotehnika/Order"
      what: "Заказы"
    - path: "$DATASPACE/pirotehnika/exports/"
      what: "Выгрузки"

  provides:
    - path: "/api/v1/orders"
      what: "REST API заказов"
    - path: "/api/v1/prices"
      what: "REST API цен"

Формат в CLAUDE.md

## Связи

| Тип | Путь | Описание |
|-----|------|----------|
| uses | `infra/@beget.server` | SSH, MySQL |
| reads | `nocodb://pirotehnika/Product` | Каталог |
| writes | `nocodb://pirotehnika/Order` | Заказы |
| provides | `/api/v1/orders` | REST API |

Или развёрнуто:

## Связи

### Использует
- `infra/@beget.server` — SSH, MySQL доступ
- `system/scripts/backup.sh` — скрипт бэкапа

### Читает
- `$DATASPACE/pirotehnika/prices/` — прайсы поставщиков
- `nocodb://pirotehnika/Product` — каталог товаров

### Пишет
- `nocodb://pirotehnika/Order` — заказы

### Предоставляет
- `/api/v1/orders` — REST API заказов

Примеры по слоям

Проект

# projects/pirotehnika/index.yaml
name: "pirotehnika"
type: commercial

links:
  uses:
    - path: "infra/@beget.server"
      what: "Хостинг сайтов"
    - path: "infra/@dev-pro.server"
      what: "NocoDB, MP1"
  reads:
    - path: "$DATASPACE/pirotehnika/"
      what: "Все данные проекта"
    - path: "nocodb://pirotehnika"
      what: "База данных"

Сервис

# projects/pirotehnika/app/mp1/index.yaml
name: "mp1"
type: service

links:
  uses:
    - path: "../../data/connectors/ozon"
      what: "OZON клиент"
  reads:
    - path: "nocodb://pirotehnika/Product"
    - path: "nocodb://pirotehnika/Order"
    - path: "http://api-seller.ozon.ru/"
      what: "OZON Seller API"
  writes:
    - path: "nocodb://pirotehnika/Order"
  provides:
    - path: "http://91.218.142.168:8504/api/v1/"
      what: "REST API"

Сайт

# projects/pirotehnika/app/site/pirotehnika.spb.ru/index.yaml
name: "pirotehnika.spb.ru"
type: site

links:
  uses:
    - path: "infra/@beget.server"
      what: "Хостинг"
  reads:
    - path: "server://beget/home/kondurov/pirotehnika.spb.ru/"
      what: "Файлы сайта"
    - path: "nocodb://pirotehnika/Product"
      what: "Синхронизация товаров"

Инфраструктура

# infra/@beget.server/index.yaml
name: "@beget.server"
type: server

links:
  provides:
    - what: "SSH доступ"
    - what: "MySQL базы"
    - what: "PHP 8.2"
    - what: "Nginx"
    - what: "Cron"

Данные

# projects/pirotehnika/data/index.yaml
name: "data"
type: data

links:
  reads:
    - path: "http://baz-on.ru/export/"
      what: "BAZON прайсы"
    - path: "http://api.pochta.ru/"
      what: "Почта России API"
  writes:
    - path: "$DATASPACE/pirotehnika/"
      what: "Файловое хранилище"
    - path: "nocodb://pirotehnika"
      what: "База данных"
  provides:
    - path: "connectors/"
      what: "Коннекторы к источникам"

Правила

Обязательность

Уровень	links: обязателен?
Проект (корень)	Да
Приложение (app/)	Да
Данные (data/)	Да
Модуль внутри app/	Рекомендуется
Скрипты	Нет

Относительные пути

Внутри проекта: относительно текущего модуля
Между проектами: от корня $WORKSPACE

# Внутри проекта
uses:
  - path: "../modules/lider_import"  # относительно

# Между проектами
uses:
  - path: "infra/@beget.server"      # от корня
  - path: "system/scripts/backup.sh" # от корня

Внешние источники

Всегда полный URL с протоколом:

reads:
  - path: "http://api.ozon.ru/v1/"
  - path: "https://baz-on.ru/export/"

Валидация

Проверки при линтинге:

Существование пути — путь должен существовать (кроме http://)
Циклические зависимости — A→B→A запрещено
Версии — если указана версия, проверить совместимость

Команды (планируется)

# Показать связи модуля
platform links projects/pirotehnika

# Кто использует этот модуль?
platform links --reverse infra/@beget.server

# Граф зависимостей
platform links --graph > deps.dot

# Проверить целостность
platform links --check

# Найти неиспользуемые модули
platform links --orphans

История

Дата	Версия	Изменения
2025-12-20	1.0.0	Создание стандарта

Стандарт: architect/standards/LINKS.md