Капстон‑интеграция: технико‑продуктовая демо и «паспорт App»

1. Что такое «паспорт App» и зачем он вам

Паспорт App — это компактный, но насыщенный документ (обычно 1–2 страницы Markdown или раздел в README), который даёт любому человеку быстрое представление о вашем ChatGPT App: как он устроен, какие у него ограничения, как он зарабатывает и как вы им управляете в продакшене.

Это не маркетинговая брошюра. В нём не про «самые инновационные AI‑технологии», а про очень приземлённые вещи:

• где проходит граница между ChatGPT, вашим виджетом, MCP‑сервером, агентами и ACP/Stripe;
• какие PII вы храните, как устроен OAuth/scopes и ротация секретов;
• какие у вас SLO по latency и availability, какие есть дашборды и алерты;
• сколько в среднем стоит один успешный сценарий и как вы берёте за него деньги;
• какие типичные инциденты уже описаны и где лежат runbook’и;
• что вы планируете делать с этим App в ближайшие месяцы.

Можно думать о паспорте как об агрегаторе ссылок и high‑level описаний, который меняется реже, чем код, но чаще, чем «официальная презентация для инвесторов».

Для вас как разработчика ChatGPT App паспорт — ещё и чек‑лист зрелости. Если какой‑то раздел пустой («а SLO мы как‑то не описали…»), это хороший красный флаг: значит, не только документации не хватает, но и самой практики.

2. Базовая структура паспорта GiftGenius

Для GiftGenius логично взять следующую структуру (вы можете слегка модифицировать её под свой App, но общая идея сохранится).

Представим в виде небольшой таблицы, кто что читает и зачем:

Дальше разберём каждый из этих блоков и параллельно будем набрасывать реальный PASSPORT.md для GiftGenius.

3. Архитектура: как показать весь стек на одной картинке

Архитектурный раздел — это сердце паспорта. Здесь не нужно рисовать UML‑диаграмму на 200 прямоугольников. Важно показать слои и потоки: от пользователя в ChatGPT до вашей БД и платёжки. Для ChatGPT App с Apps SDK и MCP этот путь стандартный.

Удобный формат — диаграмма Mermaid прямо внутри PASSPORT.md. Например, для GiftGenius:

flowchart TD
  U[User in ChatGPT] --> C[ChatGPT + GPT-5]
  C --> W[GiftGenius Widget
Next.js + Apps SDK]
  W --> MCP[MCP Server
giftgenius-mcp]
  MCP --> A[Agent: GiftPlanner]
  A --> DB[(Postgres: products,gifts)]
  A --> ACP[ACP / Stripe]
  ACP --> ORD[(Orders)]

В тексте под диаграммой вы описываете ключевой сценарий:

Пользователь в чате описывает получателя подарка. Модель решает вызвать tool suggest_gifts на MCP‑сервере. Агент может дополнительно читать каталоги как ресурсы и выполнять несколько tools. Затем при выборе подарка создаётся ACP‑сессия в Stripe, чекаут проходит через webhooks, а результат сохраняется в БД.

Хорошо, если вы тут же упоминаете технологии: Next.js 16 + Apps SDK, MCP‑сервер на Node/Python, PostgreSQL, Redis для кэша, Stripe как платёжка.

Можно добавить к архитектурному разделу мелкий технический фрагмент, чтобы было видно, как архитектурные кирпичики проявляются в коде. Например, кусочек Next.js‑роута, который прокидывает requestId и userId в MCP‑клиент:

// app/api/suggest-gifts/route.ts
import { mcpClient } from "@/lib/mcpClient";

export async function POST(req: Request) {
  const { occasion, budget } = await req.json();
  const requestId = crypto.randomUUID();      // трейс для логов
  const userId = req.headers.get("x-user-id") ?? "anonymous";

  const result = await mcpClient.callTool("suggest_gifts", {
    occasion, budget, requestId, userId,
  });

  return Response.json({ requestId, result });
}

Такой кусок помогает связать абстрактную стрелочку на диаграмме «Widget → MCP» с реальным кодом.

4. Security & Privacy: что именно нужно зафиксировать

Безопасность в паспорте — не про «мы используем HTTPS и бэкенд на TypeScript, так что всё нормально». Нужны конкретные ответы на вопросы безопасности, комплаенса и юридического блока.

Для GiftGenius стоит кратко описать:

Какая модель аутентификации и авторизации:
для commerce‑сценариев используется OAuth 2.1 с PKCE через MCP Auth Server; токен привязан к user_id и tenant_id, все tool‑вызовы, связанные с чекаутом, требуют scope commerce.checkout.

Какие данные являются PII и как вы с ними обходитесь.
Например: email и имя — PII, предпочтения по подаркам — псевдо‑анонимные данные; логируем только захешированный email, адрес доставки не храним, а только прокидываем в Stripe и вебхуки.

Как устроены retention и удаление:
логи инструментов храним 30 дней, события commerce — 1 год, по запросу пользователя можем удалить его заказы и связанные аналитические события.

Как вы управляете секретами:
кратко опишите, где лежат OpenAI API key, Stripe secret, OAuth client secret (например, в managed secret store), как часто вы их ротируете и как это тестируется на staging.

В паспорте можно дать маленький технико‑ориентированный фрагмент, чтобы продемонстрировать принцип «минимально необходимых прав».

// config/scopes.ts
export const TOOL_SCOPES = {
  suggest_gifts: ["read:products"],
  get_gift_details: ["read:products"],
  create_checkout_session: ["read:products", "write:orders", "stripe:checkout"],
} as const;

Дальше в описании инструмента и MCP‑auth вы ссылаетесь на эти же scopes. Это уже не просто слова про «least privilege», а конкретный контракт.

5. Observability и SLO: чтобы видеть, как App живёт

Следующий блок паспорта — про наблюдаемость: как вы понимаете, что App жив и здоров. Здесь объединяются структурированные логи, метрики, SLO и ссылки на дашборды.

Для GiftGenius логично описать:

Ключевые SLO.
Например: доступность MCP ≥ 99.5%, p95 latency для suggest_gifts < 5 секунд, success‑rate для checkout ≥ 99%.

Где смотреть на эти SLO.
Название и URL дашборда в Grafana/Datadog/… (в паспорте можно указать просто «Dashboard: GiftGenius / SLO»).

Формат структурированных логов.
В предыдущем модуле по наблюдаемости вы уже продумывали поля request_id, tool_name, user_id/tenant_id, tokens_in/tokens_out, cost_estimate, duration_ms, error_code. В паспорте полезно привести JSON‑пример (маленький), но мы ещё круче — оформим TypeScript‑тип, который используется и в коде.

// lib/logging.ts
export type ToolInvocationLog = {
  level: "info" | "error";
  timestamp: string;
  requestId: string;
  userId?: string;
  toolName: string;
  tokensIn?: number;
  tokensOut?: number;
  costEstimateUsd?: number;
};

И helper‑функцию:

export function logToolInvocation(event: ToolInvocationLog) {
  console.log(JSON.stringify({ type: "tool_invocation", ...event }));
}

Теперь этот тип становится мостом между кодом и паспортом: в разделе Observability вы пишете, что все tool‑вызовы логируются в формате ToolInvocationLog, и прикладываете ссылку на дашборд, который агрегирует эти записи.

Можно добавить короткую текстовую схему:

Лог события → лог‑хранилище → дашборды SLO → алерты → инцидент/Runbook.

6. Economics & Product Metrics: деньги и поведение пользователей

Здесь вы соединяете всё, что делали в предыдущем блоке про экономику (М19): cost‑метрики, pricing и продуктовую аналитику.

Для GiftGenius в паспорте стоит закрепить:

Unit‑экономику ключевого сценария (условно, «экономика одной законченной задачи»).
Например: «Средний cost_per_successful_task (подбор подарка с успешной оплатой) = $0.13 (LLM + infra). Средняя выручка per task = $0.80 (CPA от партнёров).»

Основную модель монетизации.
Кратко: «Бесплатный базовый подбор без покупки, монетизация через CPA за переход в магазин‑партнёр + опциональная premium‑подписка с расширенными фильтрами и историей подарков».

Ключевые продуктовые метрики.
Например: activation‑rate = доля пользователей, у которых был хотя бы один workflow_completed; repeat‑rate = доля пользователей, вернувшихся хотя бы раз за месяц; conversion workflow_completed → checkout_success.

Эксперименты.
Список активных A/B: «Модель A (дорогая) vs модель B (дешёвая)», «Длинный мастер vs быстрый inline». Для каждого вы храните experiment_id, варианты, таргет‑метрики (конверсия, cost_per_task, quality‑score).

В коде это тоже можно проявить, чтобы паспорт не оставался теорией, например, через единый helper для аналитических событий:

// lib/analytics.ts
export function trackEvent(
  name: string,
  payload: Record<string, unknown>,
) {
  console.log(JSON.stringify({
    type: "analytics",
    name,
    ts: new Date().toISOString(),
    ...payload,
  }));
}

И вызов при успешном завершении workflow:

trackEvent("workflow_completed", {
  userId,
  requestId,
  experimentId: "model_ab_01",
  variant: "A",
  costUsd: 0.13,
  checkoutSuccess: true,
});

В паспорте вы описываете, какие события являются ключевыми и какие KPI на них завязаны. Код — это доказательство, что вы действительно что‑то измеряете, а не просто обещаете.

Но метрики и экономика имеют смысл только тогда, когда App стабильно работает в продакшене. Поэтому в следующем разделе мы посмотрим, как зафиксировать в паспорте операционную сторону жизни GiftGenius: инциденты, on‑call и runbook’и.

7. Ops & Incidents: как вы будете жить с App в продакшене

Этот раздел — про то, как вы реагируете, когда всё идёт не по плану.

Для GiftGenius имеет смысл в паспорте перечислить хотя бы два типичных инцидента:

Проблемы с оплатой.
Например: падение success‑rate checkout ниже SLO, массовые ошибки Stripe webhooks. В паспорте вы пишете, что на это заведен runbook «Checkout Failures», где описаны симптомы, где смотреть (дашборд ошибок, логи webhook‑эндпойнта), быстрые шаги mitigation (временные меры: отключить проблемный feature‑flag, перевести часть трафика в sandbox или временно предлагать только сертификаты) и follow‑up (post‑mortem, добавление новых алертов).

Проблемы с MCP/LLM.
Например: рост p95 latency для suggest_gifts до 9 секунд или ошибка «Error talking to app» для большого процента запросов. Здесь отдельный runbook: проверка статуса OpenAI, туннеля/Vercel, health‑check MCP, переключение на деградированный режим, в котором агент пробует отвечать без доступа к каталогу (общие идеи из модели, без commerce).

В этом же разделе вы коротко описываете операционный календарь: как часто вы пересматриваете SLO, делаете cost‑review, проверяете security‑логи и ротируете секреты.

Тут же можно добавить, кто on‑call (даже если это один человек — вы), и в какой Slack‑канал или на какую почту летят алерты.

8. Roadmap & Risks: честный взгляд вперёд

Финальный блок паспорта — о будущем. Здесь не нужно писать роман. Достаточно 3–5 реальных шагов развития App и несколько известных ограничений.

Для GiftGenius это может выглядеть так:

• запуск LLM‑оценок (LLM‑evals) для качества подборов, чтобы связать качество с конверсией;
• добавление ещё одной локали и тестирование локализованных описаний инструментов;
• эксперимент с более дешёвыми моделями на части трафика;
• улучшение resilience к сбоям Stripe (надёжнее обрабатывать вебхуки и отложенные подтверждения);
• подготовка к миграции на новую версию Apps SDK или MCP (с версионированием контрактов инструментов).

Ограничения: капы API, лимиты ChatGPT UI (например, ограничение на количество карточек в выдаче), слабые места текущей архитектуры (single‑region БД, отсутствие горячего резерва MCP и т.п.).

План по экспериментам: какие гипотезы вы собираетесь проверять по pricing/UX/моделям и через какие метрики будете принимать решения.

9. Где жить паспорту и как его обновлять

На практике самый удобный формат — PASSPORT.md в корне репозитория GiftGenius или в папке docs/, а также копия/ссылка в вашей документационной системе (Confluence, Notion и т.п.).

Он должен быть достаточно лёгким, чтобы его можно было прочитать за 10–15 минут, и достаточно плотным, чтобы по нему можно было ответить на вопросы:

• «что это вообще за App, как он устроен?»
• «что будет, если упадёт X?»
• «во сколько нам обходится один пользователь?»
• «какие риски нас сейчас больше всего беспокоят?».

Обновлять паспорт стоит при изменении:

• архитектурных границ (новый сервис, новая платёжка, миграция на другой стэк);
• ключевых SLO или политики безопасности (например, другая retention);
• модели монетизации;
• значимых инцидентов и выводов из post‑mortem’ов.

Мелкие изменения кода не требуют немедленной правки паспорта, иначе он превратится в ещё один устаревающий документ.

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

10. Технико‑продуктовая демо: почему нужно две «версии рассказа»

Когда вы показываете GiftGenius, вы почти всегда выступаете перед двумя типами аудитории (иногда они смешаны в одной комнате):

• технарями (CTO, архитекторы, security, лиды разработки);
• продукт/бизнес‑аудиторией (CEO, инвесторы, продакты, маркетинг).

Техническому человеку важно, что:

• архитектура понятна, слои разделены, есть точки расширения;
• надёжность и наблюдаемость продуманы: логи, трейсинг, SLO, алерты;
• есть история про resilience: что будет, если упадёт OpenAI, MCP, Stripe;
• как вы планируете эволюцию (миграция SDK/МCP/моделей).

Бизнесу важнее другое:

• какая у пользователя боль (например, «поиск подарка занимает 40 минут»);
• как GiftGenius эту боль решает в рамках ChatGPT за несколько минут;
• какая у вас монетизация, unit‑экономика и метрики роста;
• снизит ли это стоимость привлечения клиента, увеличит ли конверсию/выручку.

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

11. Сценарий технического демо GiftGenius (5–7 минут)

Представим, что вы презентуете GiftGenius перед технической аудиторией.

Сначала короткий контекст.
Буквально 30 секунд: «GiftGenius — ChatGPT App для подбора подарков с ACP‑чекаутом. Мы живём внутри ChatGPT, используем Apps SDK, MCP и агента для планирования шагов.»

Затем архитектурный слайд/фрагмент из паспорта.
Вы открываете диаграмму, похожую на ту, что мы написали в Mermaid, и объясняете, где граница ответственности ChatGPT (LLM‑часть), где ваш виджет, где MCP и где commerce‑слой со Stripe. Здесь полезно показать, что все tool’ы инкапсулированы в MCP, а виджет — тонкий слой UI.

Live‑демо с логами.
Дальше вы включаете split‑screen: слева — ChatGPT с GiftGenius, справа — логи или MCP Inspector. Делаете естественный запрос вроде «подбери подарок для геймера до 50$». По ходу исполнения вы показываете:

• tool‑вызов suggest_gifts с request_id;
• структурированный лог tool_invocation, где видно tokens, cost_estimate и duration_ms;
• вторичный tool, который заводит ACP‑сессию и создаёт заказ.

Здорово, если вы можете сразу ткнуть в дашборд: «а вот p95 latency этого сценария за последние сутки, вот success‑rate checkout». Это момент, когда технарь понимает, что это не pet‑project, а система с наблюдаемостью (observability).

Failure‑injection (опционально, но очень эффектно).
Если вы достаточно уверены в системе (или заранее приготовили сценарий), можно временно отключить, скажем, доступ к каталогу (БД) и повторить запрос. Вы показываете, что:

• MCP корректно логирует ошибку и срабатывает алерт;
• агент переходит в деградированный режим и честно говорит пользователю, что каталог недоступен, но может выдать generic‑идеи;
• checkout в таком режиме недоступен.

В конце — кратко про эксплуатацию и эволюцию.
Заканчиваете слайдом из паспорта с SLO, инцидентами и roadmap: какие у вас целевые показатели, как вы их мониторите, какие инциденты уже разобраны runbook’ами, что будет в v2 (масштабирование, новые модели, новые рынки).

Главный сигнал для аудитории: у вас не просто красивый UI, а продуманная платформа, готовая к жизни в проде.

12. Сценарий продуктового демо (бизнес‑ракурс)

Теперь тот же GiftGenius, но вы рассказываете его как продукт.

Начинаете с истории пользователя.
Например: «У нас есть Катя, ей нужно за вечер выбрать подарок коллеге. Обычно она тратит на это 30–40 минут по сайтам магазинов».

Показываете ChatGPT с GiftGenius.
Катя пишет живую фразу, а не кликает по фильтрам в маркетплейсе: «подбери подарок коллеге, который любит настольные игры, бюджет до 50$». ChatGPT объясняет, что может использовать GiftGenius, и открывает widget. GiftGenius уточняет пару деталей и показывает список вариантов.

Переходите к результату и ценности.
Показываете карточки подарков, возможность сохранить или сразу перейти к покупке, чекаут через ACP/Stripe. Важно произнести: «всё это занимает 3–5 минут, причём в том месте, где пользователь и так проводит время — в ChatGPT».

Затем 1–2 минуты про монетизацию и метрики.
Вы объясняете, что зарабатываете на CPA или комиссии с магазинов, возможно, предлагаете премиум‑режим для частых пользователей. Ссылаетесь на цифры из паспорта: сколько стоит один успешный сценарий, какова конверсия в покупку и какой запас маржи заложен.

Дальше — немного про рост.
Рассказываете, как планируете приводить пользователей: через Store‑листинг в ChatGPT, контент, партнёрские интеграции. Но всё привязываете к продуктовым метрикам: «мы смотрим, как изменение листинга влияет на число новых app_opened и activation‑rate; как статьи и видео влияют на retention и долю пользователей с более чем одним workflow_completed».

Завершаете рисками и планом.
Честно говорите про текущие ограничения (например, что вы зависите от лимитов OpenAI/Stripe, что пока слабая поддержка локалей), и показываете roadmap: какие эксперименты и улучшения в pipeline.

Если всё сделать аккуратно, бизнес‑аудитория увидит не только «ещё один AI‑виджет», а понятный продукт с экономикой и планом роста.

13. Практика: собираем свой паспорт и демо вокруг GiftGenius

В качестве практики к этой лекции вы можете прямо в своём репозитории GiftGenius завести файл PASSPORT.md и заполнить его минимум по пяти блокам: архитектура, безопасность, observability/SLO, экономика и продуктовые метрики, инциденты/операции. Как только вы допишите новый runbook или измените SLO, возвращайтесь в паспорт и отражайте это изменение.

Параллельно имеет смысл написать себе конспект демо на 5–7 минут: первые 2–3 минуты — пользовательский сценарий и ценность, следующие 2–3 — архитектура и эксплуатация (SLO, cost, инциденты). Такой конспект отлично тренирует умение говорить на языке и бизнеса, и техники, не скатываясь ни в сухой код, ни в голый маркетинг.

Эти артефакты — не «бумажка для галочки», а основа финальной капстон‑демо. Именно по этому паспорту и сценарию вы потом будете защищать свой App перед условными CTO/CEO.

14. Типичные ошибки при подготовке паспорта и демо

Ошибка №1: превратить паспорт в маркетинговый буклет.
Иногда паспорт начинает походить на лендинг: много общих слов про «инновационный AI», мало конкретики про архитектуру, SLO, cost и инциденты. Такой документ никому не помогает: технарь не понимает, как это живёт внутри, а бизнес не видит, что вы контролируете риски. В паспорте должны быть факты, схемы, метрики и ссылки.

Ошибка №2: описывать только код, а не потоки данных и ответственности.
Популярный перекос у разработчиков — перечислить все сервисы, библиотеки и фреймворки, забыв про высокоуровневую схему «пользователь → ChatGPT → виджет → MCP → агенты → ACP/БД». В результате новый человек не понимает, где чьи обязанности и где проходят границы. В архитектурном разделе важнее data flow и слои, а не названия всех npm‑пакетов.

Ошибка №3: не связать passport с observability и cost‑инструментацией.
Бывает, что в паспорте гордо написано «у нас есть SLO», но нигде не видно, как они измеряются, где логи и какие именно поля пишутся в JSON‑события. Или написано, что «LLM‑cost под контролем», но нет ни одной метрики cost_per_task. Чем меньше связь с реальными логами, метриками и дашбордами, тем больше вероятность, что SLO и cost живут только в Google Docs, а не в системе мониторинга.

Ошибка №4: демо только про красивый UI, без архитектуры и отказоустойчивости.
Лёгко скатиться в шоу: «смотрите, какие классные карточки подарков». Техническая аудитория в этот момент думает: «а что будет, если Stripe упадёт?», «как вы логируете tool‑вызовы?», «можно ли это масштабировать?». Если в демо не показать хотя бы одну‑две истории про логи, SLO и инциденты, у технарей останется ощущение игрушки, а не продукта.

Ошибка №5: демо только для технарей, без истории пользователя и экономики.
Обратный перекос: 10 минут обсуждаем p95 latency, MCP‑handshake и JSON Schema инструментов, но ни разу не произнесли, какую боль пользователя решаем, кто платит и сколько стоит один сценарий. Для бизнеса и продакта это выглядит как «крутая инженерная штука без бизнес‑кейса». Старайтесь всегда держать в голове минимум две шляпы: инженера и продукт‑менеджера.

Ошибка №6: паспорт и демо расходятся.
Иногда в паспорте одно, а в демо — другое: в документе обещаны одни SLO, а на дашбордах — другие; в паспорте три инцидента с runbook’ами, а в живой презентации при первом же сбое все хватаются за голову. Постарайтесь использовать паспорт как сценарий для демо: ссылаться на те же SLO, те же дашборды, те же runbook’и. Тогда у слушателя возникает ощущение цельной системы, а не набора случайных артефактов.

Ошибка №7: относиться к паспорту как к одноразовой курсовой.
Самая большая ловушка — написать PASSPORT.md для сдачи модуля и забыть про него. В реальной жизни как раз такие документы и превращают команду в зоопарк вынесенных в голову знаний. Старайтесь относиться к паспорту как к живой части кода: пусть он меняется при серьёзных архитектурных, операционных или бизнес‑решениях. Тогда через пару месяцев вы сами скажете себе спасибо.