Fluxos de Smoke

Fluxos de Smoke — api-community

Documentação canônica dos fluxos de smoke alinhados aos fluxos de negócio do ControleOnline.

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.

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).

Fluxos de negócio prioritários

1. Autenticação e conta

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)

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

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)

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

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

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)

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.

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

Referências

• github-flow
• smoke-tests-playground
• Coleção Postman no repo: postman/collections/Controle Online.json