Fase 02 — Product Discovery
HITLs #2-#6 Aprovados PO + Designer + PM

Fase 02 — Product Discovery

Priorização de oportunidades, hipóteses de solução, protótipos, backlog estruturado e avaliação de riscos.

Personas Sintéticas

3 personas representando os usuários do gateway de pagamentos. Construídas com base nos papéis de integração, operação e gestão do ecossistema ECP.

P-01 — Persona Primária (MVP)
Diego Moreira, 29 anos — Dev Full-Stack do Ecossistema ECP

Papel: Desenvolvedor integrador | Apps: ecp-bank, ecp-food | Experiência: 5 anos TypeScript

Contexto: Precisa integrar pagamentos (Pix, cartão, boleto) em cada app do ecossistema. Hoje reimplementa a integração com o Asaas em cada projeto separadamente. Testes dependem de sandbox instável do gateway externo.

Frustrações: Retrabalho a cada novo app. Sandbox do Asaas falha e trava o desenvolvimento. Não tem ambiente de staging determinístico. Documentação espalhada em múltiplos sistemas.

Objetivos: API única com contrato estável. Modo internal para testes sem dependência externa. Onboarding em horas, não semanas.

“Cada vez que crio um app novo no ecossistema, eu reimplemento toda a integração com pagamento do zero. Se tivesse uma API centralizada, eu faria a integração em 1 dia em vez de 1 semana.”

Oportunidades: OPP-01, OPP-02, OPP-10, OPP-12 | KRs: KR-01, KR-03, KR-04

P-02 — Persona Primária (MVP)
Patricia Lopes, 33 anos — Operadora do Ecossistema / DevOps

Papel: Operações e suporte | Foco: Monitorar transações, investigar falhas | Experiência: 4 anos em ops fintech

Contexto: Responsável por garantir que pagamentos do ecossistema fluam sem problemas. Investiga falhas de transação, reprocessa webhooks e gerencia o provider ativo (internal vs Asaas).

Frustrações: Para investigar uma falha, precisa acessar logs em 3 sistemas diferentes. Não tem visão unificada do ciclo de vida de uma transação. Sem retry manual de webhooks — precisa de intervenção técnica.

Objetivos: Dashboard unificado com KPIs do ecossistema. Timeline completa de cada transação. Retry de webhook com um clique. Alertas de falha em tempo real.

“Quando uma transação falha, eu levo 2 horas pra investigar porque preciso cruzar logs do app, do gateway e dos webhooks. Se tivesse tudo numa timeline, levaria 5 minutos.”

Oportunidades: OPP-06, OPP-13, OPP-14 | KRs: KR-02, KR-05

P-03 — Persona Secundária (Ciclo 2)
Ricardo Tavares, 35 anos — Product Owner / Gestor do Ecossistema

Papel: Gestão de produto | Foco: Visão estratégica, métricas, custos | Experiência: 8 anos em produtos digitais

Contexto: Toma decisões sobre provider (interno vs Asaas), monitora volume de transações e custos. Precisa de visão consolidada do ecossistema para planejar evoluções.

Frustrações: Não tem visão do volume de transações por app. Não sabe quanto custa cada transação real vs simulada. Sem auditoria de quem fez o quê no painel admin.

Objetivos: Dashboard com métricas do ecossistema. Auditoria completa de ações. Controle de provider com histórico de switches.

“Eu preciso saber exatamente quantas transações reais vs simuladas passam pelo gateway, qual o volume por app, e quanto estou pagando de taxa ao Asaas. Hoje eu não tenho nenhuma dessas visões.”

Oportunidades: OPP-06, OPP-08, OPP-09 | KRs: KR-02, KR-05

Insights Principais

6 insights extraídos da análise do ecossistema ECP, benchmarks de gateways (Stripe, Adyen, PagSeguro) e dores operacionais reais.

INS-01 — Confiança alta
Reimplementar integração de pagamento em cada app é o maior gargalo de velocidade
Cada novo app no ecossistema gasta 1–2 semanas integrando com gateway. Uma API unificada com contrato estável reduz esse tempo para horas. O Provider Pattern permite que apps não saibam qual gateway está ativo.
INS-02 — Confiança alta
Dependência de sandbox externo trava o ciclo de desenvolvimento
Sandbox do Asaas falha intermitentemente. Testes de pagamento ficam indeterminísticos. Modo Internal com simulação determinística elimina 100% da dependência externa em dev/staging.
INS-03 — Confiança alta
Investigação de falhas exige cruzar dados em múltiplos sistemas
Operadores precisam acessar logs do app, gateway e banco para investigar uma falha. TransactionTimeline unificada (request → gateway → webhook → callback) reduz investigação de horas para minutos.
INS-04 — Confiança alta
Retries sem idempotência causam cobranças duplicadas
Falhas de rede em produção levam apps a reenviar requests. Sem idempotency_key, o gateway cria transações duplicadas. Padrão Stripe: X-Idempotency-Key obrigatório + UNIQUE constraint no banco.
INS-05 — Confiança média
Webhooks não entregues silenciosamente comprometem a confiabilidade
Quando um callback falha, apps downstream ficam com status desatualizado. Retry automático com backoff exponencial + retry manual via painel admin garante entrega eventual.
INS-06 — Confiança média
Painel admin density-first (inspiração Stripe) é o padrão para ferramentas operacionais
Operadores de pagamento precisam de densidade de informação, não de estética consumer. Dashboards Stripe/Datadog são a referência: filtros poderosos, tabelas densas, detalhes expansíveis, timeline correlacionada.

Oportunidades Priorizadas (WSJF)

9 oportunidades selecionadas para discovery, organizadas em 3 pilares estratégicos. Framework: WSJF (Weighted Shortest Job First).

Pilar 1: Core Infrastructure

API unificada, contrato estável e abstração de provider — o esqueleto sobre o qual tudo é construído.

#IDOportunidadeWSJFEsforçoKRs
1OPP-01Eliminar reimplementação de integração com gateway em cada app10.0LKR-01, KR-02, KR-03
2OPP-09Estabilidade contratual da API para apps consumidores14.0MKR-01, KR-03
3OPP-08Liberdade para negociar com múltiplos gateways sem retrabalho13.0MKR-03

Pilar 2: Development Velocity

Modo internal, staging determinístico e documentação unificada eliminam dependências externas.

#IDOportunidadeWSJFEsforçoKRs
4OPP-10Testes de pagamento dependem de sandbox instável do Asaas13.0MKR-04, KR-01
7OPP-12Staging precisa ser determinístico e controlável22.0SKR-04
6OPP-02Devs precisam entender API de cada gateway em vez de contrato único11.5MKR-01, KR-03

Pilar 3: Production Reliability

Idempotência, entrega garantida de webhooks e observabilidade completa de transações.

#IDOportunidadeWSJFEsforçoKRs
5OPP-14Sem idempotência, retries causam cobranças duplicadas13.5MKR-05, KR-02
8OPP-13Callbacks precisam ser entregues mesmo em falha temporária11.0MKR-05, KR-02
9OPP-06Investigar falhas exige acessar logs em múltiplos sistemas9.5MKR-02, KR-05
prioritized-opportunities.json

Hipóteses de Solução

7 hipóteses formuladas pelo Product Designer, cada uma com assumptions críticas validáveis por protótipo ou entrevista.

HYP-01 — Core Infrastructure
API unificada com contrato estável no Dashboard e Transactions

Uma camada de API unificada com contrato versionado dará aos operadores visibilidade em tempo real de todos os pagamentos do ecossistema, eliminando a necessidade de cada app integrar diretamente com o gateway.

Assumptions: CA-01 (Dashboard sem overload), CA-02 (FilterBar cobre 95% dos workflows), CA-03 (contrato único para Pix/Card/Boleto), CA-04 (atribuição source_app suficiente).

HYP-02 — Core Infrastructure
Provider Pattern com ProviderToggle no painel admin

Uma camada de abstração de provider, surfaced por uma página Providers dedicada com ProviderToggle, permitirá ao super admin alternar entre Internal e External sem impactar apps downstream.

Assumptions: CA-05 (toggle two-card previne acidentes), CA-06 (modal de confirmação), CA-07 (status em 3 locais persistentes), CA-08 (histórico de swaps).

HYP-03 — Development Velocity
Internal Mode com controles de simulação no Settings

Modo Internal com controles de simulação na página Settings e ações contextuais na página Transactions eliminará dependência do sandbox Asaas, habilitando testes determinísticos.

Assumptions: CA-09 (admin panel vs env vars), CA-10 (banner amarelo suficiente), CA-11 (botões de simulação contextual), CA-12 (feature flags via Toggle).

HYP-04 — Development Velocity
Documentação unificada via Apps page e exemplos interativos

Documentação acessível do painel admin (Apps page) com exemplos interativos usando modo Internal reduzirá onboarding de semanas para horas.

Assumptions: CA-13 (Apps page como entry point), CA-14 (payloads reais como material de aprendizado), CA-15 (modal de registro self-service).

HYP-05 — Production Reliability
Idempotência visível no painel admin

Mostrar idempotency_key por transação, flagging de requests deduplicados e duplicatas na timeline dará confiança aos operadores de que cobranças duplicadas não ocorrem.

Assumptions: CA-16 (idempotency_key visível), CA-17 (evento dedup na timeline), CA-18 (sem dashboard dedicado de duplicatas).

HYP-06 — Production Reliability
Webhooks page com tabs Recebidos/Enviados e retry manual

Página dedicada de Webhooks com tabs received/sent, tracking de delivery status e retry one-click dará controle total sobre entrega de eventos.

Assumptions: CA-19 (two-tab mental model), CA-20 (attempt count com timing), CA-21 (botão retry suficiente), CA-22 (CodeBlock para debug).

HYP-07 — Production Reliability
TransactionTimeline com ciclo de vida completo

Componente TransactionTimeline mostrando o ciclo completo (request → gateway → webhook → callback) com timestamps correlacionados reduzirá tempo de investigação de horas para minutos.

Assumptions: CA-23 (timeline vertical clara), CA-24 (elapsed time entre eventos), CA-25 (cores semânticas), CA-26 (nós expansíveis com payload).

ideation-output.json

Protótipos

📝 Protótipo Low-fi (Wireframes) 🎨 Protótipo High-fi (Visual)

8 telas prototipadas: Dashboard, Transactions, Transaction Detail, Providers, Webhooks, Apps, Settings, Audit Log.

Backlog Estruturado

3 épicos, 13 features e 29 user stories com critérios de aceite em BDD/Gherkin.

EP-01
Infraestrutura Central de Pagamentos
API unificada, Provider Pattern, autenticação de apps, cofre de tokens e split de pagamento. Serve KR-01, KR-02 e KR-03.
FT-01
API Unificada de Pagamentos (Pix, Cartão, Boleto)
POST /pay/pix, POST /pay/card, POST /pay/boleto, GET /pay/transactions/:id, POST /pay/transactions/:id/refund
US-01 Criar cobrança Pix via API (QR Code + copia-e-cola)
US-02 Cobrar cartão de crédito via API (novo ou tokenizado)
US-03 Emitir boleto registrado via API com QR Code Pix embutido
US-04 Consultar status de qualquer transação
US-05 Estornar transação total ou parcialmente
FT-02
Provider Pattern com Abstração de Gateway
PaymentProvider interface, AsaasAdapter, InternalAdapter, ProviderFactory com feature flag
US-06 Alternar entre provider Internal e Asaas via painel admin
US-07 Contrato da API idêntico independente do provider ativo
FT-03
Autenticação e Registro de Apps Consumidores
X-API-Key, X-Source-App, rate limiting 100 tx/min por app
US-08 Registrar novo app via painel admin
US-09 Autenticação via API key com rate limiting
FT-04
Cofre de Tokens (Card Vault) Cross-App
Tokenização segura, nunca persiste dados sensíveis, reutilizável entre apps
US-10 Tokenizar cartão durante cobrança para reutilização futura
FT-05
Split de Pagamento por Transação
Regras de split por transação, validação soma = total, distribuição multi-parte
US-11 Definir regras de split ao criar transação
EP-02
Velocidade de Desenvolvimento do Ecossistema
Modo Internal, staging determinístico e onboarding de desenvolvedores. Serve KR-04 e KR-01.
FT-06
Modo Internal — Simulação Completa de Pagamentos
InternalAdapter simula Pix (auto-approve), Card (regras determinísticas), Boleto (mock)
US-12 Pix aprovado automaticamente no modo internal
US-13 Cartão com regras determinísticas no modo internal
US-14 Boleto com código mock no modo internal
FT-07
Ambiente de Staging Determinístico
Feature flags editáveis em runtime, banner de modo internal, configuração via admin
US-15 Configurar parâmetros de simulação via painel admin
US-16 Banner visual claro quando modo internal está ativo
FT-08
Gestão de Apps e Onboarding de Desenvolvedores
Apps page, registro self-service, payloads de request/response como exemplos
US-17 Visualizar apps registrados com métricas no painel admin
US-18 Ver payloads de request/response no detalhe de transação
EP-03
Confiabilidade e Operação em Produção
Idempotência, webhook retry, observabilidade, auditoria e autenticação RBAC. Serve KR-05 e KR-02.
FT-09
Idempotência e Deduplicação de Transações
X-Idempotency-Key obrigatório, UNIQUE constraint, dedup no audit log
US-19 Retries com mesma idempotency_key retornam resultado original
US-20 Idempotency_key e eventos de dedup visíveis no detalhe
FT-10
Webhook Delivery com Retry e Backoff Exponencial
Callbacks automáticos, retry 3x (30s, 2min, 10min), retry manual via admin
US-21 Callbacks automáticos quando status de transação muda
US-22 Callbacks falhos reenviados com backoff exponencial
US-23 Gerenciar webhooks com opção de retry manual no painel
FT-11
Observabilidade de Transações — Timeline e Dashboard
TransactionTimeline, 6 KPI cards, gráficos de volume/tipo/success rate
US-24 Timeline completa de transação no detalhe
US-25 Dashboard com KPIs e gráficos do ecossistema
US-26 Filtrar e buscar transações com múltiplos critérios
FT-12
Auditoria e Logging Estruturado
Audit log para todas as ações admin, soft delete policy, logging estruturado
US-27 Toda ação administrativa registrada em log de auditoria
US-28 Ações operacionais (reprocessar, estornar, cancelar) no detalhe
FT-13
Autenticação e RBAC do Painel Admin
Login JWT, 3 roles (admin, operator, viewer), RBAC em todas as rotas
US-29 Login com email/senha e controle de acesso por role
backlog-and-risks.json

Avaliação dos 4 Riscos (Cagan)

Valor para o Cliente
Aprovado approved
OST validado com 15 oportunidades mapeadas a 5 KRs. 7 hipóteses de solução com 26 assumptions críticas. 3 personas com necessidades distintas. 9 oportunidades priorizadas via WSJF cobrindo jornada completa de integração a operação.
Valor de Negócio
Aprovado approved
Todos os 5 KRs cobertos com full coverage. EP-01 + EP-02 servem KR-01 a KR-04. EP-03 serve KR-05 e KR-02. Risco residual: SQLite pode ser gargalo se volume exceder expectativas (AS-03).
Usabilidade
Aprovado approved
8 telas, 7 fluxos e 8 interações validadas. Design segue padrão density-first (inspiração Stripe/Datadog). Princípios de Norman aplicados: visibilidade de status, feedback, constraints. Admin panel é ferramenta operacional, não consumer-facing.
Viabilidade Técnica
Aprovado approved
Stack idêntica ao ecossistema existente (TypeScript + Fastify + SQLite + React + Vite). Provider Pattern é padrão bem documentado. 29 endpoints, 8 rotas SPA, 13 features — escopo viável. RBAC com JWT já provado no ecp-digital-bank.
backlog-and-risks.json