---
doc_id: PRD-CK8S-PACKAGE-0001
type: prd
title: kodex — требования домена пакетной платформы
status: active
owner_role: PM
created_at: 2026-05-06
updated_at: 2026-05-11
related_issues: [642, 700, 704, 706, 711]
related_prs: []
related_docsets:
  - docs/platform/product/requirements.md
  - docs/platform/architecture/domain_map.md
  - docs/platform/architecture/service_boundaries.md
approvals:
  required: ["Owner"]
  status: approved
  request_id: "owner-2026-05-06-package-platform-kickoff"
  approved_by: "ai-da-stas"
  approved_at: 2026-05-06
---

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

## TL;DR

- Что строим: домен `package-hub` для локального каталога установленных пакетов, доступных пакетов, источников магазинов, версий, верификации и пакетных метаданных.
- Для кого: владелец платформы, администраторы, операторы, `agent-manager`, `runtime-manager`, `interaction-hub`, `billing-hub` и будущий пользовательский интерфейс управления пакетами.
- Почему: расширения платформы, внешние каналы, руководящие пакеты и пользовательские пакеты нельзя вшивать в ядро или хранить как разрозненные submodule без статуса, прав, версии и аудита.
- Минимум первой версии: встроенные, внешние и пользовательские пакеты; источник магазина; доступный каталог; установленный каталог; manifest; версия; верификация; схема секретов; права установки.
- Критерии успеха: платформа знает, какие пакеты доступны и установлены, откуда они получены, какая версия используется, что пакет требует для запуска и где лежит его источник.

## Проблема и цель

Проблема:
- внешние каналы, например Telegram или другие адаптеры обратной связи, должны подключаться без изменения ядра платформы;
- пакеты руководящей документации живут в отдельных репозиториях и должны попадать агенту в рабочий контур локально;
- магазин доступных пакетов сам является устанавливаемым пакетом, а не встроенной частью ядра;
- платные, бесплатные, проверенные и непроверенные версии должны различаться до установки;
- submodule, gitlink, `tag` и `commit` фиксируют исходник, но не отвечают на вопросы о правах, секретах, статусе установки и доступности пакета.

Цель:
- создать сервис-владелец пакетного состояния;
- разделить источник пакета, доступный каталог, установку, runtime-нагрузку и коммерческий контур;
- дать другим доменам один авторитетный способ узнать, какие пакеты доступны, какие установлены и какие требования они предъявляют.

## Пользователи и роли

| Роль | Главный сценарий |
|---|---|
| Владелец платформы | Управляет встроенными и внешними пакетами, включает авторский магазин, видит верификацию и коммерческий статус. |
| Администратор организации | Устанавливает разрешённые пакеты для организации, проекта или платформы. |
| Оператор платформы | Диагностирует ошибку синхронизации магазина, установки пакета, схемы секретов или устаревшей версии. |
| Разработчик пакета | Публикует пакет в репозитории-источнике и описывает manifest, права, секреты и runtime-требования. |
| `agent-manager` | Получает сведения о руководящих пакетах, ролях, flow и доступных пакетных возможностях. |
| `runtime-manager` | Получает запрос на подготовку runtime-нагрузки или локального источника, но не хранит пакетную истину. |
| `interaction-hub` | Использует пакеты внешних каналов для уведомлений, вопросов и согласований. |
| `billing-hub` | Получает ценовые метаданные и факты использования платных пакетов для расчётов. |

## Виды пакетов

| Вид | Назначение | Примеры |
|---|---|---|
| Пакет плагина `plugin` | Исполняемое расширение платформы, которое может запускать runtime-нагрузку и предоставлять интеграцию или MCP-инструмент. | Telegram-пакет согласований, пакет внешнего webhook, пакет корпоративного мессенджера. |
| Руководящий пакет `guidance` | Руководящие документы, правила, шаблоны и справочные материалы для агентов. | Общие инженерные правила, Go backend-гайд, Vue frontend-гайд. |
| Пакет магазина `store` | Пакет, предоставляющий магазин доступных пакетов для одной или нескольких установок платформы. | Авторский магазин `kodex`. |
| Пакет пользовательского контента платформы `platform_content` | Пользовательская документация и сайт платформы, поставляемые как пакет. | Сайт и документация API, правила разработки пакетов, публикация в каталог. |

Проектная продуктовая документация не становится `guidance package` только потому, что агенту нужно её читать. Её источники описывает проектный контур и `services.yaml`.

## Функциональные требования

| ID | Требование | Приоритет |
|---|---|---|
| PACK-FR-1 | Домен должен хранить локальный каталог установленных пакетов с областью установки: платформа, организация, проект или репозиторий. | Обязательно |
| PACK-FR-2 | Домен должен хранить локальный каталог доступных пакетов, синхронизированный из одного или нескольких источников магазина. | Обязательно |
| PACK-FR-3 | Домен должен поддерживать встроенные, внешние и пользовательские пакеты. | Обязательно |
| PACK-FR-4 | Домен должен различать бесплатные и платные пакеты, а также верифицированные и непроверенные версии. | Обязательно |
| PACK-FR-5 | Домен должен хранить источник пакета как ссылку на репозиторий, `tag`, `commit`, gitlink или источник, доступный через прокси платформы. | Обязательно |
| PACK-FR-6 | Домен должен хранить снимок manifest пакета и результат его проверки. | Обязательно |
| PACK-FR-7 | Manifest пакета должен описывать вид пакета, метаданные, версии, требуемые права, требуемые API платформы, схемы секретов, runtime-требования и локализованные описания. | Обязательно |
| PACK-FR-8 | Домен должен хранить схемы секретов и статус заполненности секретов для установки; канонические ссылки на заполненные секреты остаются в `access-manager`, статус проверяется без возврата значения через общий `secretresolver.Checker`, а сырые значения секретов не хранятся в `package-hub`. | Обязательно |
| PACK-FR-9 | Домен должен проверять права установки и управления пакетом через `access-manager`. | Обязательно |
| PACK-FR-10 | Домен должен публиковать `package.*` события при обнаружении, синхронизации, установке, обновлении, отключении, отзыве или изменении верификации пакета. | Обязательно |
| PACK-FR-11 | Домен должен поддерживать идемпотентные команды и ожидаемую версию для конкурентных изменений установки. | Обязательно |
| PACK-FR-12 | Домен должен отдавать другим сервисам авторитетные чтения установленных пакетов, доступных пакетов, manifest, схем секретов и требований runtime. | Обязательно |
| PACK-FR-13 | Домен не должен запускать runtime-нагрузку плагина, выполнять checkout, управлять Kubernetes или читать БД других сервисов. | Обязательно |
| PACK-FR-14 | Домен не должен владеть бизнес-логикой магазина пакетов: магазин подключается как пакет и предоставляет каталог через согласованный клиентский контракт. | Обязательно |
| PACK-FR-15 | Домен должен сохранять ценовые метаданные пакета для будущего биллинга, но не выставлять счета и не принимать платежи. | Обязательно |
| PACK-FR-16 | Домен должен поддерживать пользовательские источники пакетов без обязательной публикации в авторском магазине. | Обязательно |

## Критерии приёмки

| ID | Критерий |
|---|---|
| PACK-AC-1 | Если подключён магазин пакетов, платформа синхронизирует доступный каталог и показывает источник, версию, статус проверки и коммерческий статус пакетов. |
| PACK-AC-2 | Если пользователь устанавливает пакет, `package-hub` фиксирует область установки, версию, manifest, требования и статус, а запуск runtime-нагрузки остаётся за runtime-контуром. |
| PACK-AC-3 | Если пакет требует секреты, платформа показывает форму по схеме manifest, создаёт привязки секретов через `access-manager` и сохраняет в `package-hub` только статус заполненности установки. |
| PACK-AC-4 | Если пакет является руководящим, платформа читает его как `package_kind=guidance` через каталог, установки и manifest, но `package-hub` не смешивает его с проектной документацией и не выполняет checkout в workspace. |
| PACK-AC-5 | Если пакет является магазином, платформа читает его как `package_kind=store` и хранит локальную установку и manifest, но `package-hub` не становится бизнес-системой магазина. |
| PACK-AC-6 | Если пакет является пользовательским контентом платформы, платформа читает его как `package_kind=platform_content`, но не хранит файлы сайта, справки или API-материалов в БД `package-hub`. |
| PACK-AC-7 | Если версия пакета отозвана или потеряла верификацию, установка получает видимый статус риска и событие для потребителей. |
| PACK-AC-8 | Если source submodule недоступен из-за прав, платформа фиксирует проблему доступа, а не подменяет пакет локальной копией. |

## Что не входит

- Не реализовывать бизнес-систему авторского магазина внутри `package-hub`.
- Не запускать нагрузки плагинов в Kubernetes и runtime-нагрузку пакетов.
- Не хранить сырые секреты и канонические ссылки на заполненные секреты.
- Не хранить исходники пакетов или файлы руководящих документов в БД.
- Не выставлять счета и не принимать платежи.
- Не управлять provider-native репозиториями пакетов напрямую.
- Не проектировать полный пользовательский интерфейс управления пакетами в этом документе.

## Нефункциональные требования

| ID | Категория | Требование |
|---|---|---|
| PACK-NFR-1 | Надёжность | Каждое изменение установки, источника или статуса верификации публикует доменное событие через outbox. |
| PACK-NFR-2 | Производительность | Списки доступных и установленных пакетов читаются пакетно, без обращения к внешнему магазину на каждый пользовательский запрос. |
| PACK-NFR-3 | Безопасность | Управление пакетами требует проверки прав через `access-manager`; секреты передаются только как ссылки на хранилище секретов. |
| PACK-NFR-4 | Наблюдаемость | Ошибки синхронизации магазина, проверки manifest, доступа к источнику и установки пакета логируются с correlation id. |
| PACK-NFR-5 | Расширяемость | Новый вид пакета должен добавляться через manifest и policy-решение, а не через переписывание ядра. |
| PACK-NFR-6 | Локализация | Названия, описания, поля секретов и предупреждения пакета должны поддерживать локали. |
| PACK-NFR-7 | Совместимость | GitHub — первый источник репозиториев пакетов, но модель не должна блокировать GitLab. |

## Зависимости

| Зависимость | Зачем нужна |
|---|---|
| `access-manager` | Проверка прав на управление источниками, установками, верификацией и областью применения пакета; владение ссылками на заполненные секреты. |
| `provider-hub` | Зеркало репозиториев-источников пакетов, webhook и операции провайдера. |
| `project-catalog` | Проектная политика и `services.yaml`, где описываются источники рабочего контура и пакетные привязки проекта. |
| `runtime-manager` | Подготовка runtime-нагрузки плагина, checkout локального источника и технические задания установки. |
| `fleet-manager` | Выбор инфраструктурного контура для пакета, который требует runtime-нагрузку. |
| `agent-manager` | Использует руководящие пакеты, роли и возможности пакетов при подготовке агентной работы. |
| `interaction-hub` | Использует пакеты внешних каналов для сообщений, вопросов и Human gate. |
| `billing-hub` | Получает ценовые метаданные и факты использования платных пакетов. |

## Апрув

- request_id: `owner-2026-05-06-package-platform-kickoff`
- Решение: approved
- Комментарий: требования домена пакетной платформы согласованы как целевое состояние стартового среза.
