Merge pull request #52 from rede5/codex/find-task-and-roadmap-documentation

docs: add B2B gaps, roadmap, and test matrix
2026-01-01 15:22:35 -03:00 · 2026-01-01 15:22:35 -03:00 · cb9ccc9792
commit cb9ccc9792
parent a51dfd14af d3f1d0e36d
12 changed files with 363 additions and 0 deletions
--- 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
--- 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:
--- 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)
--- 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)
--- 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)
--- a/docs/GAPS_ANALISE_B2B.md
+++ 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.
--- 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
--- a/docs/ROADMAP.md
+++ 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.
--- a/docs/TESTES.md
+++ 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.
--- 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)
--- 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:
--- 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: