Документация АПИ Project+apps

API Project+apps принимает управленческий слой целиком: core-объекты портфеля, канон и summary-сущности. Сырые события, установки, отзывы, логи и выгрузки рекламных кабинетов сюда не отправляются.

Подключение

Для локальной разработки используем http://127.0.0.1:8010. Публичный прод-контур живёт на https://apps.farmchel.org. MCP и API должны подключаться к тому контуру, в котором реально запущено приложение.

Accept: application/json
Content-Type: application/json
X-Project-Apps-Token: <выданный токен>

Контракт для агентов

Правильная модель интеграции для внешних агентов: MCP для чтения, API для записи.

• Через MCP агент читает контекст системы, канон, карту портфеля и ищет существующие продукты.
• Через API агент создаёт и обновляет продукты, приложения, решения, задачи и канонические правила.
• Через API агент также пишет summary-слой: signals, insights, economics.
• Перед записью агент должен сначала читать /api/project-apps/directions или ресурс project-apps://portfolio, чтобы использовать только допустимые direction_slug.
• Перед записью агент должен проверить через MCP или API, существует ли объект, чтобы не создавать дубль.
• Для продуктов опорный идентификатор — slug.
• Для приложений опорный идентификатор — slug, bundle_id, package_id и store_url.
• Для одной и той же platform не допускаются два приложения с одинаковым непустым bundle_id или package_id — сервер вернёт 422.

Модель портфеля

Project+apps выражает мобильный контур по слоям: направление → продукт → приложение.

• Направление — управленческий контур и общий рынок/тезис.
• Продукт — самостоятельный продуктовый смысл со своим фокусом, решениями и economics.
• Приложение — реализация продукта или временный хвост направления, если продукт ещё не подтверждён.

Канонический перечень направлений Farmchel

Эталонные direction_slug для мобильного портфеля (строки в БД могут включать и демо-направления вроде watches или sales-support):

utilities, documents, documents-qr, parental-family-safety, fitness, fitness-cognitive, wellness-habit-change, wellness-mental, lifestyle-content, wellness-lifestyle, security-privacy

Генерация API-токенов

Токен выдаётся каждому API-агенту, который пишет управленческий слой в Project+apps. Реальные токены нельзя хранить в git, README, задачах, скриншотах или публичной документации.

1. Сгенерировать токен

php artisan project-apps:token metrika-agent

Команда выведет безопасное значение вида pa_... и готовую строку для окружения.

2. Подключить одного агента

PROJECT_APPS_INGEST_TOKEN=pa_сгенерированный_токен

3. Подключить несколько агентов

PROJECT_APPS_INGEST_TOKENS=pa_токен_метрики,pa_токен_финансов,pa_токен_store

4. Передавать токен в каждом запросе

X-Project-Apps-Token: pa_сгенерированный_токен

• Для каждого внешнего API-агента лучше выдавать отдельный токен.
• При компрометации удалите старый токен из PROJECT_APPS_INGEST_TOKENS, сгенерируйте новый и перезапустите приложение.
• После изменения токенов очистите конфиг, если он кешировался: php artisan config:clear.
• MCP endpoint остаётся отдельным каналом чтения контекста; входящие API-записи от агентов принимаются только через токен.

Эндпоинты

Коды ответов

• 200 — read endpoint или update endpoint успешно отработал.
• 201 — сигнал, инсайт, экономика, продукт, приложение, решение, задача или каноническое правило созданы.
• 403 — неверный или отсутствующий X-Project-Apps-Token.
• 422 — payload не прошёл валидацию.
• 503 — токен API не настроен на стороне сервера: не заполнены PROJECT_APPS_INGEST_TOKEN или PROJECT_APPS_INGEST_TOKENS.

Как агенту узнать допустимые направления

GET http://127.0.0.1:8010/api/project-apps/directions
X-Project-Apps-Token: <выданный токен>

Список продуктов (поиск перед записью)

GET http://127.0.0.1:8010/api/project-apps/products?direction_slug=fitness&portfolio_status=core&is_favorite=1&limit=25
X-Project-Apps-Token: <выданный токен>

Основные query-параметры

• slug — точный slug продукта.
• direction_slug — фильтр по направлению.
• name — подстрока в названии.
• portfolio_status — core, next, rebuild, freeze.
• is_favorite — 1 / 0 или boolean: только избранные в админке.
• limit — максимум записей (по умолчанию до 25).

Получить сводку портфеля

GET http://127.0.0.1:8010/api/project-apps/summary
X-Project-Apps-Token: <выданный токен>

Фрагмент ответа

{
  "message": "Сводка Project+apps без сырой первички.",
  "portfolio": {
    "health": "Требует внимания",
    "directions_count": 4,
    "products_count": 9,
    "apps_count": 7,
    "critical_problems": 1,
    "key_growth_points": 2
  },
  "need_attention": [
    {
      "title": "Раскрыть внутреннюю карту часов",
      "severity": "high",
      "recommended_action": "Уточнить приложения, выплаты и store-подтверждение."
    }
  ],
  "canon": [
    {
      "title": "Что считать отдельным продуктом",
      "type": "Критерий продукта"
    }
  ]
}

Пример сигнала

POST http://127.0.0.1:8010/api/project-apps/signals
X-Project-Apps-Token: <выданный токен>

{
  "product_slug": "push-ups",
  "signal_type": "problem",
  "source_layer": "metrika",
  "severity": "high",
  "status": "open",
  "title": "Удержание второй вариации ниже ожидания",
  "body": "В сводке поведения видно, что пользователи быстрее бросают тренировочный сценарий.",
  "recommended_action": "Сравнить onboarding двух вариаций и вынести решение по продуктовой гипотезе."
}

Обязательные поля

• signal_type: growth, problem, risk или opportunity.
• source_layer: источник summary-сигнала, например metrika, store, acquisition, finance.
• severity: low, medium, high или critical.
• title и хотя бы одно из body / recommended_action: управленческий смысл, а не сырой лог.

Пример инсайта

POST http://127.0.0.1:8010/api/project-apps/insights
X-Project-Apps-Token: <выданный токен>

{
  "product_slug": "push-ups",
  "source_layer": "metrika",
  "confidence_level": "medium",
  "impact_level": "high",
  "title": "Вторая вариация отжиманий слабее удерживает пользователя",
  "body": "После onboarding пользователи чаще обрывают тренировочный сценарий. Поведенческая summary показывает разницу между вариациями без передачи сырых событий.",
  "discovered_at": "2026-04-08"
}

Пример экономической сводки

POST http://127.0.0.1:8010/api/project-apps/economics
X-Project-Apps-Token: <выданный токен>

{
  "product_slug": "push-ups",
  "economics_status": "unconfirmed",
  "confidence_level": "medium",
  "title": "Отжимания: сводка экономики за период",
  "period_start": "2026-04-01",
  "period_end": "2026-04-08",
  "acquisition_summary": "Стоимость установки требует проверки по качеству трафика.",
  "behavior_summary": "Поведение отличается между вариациями.",
  "store_confirmation_summary": "Нужны рейтинг, отзывы и выплаты.",
  "roi_summary": "Рентабельность пока не подтверждена.",
  "conclusion": "Не масштабировать без подтверждения магазина приложений."
}

Создать продукт

POST http://127.0.0.1:8010/api/project-apps/products
X-Project-Apps-Token: <выданный токен>

{
  "direction_slug": "fitness",
  "name": "Бег",
  "portfolio_status": "next",
  "product_focus": "assess-development",
  "summary": "Кандидат в новый фитнес-продукт.",
  "is_revenue_generating": false,
  "is_favorite": true,
  "monetization_model": "Пока не подтверждена",
  "health_state": "На проверке",
  "risk_summary": "Не собрана app map и economics.",
  "growth_chance": "Есть соседний спрос внутри фитнес-контура.",
  "next_step": "Проверить app map и economics."
}

Обязательные поля

• direction_id или direction_slug.
• name.
• portfolio_status: core, next, rebuild, freeze.

Фокус продукта

• increase-monetization — усиливать монетизацию.
• rewrite — переписывать.
• assess-development — оценивать разработку.
• scale — масштабировать.
• leave-as-is — не трогать.

Обновить продукт

PATCH http://127.0.0.1:8010/api/project-apps/products/{product}
X-Project-Apps-Token: <выданный токен>

{
  "portfolio_status": "core",
  "product_focus": "scale",
  "is_revenue_generating": true,
  "is_favorite": true,
  "monetization_model": "Подписка",
  "health_state": "Стабильный рост",
  "health_summary": "Экономика подтверждена, продукт можно усиливать.",
  "next_step": "Подтвердить план роста и store map."
}

Записать решение

POST http://127.0.0.1:8010/api/project-apps/decisions
X-Project-Apps-Token: <выданный токен>

{
  "product_slug": "push-ups",
  "title": "Масштабировать после подтверждения stores",
  "decision_type": "scale",
  "owner": "Growth",
  "decision": "Не масштабировать без store truth.",
  "rationale": "Требуются точные названия и подтверждение выплат.",
  "review_at": "2026-04-30",
  "tasks": [
    {
      "title": "Проверить store truth по Отжиманиям",
      "owner": "Growth",
      "priority": "high"
    }
  ]
}

Типы решений

• focus
• scale
• stop
• retest
• positioning
• investment

Создать приложение

POST http://127.0.0.1:8010/api/project-apps/apps
X-Project-Apps-Token: <выданный токен>

{
  "product_slug": "push-ups",
  "name": "Отжимания Android",
  "platform": "Android",
  "implementation_status": "building",
  "store_url": "https://play.google.com/store/apps/details?id=org.farmchel.pushups.android",
  "bundle_id": "org.farmchel.pushups.android",
  "package_id": "org.farmchel.pushups.android"
}

Спорный хвост без подтверждённого продукта

{
  "direction_slug": "fitness",
  "name": "Quit Alcohol Android",
  "platform": "Android",
  "implementation_status": "building",
  "product_binding_status": "product-candidate",
  "product_candidate_name": "Quit Alcohol",
  "package_id": "org.farmchel.quit.alcohol",
  "portfolio_note": "Пока неясно, это отдельный продукт или приложение существующего продукта."
}

• confirmed — приложение уже связано с подтверждённым продуктом.
• needs-product — приложение точно живёт в направлении, но продукт ещё не оформлен.
• product-candidate — приложение может оказаться отдельным продуктом после проверки.

Создать задачу

POST http://127.0.0.1:8010/api/project-apps/tasks
X-Project-Apps-Token: <выданный токен>

{
  "product_slug": "push-ups",
  "product_decision_id": 12,
  "title": "Собрать store links по Отжиманиям",
  "owner": "Operations",
  "status": "open",
  "priority": "high",
  "due_at": "2026-04-20"
}

Статусы задачи

• open
• in-progress
• blocked
• done

Создать каноническое правило

POST http://127.0.0.1:8010/api/project-apps/canon-rules
X-Project-Apps-Token: <выданный токен>

{
  "title": "Один продукт может иметь несколько приложений",
  "rule_type": "product-definition",
  "body": "Продукт не равен одному приложению, если смысл общий и решения принимаются на уровне продукта."
}

Прочитать канон

GET http://127.0.0.1:8010/api/project-apps/canon-rules?status=active
X-Project-Apps-Token: <выданный токен>

{
  "message": "Канонические правила Project+apps.",
  "rules": [
    {
      "title": "Что считать отдельным продуктом",
      "rule_type": "product-definition",
      "status": "active"
    }
  ]
}

Что не отправлять

• Сырые события аналитики и клики пользователей.
• Сырые установки, показы, поисковые таблицы и рекламные выгрузки.
• Сырые отзывы, store dumps и технические логи.
• Данные, по которым нельзя сразу принять продуктовый вывод или решение.