Бизнес-логика Project+apps

Project+apps — продуктовый штаб мобильного портфеля Farmchel: направления, продукты, приложения, гипотезы, инсайты, решения, задачи, сводные сигналы и экономика, канон и токены для агентов. Это не каталог сторов «ради списка», не техническая админка нижнего уровня и не хранилище сырых логов.

1. Назначение и границы

Внутри Project+apps фиксируется управленческий смысл: что считается отдельным продуктом, как живёт портфель, какие решения приняты, что требует внимания и какая экономика подтверждена на уровне выводов, а не таблиц.

Снаружи остаются первичные источники: рекламные кабинеты, выгрузки сторов, сырые события, длинные таблицы конкурентов и поисковых позиций. В штаб попадает только то, что уже свёрнуто в summary: источник, период, связь с продуктом или приложением, уверенность, вывод и рекомендуемое действие.

Третья граница — канал записи. Публичный HTTP API закрыт токеном и предназначен для агентов и интеграций. Часть сущностей (например рыночный и store-слой ниже) ведётся прежде всего через админку Filament; отдельные массовые write-эндпоинты для них в открытом API могут отсутствовать намеренно.

2. Главная цепочка чтения

Опорный порядок осмысления портфеля:

Направление → Продукт → Приложение → Гипотеза → Инсайт → Решение → Задача.

Параллельно на уровне продукта и направления живут сигналы (точки роста, проблемы, риски) и экономические сводки за периоды — это не «ещё одна таблица», а управленческий слой вокруг тех же объектов.

• Направление — стратегический контур: тезис, портфельный слой, комментарии руководства. Эталонные slug мобильного контура задаются справочником Farmchel; в базе могут быть служебные или демо-направления.
• Продукт — самостоятельный продуктовый смысл: портфельный статус, фокус, здоровье, монетизация, следующий шаг. Один продукт может иметь несколько приложений (платформы и вариации одного смысла).
• Приложение — конкретная публикация в сторе: платформа, идентификаторы, статус реализации. Может быть привязано только к направлению, пока продукт не подтверждён.
• Гипотеза, инсайт, решение, задача — цепочка от проверки к действию; задачи могут порождаться из решений.

3. Слои данных: core, summary и рынок

Удобно держать в голове три слоя.

• Core портфеля — направления, продукты, приложения, гипотезы, решения, задачи, канон, токены API-агентов. Это «скелет» штаба и опорные справочники.
• Summary-слой — сигналы, инсайты, экономика: всё, что приходит из нижних систем как переработанный смысл, а не как сырой поток.
• Рынок и магазины (market / store) — конкуренты, паттерны отзывов о конкурентах, позиции по ключам, «истины стора» по приложению. Эти сущности поддерживают управленческую картину и обычно ведутся в админке; публичный write-контракт агента по умолчанию ориентирован на core и summary.

4. Продукт, приложение и избранное

• Портфельный статус, экономика и «что делать дальше» ведутся на уровне продукта, а не одной страницы приложения в сторе.
• Дедупликация: у продукта опорный идентификатор — slug; у приложения — slug и связка платформа + bundle_id / package_id, плюс при необходимости store_url.
• Избранное — флаг продукта в админке: в списке продуктов можно отметить «звёздочкой» приоритетный контур для ежедневной работы. По умолчанию таблица может показывать только избранные; чтобы увидеть весь портфель, переключите фильтр «Избранное» на «Все продукты». Через API поле is_favorite доступно в ответах и при создании/обновлении продукта.

Статусы привязки приложения к продукту

Для кандидатов используются поля кандидата и управленческие заметки, чтобы не плодить фиктивные продукты до зрелости решения.

5. Канон портфеля

Канон — долговременные правила: что считать отдельным продуктом, как замораживать линии, как читать структуру портфеля, политики направлений и контракт summary-слоя. Правило может быть привязано ко всему портфелю, к направлению и/или к продукту с учётом области действия в данных.

Типы правил включают, среди прочего, product-definition, portfolio-structure, freeze-policy, direction-policy, summary-contract, portfolio-governance.

6. Люди, API и MCP

• Filament (админка) — ручное ведение справочников, канона, карточек портфеля, рыночного слоя, избранного и токенов API-агентов.
• HTTP API (https://apps.farmchel.org/api/project-apps/...) — основной машинный канал записи для агентов: продукты, приложения, решения, задачи, канон, сигналы, инсайты, экономика — по заголовку X-Project-Apps-Token. Чтение списков направлений и продуктов перед записью обязательно, чтобы не ломать допустимые direction_slug и не плодить дубли.
• MCP — контекст, обзор портфеля, внимание, канон, поиск продуктов; опционально те же write-tools, что и через API. Если на сервере задано PROJECT_APPS_MCP_WRITE_ENABLED=false, MCP регистрирует только инструменты чтения: запись выполняется только через HTTP API.

Промпт project_apps_director_brief в MCP собирает краткий директорский бриф из сводки и блока внимания.

7. Операции над данными и консистентность

• Синхронизация направлений — миграции и справочник Farmchel выравнивают эталонные направления по slug.
• Перенос с legacy-направления — команда php artisan project-apps:reconcile-legacy-directions с картой slug → slug в конфиге или переменной окружения; перед применением используйте --dry-run.
• Идентичность в сторах — уникальность связки платформа + bundle/package поддерживается на уровне данных и валидации при записи.

8. Принципы ведения

• Не создавать второй продукт с тем же смыслом, если достаточно второго приложения у существующего продукта.
• Не превращать одно спорное приложение в продукт без решения: статус кандидата и работа через направление.
• Не смешивать summary-слой с сырыми выгрузками: штаб остаётся читаемым для управления.
• Перед автоматической записью из интеграций — проверять существующие продукты и приложения через GET API, чтобы выбирать PATCH вместо лишнего POST.

Локальный контур: http://127.0.0.1:8010 · Прод: https://apps.farmchel.org