Fluxos de Smoke

Fluxos de Smoke — api-community

Documentação técnica dos fluxos de smoke (API + contratos HTTP) alinhados ao catálogo canônico de fluxos de negócio do ControleOnline.

Fonte canônica do catálogo: smoke-test-flows.md
Espelho UI (app): Smoke-Test-Flows (app-community)
Alias nesta wiki: Smoke-Test-Flows

Os smoke tests validam ponta a ponta (API + contratos HTTP) os caminhos críticos antes de RC/staging. Evidências esperadas: status HTTP, payload mínimo e ausência de 5xx nos caminhos documentados.

Catálogo canônico (fluxo: <id>)

Todo smoke novo/alterado (incluindo API, quando classificado) deve declarar exatamente um id:

id	ator principal	nome
produto-cadastro	backoffice / gestor	Cadastro de produtos
compra-fluxo	comprador / loja / POS	Compra
device-configuracao	admin / operador	Configuração de devices
pedido-criacao	vendedor / operador	Criação de pedido
producao-fluxo	produção / operação	Produção
cliente-cadastro	CRM / atendimento	Cadastro de cliente
usuario-permissao	admin	Usuários, permissões e autenticação
financeiro-cobranca	financeiro	Cobrança, pagamento e conciliação
logistica-entrega	logística / entrega	Entrega e logística
relatorio-consulta	gestor	Relatórios e consultas gerenciais
integracao-api	sistema / API	Integração API entre módulos
outros	qualquer	Outros (fallback com justificativa obrigatória)

Smokes de API costumam mapear para integracao-api ou o fluxo de negócio exercitado (ex.: pedido-criacao, cliente-cadastro). Usar outros só com justificativa na issue.

Gate de evidência (API)

Para smoke de API, a evidência mínima inclui: status HTTP, payload mínimo sanitizado, ausência de 5xx nos caminhos documentados, e declaração fluxo: <id>.
Para smoke de UI/browser (quando o backend é validado via UI), aplica-se o gate visual completo da skill canônica (prints por etapa).

Flowcharts publicados no admin (quando o smoke cruza UI)

Quando a evidência do smoke de API também cobre (ou depende de) jornada UI dos produtos POS, SHOP, PPC, DELIVERY, CHECKOUT ou MANAGER, o gate operacional do QA aplica-se:

• ler GET https://api.controleonline.com/flowcharts com headers api-token + app-domain: admin.controleonline.com (token só no Drive admin-api.json, nunca no git);
• exigir flowchartIds existentes e enabled e prints por etapa;
• continuar declarando fluxo: <id> deste catálogo.

Smoke órfão (fluxo: outros sem flowchartId válido) nesses produtos bloqueia aceite. Detalhes e UI de conferência: Smoke-Test-Flows (app-community) · fonte smoke-test-flows.md · agents-mcp#177.

---

Como executar / consumir

Fonte	Uso
Bundle smoke-tests-playground	GET /tests, GET /tests/index.json, GET /tests/api — índice agregado de suites
Artifacts	GET /tests/artifacts/{suiteId}/{arquivo} — reports, prints
Runner	POST /tests/run (quando habilitado no ambiente)
Coleção Postman	postman/collections/Controle Online.json no repo

Playground: pacote controleonline/smoke-tests-playground (submódulo modules/controleonline/smoke-tests-playground).

Mapeamento para o catálogo oficial de fluxos

Todo smoke novo ou alterado deve declarar fluxo: <id> de acordo com a skill canônica.

Seção desta página	fluxo (id catálogo)	Ator principal
1. Autenticação e conta	usuario-permissao	admin
2. Pessoas e empresas	cliente-cadastro	CRM / atendimento
3. Produtos e catálogo	produto-cadastro	backoffice / gestor
4. Pedidos (Orders / PDV)	pedido-criacao / compra-fluxo	vendedor / operador / loja
5. Financeiro e cobranças	financeiro-cobranca	financeiro
6. Config, notificação e relatórios	device-configuracao / relatorio-consulta	admin / gestor
7. Integrações (WhatsApp / marketing)	integracao-api	sistema / API
(fallback)	outros	qualquer — com justificativa obrigatória

Papel da API nas visões (APP_TYPE)

A api-community é o backend compartilhado. Nos smokes:

Visão	O que a API faz	O que a API não deve assumir
MANAGER / ADMIN	AuthZ, configs, relatórios, usuários/permissões	UI de navegação ou layout de telas
CRM	People, companies, links, create-account	Fluxo visual de atendimento
POS / SHOP / PPC	Orders, products, inventory, payments	Renderização de PDV/loja
DELIVERY / SERVICE	Fulfillment, logistics hooks quando expostos	Roteirização de UI
Transversal	Multi-tenancy, contratos HTTP, workers	Dados de outros tenants; secrets em payload

Detalhes de fronteira de UI: app-community wiki e MODOS_OPERACAO.md no app.

Fluxos de negócio prioritários

1. Autenticação e conta (usuario-permissao)

Passo	Endpoint / ação	Evidência esperada
Login (token)	POST autenticação / oauth (coleção LOGIN → Token)	200 + token JWT/access válido
Me / perfil	GET recurso “My” autenticado	200 + people/user do tenant
Create account	fluxo create-account (people)	201/200 + pessoa criada; visitor/marketing link quando aplicável
Password recovery	request + complete recovery	200 / sem vazamento de existência de conta além do contrato

2. Pessoas e empresas — CRM / Manager (cliente-cadastro)

Passo	Endpoint / ação	Evidência esperada
Listagem people	GET /people (filtros tenant)	200 + hydra collection; soft-deleted ausentes por default
Criar PJ / vínculo	create company + people_links	201; auto-link pessoa autenticada quando fluxo My Companies
Endereços / CEP	lookup postal code + address	200 CEP; coords quando disponíveis; 404/400 estáveis

3. Produtos e catálogo (produto-cadastro)

Passo	Endpoint / ação	Evidência esperada
Categorias shop	GET /shop/categories	200 + árvore/lista
Produtos	GET /products, GET /products/{id}	200; summary quando aplicável
Inventário / labels	inventory, labels/print, SKU	200 ou job aceito; sem 5xx

4. Pedidos — Orders / PDV (pedido-criacao / compra-fluxo)

Passo	Endpoint / ação	Evidência esperada
Criar / listar orders	POST/GET /orders	201/200; tenant isolado
Itens order_products	add / replace products	200/201; total coerente
Fulfillment / ajustes	order_product_fulfillments, adjustments	200 em endpoints auditados; client role denied onde previsto
Cancelamento	cancel order (status in-place)	status atualizado; sem 5xx
Impressões	print / conference-print	200 ou PDF/stream aceito

5. Financeiro e cobranças (financeiro-cobranca)

Passo	Endpoint / ação	Evidência esperada
Invoices / order_invoices	listagem e detalhe	200; overdue mark worker não quebra request path
Paylist anônimo	página/rota paylist por CPF/CNPJ	200 público; sem dados de outros tenants
Notificação overdue	comando notify overdue	job ok; canais e-mail/WhatsApp conforme config

6. Config, notificação e relatórios (device-configuracao / relatorio-consulta)

Passo	Endpoint / ação	Evidência esperada
Configs	GET/POST /configs, menu-config	200/201 no tenant
Notifications	listagem	200
Reports	order hours, attendance	200 com payload agregado

7. Integrações — WhatsApp / marketing (integracao-api)

Passo	Endpoint / ação	Evidência esperada
Sessions WhatsApp	list/create connection	200/201 conforme papel
Marketing events	POST /marketing_events (PUBLIC_ACCESS create)	201 visitante; read ROLE_HUMAN

Critérios transversais de evidência

1. AuthZ: rotas autenticadas rejeitam anônimo (401/403); rotas públicas documentadas não exigem token.
2. Multi-tenancy: resposta nunca vaza entidades de outro company/people.
3. Estabilidade: caminhos da tabela acima não retornam 5xx em smoke verde.
4. Contrato: JSON-LD/Hydra ou payload acordado na coleção Postman; campos obrigatórios presentes.
5. Idempotência operacional: workers (mark overdue, notify) podem ser reexecutados sem corromper dados.
6. Declaração de fluxo: todo smoke deve declarar fluxo: <id> do catálogo oficial; usar outros só com justificativa.

Ponte estrutural do repositório

• Ponte da wiki no repo: docs/wiki.md → somente https://github.com/ControleOnline/api-community/wiki
• Não usar submódulo docs/wiki no api-community
• Validação automatizada: scripts/validate-wiki-structure.cjs e tests/WikiStructureTest.php

Links cruzados

Destino	URL
Home desta wiki	Home
Alias skill	Smoke-Test-Flows
Catálogo oficial (agents-mcp)	smoke-test-flows.md
App (UI / modos)	app-community/wiki
Playground	smoke-tests-playground
GitHub flow	github-flow

Referências

• Coleção Postman no repo: postman/collections/Controle Online.json
• Issue origem desta página: api-community#80