---
doc_id: PRD-CK8S-PROJ-0001
type: prd
title: kodex — требования домена проектов и репозиториев
status: active
owner_role: PM
created_at: 2026-05-05
updated_at: 2026-05-27
related_issues: [628, 629, 630, 631, 632, 633, 818, 864]
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-05-wave8-project-catalog-kickoff"
  approved_by: "ai-da-stas"
  approved_at: 2026-05-05
---

# PRD: проекты и репозитории

## TL;DR

- Что строим: домен `project-catalog` для проектов, репозиториев, `services.yaml`, источников проектной документации, правил веток, релизных политик и политики размещения.
- Для кого: владелец платформы, операторы, администраторы проектов, `agent-manager`, `provider-hub`, `runtime-manager` и `operations-hub`.
- Почему: без авторитетного каталога проектов другие сервисы начнут хранить локальные копии проектной политики и расходиться в том, какие репозитории, документы, ветки и релизные правила считаются действующими.
- Минимум первой версии: проект, репозиторий, источник проектной документации, политика `services.yaml`, правила веток, релизная политика, релизная линия и политика размещения.
- Критерии успеха: сервисы могут получать проверенную проекцию проектной политики через `project-catalog`, а не читать `services.yaml` и настройки напрямую из разных мест.

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

Проблема:
- проект может включать несколько репозиториев;
- код, проектная документация и документация отдельных сервисов могут жить в разных репозиториях;
- агенту нужно получать в рабочий контур только разрешённые источники кода, проектной документации и руководящих пакетов;
- правила веток и релизные политики должны быть управляемыми объектами платформы, но их декларативное изменение должно проходить через Git и PR вместе с кодом;
- подключение пустого или существующего репозитория нельзя привязать только к GitHub/GitLab, потому что платформа должна владеть проектной политикой независимо от конкретного провайдера.

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

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

| Роль | Главный сценарий |
|---|---|
| Владелец платформы | Создаёт проекты, подключает репозитории и задаёт базовые политики работы. |
| Администратор проекта | Управляет репозиториями проекта, источниками документации, ветками и релизной политикой. |
| Оператор платформы | Видит, какой проект, репозиторий, сервис и источник документации участвуют в работе. |
| `agent-manager` | Получает проектный контекст, выбирает flow и формирует контекст для ролевого агента. |
| `runtime-manager` | Получает политику рабочего контура, но не становится владельцем проектной документации. |
| `provider-hub` | Связывает provider-native артефакты с проектами и репозиториями. |
| `operations-hub` | Строит проекции чтения для UI поверх проектного каталога и событий. |

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

| ID | Требование | Приоритет |
|---|---|---|
| PROJ-FR-1 | Домен должен хранить проект как каноническую сущность с организацией-владельцем, статусом, slug, названием, описанием, опциональной ссылкой на иконку в бакете и версией. | Обязательно |
| PROJ-FR-2 | Проект может содержать один или несколько репозиториев. | Обязательно |
| PROJ-FR-3 | Репозиторий должен хранить поставщика, владельца, имя, URL, ветку по умолчанию, статус подключения, область проекта, опциональную ссылку на иконку в бакете и версию. | Обязательно |
| PROJ-FR-4 | Домен должен хранить проверенную проекцию политики `services.yaml`, управляемой через Git, включая версию, источник, commit, хэш файла, проверенный снимок и статус валидации. | Обязательно |
| PROJ-FR-5 | Домен должен описывать источники проектной документации: общий проектный источник, источник сервиса, источник зависимого сервиса и режим доступа `read`/`write`. | Обязательно |
| PROJ-FR-6 | Домен должен уметь вернуть разрешённый состав рабочего контура для задачи: кодовые репозитории, проектные документы, документы сервисов и ссылки на руководящие пакеты. | Обязательно |
| PROJ-FR-7 | Домен должен хранить правила веток для репозитория или проекта: защищённые ветки, релизные ветки, допустимую стратегию слияния и обязательные проверки как политику. | Обязательно |
| PROJ-FR-8 | Домен должен хранить релизную политику: релизную линию, шаблон релизной ветки, стратегию выкладки, политику отката и связь с управлением рисками и релизами. | Обязательно |
| PROJ-FR-9 | Домен должен хранить политику размещения: допустимые контуры серверов и кластеров для проекта, репозитория или тяжёлого сервиса. | Обязательно |
| PROJ-FR-10 | Домен должен публиковать `project.*` события при изменении проекта, репозитория, документационных источников, правил веток, релизной политики, релизных линий и политики размещения. | Обязательно |
| PROJ-FR-11 | Домен должен поддерживать идемпотентные команды и ожидаемую версию для конкурентных изменений. | Обязательно |
| PROJ-FR-12 | Домен не должен владеть `Issue`, `PR/MR`, комментариями, webhook и лимитами провайдера. | Обязательно |
| PROJ-FR-13 | Домен не должен выполнять checkout, сборку, deploy или управление slot. | Обязательно |
| PROJ-FR-14 | Домен должен хранить только ссылку на иконку проекта или репозитория в объектном хранилище; бинарные файлы изображений не хранятся в БД `project-catalog`. | Обязательно |
| PROJ-FR-15 | Изменения декларативной проектной политики из пользовательского интерфейса по умолчанию должны создавать PR с правкой `services.yaml`, а не менять каноническое состояние напрямую в БД. | Обязательно |
| PROJ-FR-16 | Прямые операторские переопределения политики допустимы только как исключение: с причиной, сроком действия, аудитом и явным отличием от политики, управляемой через Git. | Обязательно |
| PROJ-FR-17 | При bootstrap пустого репозитория домен должен уметь принять внутренний проверенный provider merge signal и checked artifact metadata, импортировать checked `services.yaml` и активировать repository binding без прямого доступа к GitHub/GitLab. | Обязательно |

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

| ID | Критерий |
|---|---|
| PROJ-AC-1 | Если проект содержит несколько репозиториев, `project-catalog` возвращает единый авторитетный список репозиториев и их статусов. |
| PROJ-AC-2 | Если сервис зависит от общей продуктовой документации и документации других сервисов, политика рабочего контура отражает все разрешённые источники без ручного дублирования в задаче. |
| PROJ-AC-3 | Если `services.yaml` изменился и изменение прошло слияние PR, сервис фиксирует новую проверенную проекцию политики с исходным commit/хэшем и публикует событие для потребителей. |
| PROJ-AC-4 | Если пользователь меняет релизную политику по устаревшей версии, команда получает конфликт и должна перечитать актуальное состояние. |
| PROJ-AC-5 | Если репозиторий создан или подключён напрямую у провайдера, `provider-hub` создаёт или обновляет зеркало, а `project-catalog` остаётся владельцем проектной привязки и политики. |
| PROJ-AC-6 | Если runtime готовит рабочий контур, он получает состав источников из `project-catalog` и не читает чужие БД. |
| PROJ-AC-7 | Если bootstrap PR пустого репозитория слит и внутренний контур передал проверенный source ref/commit/content hash, повтор того же сигнала не создаёт вторую проекцию, а другой commit/ref после активации возвращает конфликт. |

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

- Не реализовывать GitHub/GitLab API операции внутри `project-catalog`.
- Не хранить зеркало `Issue`, `PR/MR`, комментариев и webhook.
- Не запускать агентов, слоты, сборку, deploy или миграции проектов.
- Не вычислять права доступа; для этого используется `access-manager`.
- Не проектировать полный UI управления проектами в этом документе.

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

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

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

| Зависимость | Зачем нужна |
|---|---|
| `access-manager` | Проверка прав на проект, репозиторий и политику. |
| `provider-hub` | Provider-native зеркало и операции создания/подключения репозитория. |
| `agent-manager` | Использует проектный контекст для flow, роли и follow-up задач. |
| `runtime-manager` | Получает состав рабочего контура и политику, но не владеет проектом. |
| `fleet-manager` | Предоставляет инфраструктурные контуры для политики размещения. |
| `risk-and-release-governance` | Использует релизные политики, релизную линию и правила веток для risk gates. |

## Апрув

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