diff --git a/README.md b/README.md index 652ae7c..0477952 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ SaveInMed é uma plataforma completa de marketplace B2B que conecta farmácias e - [Deploy](#-deploy) - [Contribuindo](#-contribuindo) - [Licença](#-licença) +- [Documentação Complementar](#-documentação-complementar) --- @@ -35,6 +36,14 @@ SaveInMed é uma solução completa que oferece: --- +## 📚 Documentação Complementar + +- [Lacunas e requisitos pendentes (Marketplace B2B)](./docs/GAPS_ANALISE_B2B.md) +- [Roadmap de Tasks](./docs/ROADMAP.md) +- [Matriz de Testes](./docs/TESTES.md) + +--- + ## 🏗️ Arquitetura do Sistema ```mermaid diff --git a/backend/BACKEND.md b/backend/BACKEND.md index 2610dbb..1c41dac 100644 --- a/backend/BACKEND.md +++ b/backend/BACKEND.md @@ -189,6 +189,8 @@ go test -coverprofile=coverage.out ./... go tool cover -html=coverage.out ``` +> Para matriz completa (com/sem banco e Playwright), veja: [docs/TESTES.md](../docs/TESTES.md) + ## 📊 Performance Esta API foi otimizada para alta performance: diff --git a/backend/README.md b/backend/README.md index 764fc9c..1bf8789 100644 --- a/backend/README.md +++ b/backend/README.md @@ -89,3 +89,11 @@ graph TD - Role-Based Access Control - Payment Gateway Integration (Mercado Pago, Asaas, Stripe) - Real-time Inventory Management + +## 🧪 Tests + +```bash +go test ./... -cover +``` + +> Para matriz completa (com/sem banco e Playwright), veja: [docs/TESTES.md](../docs/TESTES.md) diff --git a/backoffice/BACKOFFICE.md b/backoffice/BACKOFFICE.md index c136ba0..aef1897 100644 --- a/backoffice/BACKOFFICE.md +++ b/backoffice/BACKOFFICE.md @@ -220,6 +220,8 @@ pnpm test:e2e pnpm test:cov ``` +> Para matriz completa (com/sem banco e Playwright), veja: [docs/TESTES.md](../docs/TESTES.md) + ## 🔒 Segurança - Senhas hasheadas com bcrypt (salt rounds: 10) diff --git a/docs/BACKEND.md b/docs/BACKEND.md index ff412ad..b69f0b2 100644 --- a/docs/BACKEND.md +++ b/docs/BACKEND.md @@ -79,3 +79,5 @@ go run ./cmd/api ```bash go test ./... -cover ``` + +> Para matriz completa (com/sem banco e Playwright), veja: [docs/TESTES.md](./TESTES.md) diff --git a/docs/GAPS_ANALISE_B2B.md b/docs/GAPS_ANALISE_B2B.md new file mode 100644 index 0000000..e71283d --- /dev/null +++ b/docs/GAPS_ANALISE_B2B.md @@ -0,0 +1,98 @@ +# Lacunas e requisitos pendentes (Marketplace B2B) + +Este documento descreve o que **falta** para cumprir o cenário solicitado: +- **Comprador só descobre o vendedor no final** do fluxo. +- **Taxa invisível de 12%** (não pode ser mostrada ao comprador). +- **Comissão do vendedor de 6%** (sugestão do usuário: “vai ficar 6% para vendedor”; confirmar regra de negócio e origem dos 6%). + +> Observação: a regra atual citada na documentação do backend indica taxa invisível de **12%** para compradores. +> Antes de implementar, alinhar o **modelo final** de taxas (12% buyer fee + 6% seller fee? 12% total? split?). + +--- + +## 1) Backend (Go API) + +### 1.1 Regras de negócio / taxas +- [ ] **Definir modelo final de taxas** (12% para comprador, 6% para vendedor): + - esclarecer se são **duas taxas distintas** ou **partes de uma taxa total**. + - documentar em `config` (ex.: `BUYER_FEE_RATE`, `SELLER_FEE_RATE`) e no Swagger. +- [ ] **Normalizar cálculo de preços**: + - guardar preços **base** (seller price) e **final** (buyer price) com rastreabilidade. + - garantir que a taxa **não aparece** em payloads do comprador. +- [ ] **Auditoria de taxas**: + - registrar no pedido: `base_price`, `buyer_fee_rate`, `buyer_fee_amount`, `seller_fee_rate`, `seller_fee_amount`, `payout_amount`. + - expor esses campos **somente** para backoffice/admin. + +### 1.2 Ocultação do vendedor +- [ ] **Mascarar dados do vendedor** nos endpoints públicos do catálogo/pesquisa: + - retornar apenas atributos neutros (ex.: distância, categoria, SLA, estoque, validade) sem identidade. +- [ ] **Revelar vendedor somente no final**: + - definir claramente qual evento é “final” (ex.: confirmação do pagamento, confirmação do pedido). + - criar endpoint específico para **revelação pós-compra**. + +### 1.3 Contratos de API +- [ ] **Revisar schemas** do Swagger para refletir: + - campos mascarados antes da compra; + - campos completos após compra; + - campos financeiros internos (somente backoffice/admin). +- [ ] **Versionar mudanças** (ex.: `/api/v1` → `/api/v2` se necessário para evitar breaking change). + +### 1.4 Segurança e compliance +- [ ] **Garantir controle de acesso**: + - comprador não pode inferir vendedor por `id`, `slug` ou dados indiretos. +- [ ] **Logs de auditoria** para preço final vs. preço base. +- [ ] **Testes automatizados** garantindo que vendedor não aparece em respostas pré-compra. + +--- + +## 2) Frontend (Marketplace React) + +### 2.1 Ocultação do vendedor no fluxo +- [ ] **Remover nome/identidade do vendedor** das telas de catálogo/listagem/carrinho. +- [ ] **Substituir por informações neutras**: + - faixa de SLA, localização genérica (ex.: “Região Metropolitana”), disponibilidade, avaliações agregadas. +- [ ] **Bloquear UI que revele vendedor** antes do “evento final”. + +### 2.2 Exibição de preços +- [ ] **Mostrar somente preço final** (com taxa invisível aplicada), sem linha de “taxa”. +- [ ] **Texto/tooltip neutro** (ex.: “preço final do produto”). + +### 2.3 Ponto de revelação +- [ ] **Tela pós-compra** com dados completos do vendedor. +- [ ] **Estados intermediários** (checkout, pagamento pendente) sem revelar vendedor. + +--- + +## 3) Frontend principal (saveinmed-frontend) + +> Se este frontend também for usado por compradores/vendedores finais, as mesmas regras acima precisam ser espelhadas. + +- [ ] **Revisar listagens** para garantir que vendedor não aparece antes da compra. +- [ ] **Revisar preços** para exibir apenas valor final (taxa invisível). +- [ ] **Revelação pós-compra** na área de pedidos. + +--- + +## 4) Backoffice (NestJS) + +### 4.1 Administração de taxas +- [ ] **Tela e endpoints** para configurar: + - `buyer_fee_rate` (ex.: 12%). + - `seller_fee_rate` (ex.: 6%). +- [ ] **Histórico de alterações** e auditoria. + +### 4.2 Visibilidade e auditoria +- [ ] **Dashboard financeiro** com: + - preço base, preço final, taxas, payout do vendedor. +- [ ] **Exportação** para contabilidade (CSV/Excel). + +### 4.3 Compliance +- [ ] **Logs de decisão** (por pedido) demonstrando que comprador não viu taxa. + +--- + +## 5) Alinhamentos necessários (negócio + produto) +- [ ] **Definir “momento final”** de revelação do vendedor. +- [ ] **Definir regra de taxa** (12% buyer + 6% seller ou modelo único). +- [ ] **Definir termos legais** (taxa invisível, transparência fiscal para vendedor). +- [ ] **Definir experiência de suporte** (ex.: disputa, devolução) sem expor vendedor antes da compra. diff --git a/docs/MARKETPLACE.md b/docs/MARKETPLACE.md index 8e520a9..a9803bc 100644 --- a/docs/MARKETPLACE.md +++ b/docs/MARKETPLACE.md @@ -77,6 +77,8 @@ npm run dev npm run test ``` +> Para matriz completa (com/sem banco e Playwright), veja: [docs/TESTES.md](./TESTES.md) + ## Build ```bash diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000..87a5910 --- /dev/null +++ b/docs/ROADMAP.md @@ -0,0 +1,93 @@ +# Roadmap de Tasks (Marketplace B2B) + +Este roadmap foca no requisito: +- comprador só descobre vendedor no final; +- taxa invisível de 12%; +- comissão de 6% para vendedor (a confirmar); +- governança e auditoria no backoffice; +- cobertura de testes (com/sem banco e Playwright). + +> Cada item possui **caixa de execução** para acompanhamento. + +--- + +## 0) Alinhamento de regras de negócio (obrigatório) +- [ ] **Definir modelo de taxas**: + - [ ] confirmar se “12% + 6%” são taxas distintas ou partes de uma taxa total. + - [ ] validar impacto em precificação e faturamento. +- [ ] **Definir momento final de revelação** do vendedor: + - [ ] após pagamento aprovado? + - [ ] após confirmação de pedido? + - [ ] após envio? +- [ ] **Definir política legal/UX** para taxa invisível e transparência ao vendedor. + +--- + +## 1) Backend (Go API) +- [ ] **Modelagem de taxas** + - [ ] adicionar `SELLER_FEE_RATE` (se aplicável) no `config`. + - [ ] registrar `base_price`, `buyer_fee_rate/amount`, `seller_fee_rate/amount`, `payout_amount` no pedido. +- [ ] **Mascaramento do vendedor** em respostas públicas + - [ ] revisar endpoints de catálogo/pesquisa para remover identidade do vendedor. + - [ ] garantir que IDs não permitam inferência. +- [ ] **Revelação pós-compra** + - [ ] criar endpoint para dados completos do vendedor **após evento final**. +- [ ] **Swagger/Docs** + - [ ] atualizar schemas para respostas pré e pós-compra. +- [ ] **Testes automatizados** + - [ ] cobrir mascaramento do vendedor. + - [ ] cobrir cálculos de taxas. + +--- + +## 2) Marketplace (React) +- [ ] **Listagem/Detalhe** + - [ ] remover qualquer referência a vendedor. + - [ ] substituir por dados neutros. +- [ ] **Carrinho/Checkout** + - [ ] mostrar apenas preço final sem taxa visível. + - [ ] impedir revelação do vendedor antes do evento final. +- [ ] **Pós-compra** + - [ ] exibir dados completos do vendedor. +- [ ] **Testes de UI** + - [ ] testes para garantir ocultação e revelação correta. + +--- + +## 3) SaveInMed Frontend (Next.js) +- [ ] **Revisar fluxos de comprador** + - [ ] ocultar vendedor antes do final. + - [ ] mostrar somente preço final. +- [ ] **Área de pedidos** + - [ ] revelar vendedor após evento final. +- [ ] **Testes** + - [ ] adicionar Playwright para fluxo de compra e revelação. + +--- + +## 4) Backoffice (NestJS) +- [ ] **Admin de taxas** + - [ ] tela/configuração de `buyer_fee_rate` e `seller_fee_rate`. +- [ ] **Auditoria financeira** + - [ ] painel com preço base, taxas e payout. +- [ ] **Logs e compliance** + - [ ] rastrear alterações de taxas. + +--- + +## 5) Testes e qualidade +- [ ] **Matriz de testes** (ver `docs/TESTES.md`) + - [ ] definir CI mínima por serviço. + - [ ] separar testes com e sem banco. +- [ ] **Playwright** + - [ ] configurar projeto e primeiros cenários E2E. + +--- + +## 6) Documentação e comunicação +- [ ] **Atualizar documentação técnica** + - [ ] links cruzados entre README principal e docs. + - [ ] instruções claras de testes. +- [ ] **Checklist de release** + - [ ] validação das taxas. + - [ ] validação de mascaramento do vendedor. diff --git a/docs/TESTES.md b/docs/TESTES.md new file mode 100644 index 0000000..8f19cb3 --- /dev/null +++ b/docs/TESTES.md @@ -0,0 +1,135 @@ +# Matriz de Testes (com/sem banco e Playwright) + +Este documento consolida **todos os testes** conhecidos no repositório e define uma matriz clara para rodar testes **com banco**, **sem banco** e **E2E/Playwright**. + +--- + +## 1) Backend (Go) — `backend/` + +### 1.1 Sem banco +- **Unitários e integrações sem DB** (default): + ```bash + cd backend + go test ./... -cover + ``` + +### 1.2 Com banco +- Alguns testes usam conexão real e **podem ser ignorados** quando `SKIP_DB_TEST` está setado. +- Para rodar com banco, **não** defina `SKIP_DB_TEST` e configure `DATABASE_URL`: + ```bash + cd backend + export DATABASE_URL=postgres://postgres:postgres@localhost:5432/saveinmed?sslmode=disable + go test ./... -cover + ``` + +### 1.3 Observações +- Testes com banco estão em: + - `backend/internal/server/server_test.go` + - `backend/internal/repository/postgres/postgres_test.go` + +--- + +## 2) Marketplace (React/Vite) — `marketplace/` + +### 2.1 Unitários (Vitest) +```bash +cd marketplace +npm test +``` + +### 2.2 Coverage +```bash +cd marketplace +npm run test:coverage +``` + +### 2.3 Observações +- Configuração do Vitest: `marketplace/vitest.config.ts` +- Pastas de testes: `marketplace/src/**/*.test.{ts,tsx}` + +--- + +## 3) Backoffice (NestJS) — `backoffice/` + +### 3.1 Unitários +```bash +cd backoffice +pnpm test +``` + +### 3.2 E2E +```bash +cd backoffice +pnpm test:e2e +``` + +### 3.3 Coverage +```bash +cd backoffice +pnpm test:cov +``` + +--- + +## 4) SaveInMed Frontend (Next.js) — `saveinmed-frontend/` + +### 4.1 Unitários (quando configurados) +```bash +cd saveinmed-frontend +npm test +``` + +### 4.2 E2E (quando configurados) +```bash +cd saveinmed-frontend +npm run test:e2e +``` + +### 4.3 Playwright (dependência presente) +- Existe dependência de `@playwright/test` no `package-lock.json`, mas não há documentação/roteiro de testes. +- **Recomendação**: criar `playwright.config.ts` e uma pasta `tests/e2e`. +- Exemplo de comando esperado após configuração: + ```bash + cd saveinmed-frontend + npx playwright test + ``` + +--- + +## 5) Website (Fresh/Deno) — `website/` + +### 5.1 Testes +```bash +cd website +deno test +``` + +### 5.2 Coverage +```bash +cd website +deno test --coverage=coverage +``` + +--- + +## 6) Runner unificado (script raiz) + +O script `start.sh` possui função para executar testes do backend e marketplace: + +```bash +./start.sh --test +``` + +--- + +## 7) Matriz resumida + +| Componente | Sem DB | Com DB | Unitário | E2E | Playwright | +|-----------|--------|--------|----------|-----|------------| +| Backend (Go) | ✅ | ✅ | ✅ | ❌ | ❌ | +| Marketplace (React) | ✅ | N/A | ✅ | ❌ | ❌ | +| Backoffice (NestJS) | ✅ | ✅* | ✅ | ✅ | ❌ | +| SaveInMed Frontend | ✅ | N/A | ✅* | ✅* | ✅* | +| Website (Fresh/Deno) | ✅ | N/A | ✅ | ❌ | ❌ | + +\* dependendo da configuração local e do banco necessário pelos testes. diff --git a/marketplace/README.md b/marketplace/README.md index a84e161..4caad03 100644 --- a/marketplace/README.md +++ b/marketplace/README.md @@ -89,3 +89,11 @@ graph TD - **Catalog**: Virtualized product lists with search and filter - **Checkout**: Multi-step checkout with payment integration - **Dashboard**: User order history and status tracking + +## 🧪 Tests + +```bash +npm test +``` + +> For the complete test matrix (with/without DB and Playwright), see: [docs/TESTES.md](../docs/TESTES.md) diff --git a/saveinmed-frontend/README.md b/saveinmed-frontend/README.md index 42ef420..091636a 100644 --- a/saveinmed-frontend/README.md +++ b/saveinmed-frontend/README.md @@ -290,6 +290,8 @@ npm test npm run test:e2e ``` +> Para matriz completa (com/sem banco e Playwright), veja: [docs/TESTES.md](../docs/TESTES.md) + ## ⚡ Performance Otimizações implementadas: diff --git a/website/README.md b/website/README.md index 76b78b2..7575684 100644 --- a/website/README.md +++ b/website/README.md @@ -353,6 +353,8 @@ deno test --coverage=coverage deno coverage coverage --lcov > coverage.lcov ``` +> Para matriz completa (com/sem banco e Playwright), veja: [docs/TESTES.md](../docs/TESTES.md) + ## 📊 Analytics Integração com Google Analytics: