# Пакетная платформа

## Назначение

Домен описывает плагины, пакеты руководящей документации, клиентские подключения к магазинам пакетов, каталоги, версии, установку, верификацию, права доступа и коммерческий статус пакетов.

## Границы домена

| Входит в домен | Не входит в домен |
|---|---|
| Локальный каталог установленных пакетов, доступный каталог, источники магазинов, версии, manifest, схемы секретов, верификация и ценовые метаданные. | Нагрузки плагинов в runtime-контуре, Git-истина репозиториев пакетов, сырые секреты, биллинг, счета, пользовательский интерфейс и бизнес-система магазина пакетов. |

## Документы домена

| Документ | Назначение |
|---|---|
| `product/requirements.md` | Продуктовые требования к пакетной платформе. |
| `architecture/design.md` | Граница сервиса, основные потоки, события и междоменные связи. |
| `architecture/data_model.md` | Целевая модель данных `package-hub`. |
| `architecture/api_contract.md` | Обзор будущих gRPC-операций и событий `package.*`. |
| `delivery/package_hub.md` | План поставки домена малыми срезами. |
| `operations/package_hub_runbook.md` | Runbook эксплуатации `package-hub`. |

## Связанные каталоги

- `docs/catalogs/package-store/`
- `docs/catalogs/plugins/`
- `docs/catalogs/guidance-packages/`

## Ключевые решения

- Каталог установленных пакетов хранится локально в платформе.
- Каталог доступных пакетов получает данные через клиентские подключения к магазинам пакетов.
- Магазин пакетов является устанавливаемым пакетом из репозитория-источника.
- Пакетная платформа не владеет магазином как бизнес-системой: она выступает клиентом магазина, хранит подключение, синхронизирует доступные пакеты и управляет локальными установками.
- Авторский магазин `kodex` живёт в приватном репозитории `github.com/codex-k8s/kodex-package-store` и не вшивается в ядро платформы.
- Сайт и пользовательская документация платформы поставляются отдельным пакетом из приватного репозитория `github.com/codex-k8s/kodex-package-platform-site`. В этот пакет входят материалы для пользователей платформы: API, разработка пакетов, добавление пакетов в магазин и каталог.
- В основном репозитории оба приватных источника объявлены в `.gitmodules` и checkout-ятся внутри `packages/**` после проверки доступа.
- Метаданные установленных пакетов хранятся в БД платформы и могут предзаполняться из JSON-манифеста внутри репозитория пакета.
- Установленные пакеты, клиентские пакеты и платные пакеты размещаются в `packages/**`; конкретная версия фиксируется gitlink, `tag` или `commit` по контракту пакетной платформы.
- Платные пакеты поставляются через прокси платформы, а downstream-репозитории очищают магазин, сайт и необязательные пакеты отдельным workflow.
- `package-hub` публикует `package.*` события, но не запускает runtime-нагрузки и не становится оркестратором исполнения.
- Руководящие пакеты не смешиваются с проектной документацией: проектная документация описывается проектной политикой, а руководящие пакеты остаются пакетами со своей версией и источником.
- Руководящие пакеты читаются через общие операции `ListPackages`, `ListPackageInstallations` и `GetPackageManifest` с видом `guidance`; отдельная сущность руководства в БД не создаётся.
- Использование руководящих пакетов в workspace описано в `docs/domains/agent-orchestration/architecture/guidance_workspace_context.md`: `package-hub` отдаёт refs и digest, а runtime-контур выполняет checkout/mount.
- Пакет магазина и пакет пользовательского контента платформы читаются через те же операции с видами `store` и `platform_content`; `package-hub` не хранит бизнес-состояние магазина и файлы сайта или документации в БД.
- Эксплуатационный контур `package-hub` включает отдельный Dockerfile, Kubernetes manifests, migration job, health/metrics, проверку готовности и runbook; запуск runtime-нагрузок пакетов остаётся за соседними доменами.
- Сырые значения секретов установки не попадают в `package-hub`: домен хранит схему и статус заполненности, а доступность проверяется по ссылкам из `access-manager` через общий checker без возврата значения.

## Карта Issue

- Доменная карта: `docs/delivery/issue-map/domains/package-platform.md`.
