saveinmed/docs/GAPS_ANALISE_B2B.md

# Lacunas e requisitos pendentes (Marketplace B2B)

> **Local do documento:** `docs/GAPS_ANALISE_B2B.md`

## Status (pronto x faltando)

**Pronto**
- Nenhum item confirmado como concluído nesta análise de lacunas.

**Faltando**
- Itens listados nas seções abaixo.

---


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 6%** (não pode ser mostrada ao comprador).
- **Comissão do vendedor de 6%** (conforme documentação atual do backend; confirmar regra de negócio se houver mudança).

> Observação: a regra atual citada na documentação do backend indica taxa invisível de **6%** para compradores.
> Antes de implementar, alinhar o **modelo final** de taxas (6% buyer fee + 6% seller fee? modelo único? split?).

---

## 1) Backend (Go API)

### 1.1 Regras de negócio / taxas
- [ ] **Definir modelo final de taxas** (6% 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.: 6%).
  - `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** (6% 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.

---

## 6) Alinhamento Inicial (Semana 1) — Plano detalhado

### 6.1 Revisar lacunas no documento
**Objetivo:** validar e ajustar as lacunas descritas neste documento com as áreas de Produto, Negócios e Tech.  
**Passos:**
1. **Revisão guiada do cenário**: confirmar com stakeholders o fluxo “comprador só descobre vendedor no final” e a “taxa invisível de 6%”.  
2. **Conferir impactos por domínio**:
   - Backend: preço final x base, auditoria, controle de acesso.
   - Frontend(s): ocultação de vendedor e taxa invisível.
   - Backoffice: gestão e auditoria de taxas.
3. **Validar riscos de compliance**: alinhar transparência fiscal para vendedor e registros de auditoria.
4. **Atualizar este documento** com decisões finais.
**Entregáveis da semana:** documento revisado + decisões registradas em seção 5.

### 6.2 Definir MVP do backend e critérios de aceite por módulo
**Objetivo:** fechar o escopo mínimo do backend para suportar o fluxo B2B sem quebrar o modelo atual.  

#### MVP Backend (escopo mínimo)
1. **Taxas e precificação**
   - Configurar taxas (`buyer_fee_rate`, `seller_fee_rate`) via config/DB.
   - Calcular preço final (buyer) e payout (seller) com rastreabilidade.
2. **Ocultação do vendedor**
   - Listagem e detalhes **sem identificação do vendedor** até o evento final.
   - Endpoint pós-compra para revelar vendedor.
3. **Auditoria e segurança**
   - Logs de auditoria e campos internos para backoffice/admin.
   - Regras de acesso garantindo anonimato pré-compra.
4. **Contratos de API**
   - Swagger atualizado com campos pré e pós-compra.

#### Critérios de aceite por módulo (backend)
**Módulo 1 — Taxas e precificação**
- [ ] Dado um produto, o preço final exibido ao comprador **já inclui** a taxa invisível.  
- [ ] Os campos de taxa **não aparecem** para o comprador.  
- [ ] A auditoria registra base, taxas e payout do vendedor.  

**Módulo 2 — Ocultação do vendedor**
- [ ] Endpoints de catálogo e carrinho **não retornam** dados identificáveis do vendedor.  
- [ ] Existe endpoint de revelação pós-compra com dados completos.  
- [ ] Testes confirmam que não há vazamento indireto (id, slug).  

**Módulo 3 — Segurança e controle de acesso**
- [ ] Rotas de auditoria são restritas a admin/backoffice.  
- [ ] Logs registram decisões de preço e ocultação.  

**Módulo 4 — Contratos de API**
- [ ] Swagger documenta claramente os campos pré-compra e pós-compra.  
- [ ] Versionamento definido caso haja breaking change.  

### 6.3 Atualizar backlog e priorizar dependências críticas
**Objetivo:** ordenar entregas e identificar bloqueios.  

#### Backlog priorizado (ordem de execução)
1. **Definir regra final de taxas (Negócio + Produto)**  
2. **Modelo de dados e auditoria (Backend)**  
3. **Ocultação do vendedor (Backend + Frontend)**  
4. **Endpoint de revelação pós-compra (Backend + Frontend)**  
5. **Swagger/contratos e versionamento (Backend)**  
6. **Backoffice: gestão de taxas e auditoria (Backoffice)**  

#### Dependências críticas
- **Regra final de taxa** (bloqueia cálculo de preço, auditoria e UI).  
- **Definição do evento “final”** (bloqueia endpoint de revelação).  
- **Modelo de dados de pedido** com campos de auditoria (bloqueia backoffice).  

---

## 7) Plano de ação (resumido)
**Semana 1**
- Validar regras de negócio e evento final.  
- Revisar e atualizar este documento.  
- Definir MVP backend e critérios de aceite.  

**Semana 2**
- Implementar cálculo de taxas, auditoria e mascaramento.  
- Atualizar Swagger e contratos.  

**Semana 3**
- Integração com frontend(s) e backoffice.  
- Testes de segurança/anonimato pré-compra.  

---

## 8) Plano de ação para colocar no ar (go-live)
**Objetivo:** preparar o rollout do fluxo B2B com taxas corretas (6% buyer + 6% seller), anonimato pré-compra e auditoria.  

### 8.1 Pré-lançamento (D-7 a D-1)
1. **Confirmar taxas finais** com Negócio/Produto e alinhar comunicação interna.  
2. **Validar ambiente**:
   - Variáveis `BUYER_FEE_RATE=0.06` e `SELLER_FEE_RATE=0.06` aplicadas no backend.
   - Backoffice com auditoria habilitada e acesso restrito.  
3. **Teste completo do fluxo**:
   - Simular compra ponta-a-ponta com vendedor oculto até o evento final.  
   - Conferir cálculo: preço base → preço final → payout.  
4. **Checklist de UX/Legal**:
   - Comprador não vê taxa explícita.  
   - Vendedor recebe transparência fiscal e extrato de taxas.  

### 8.2 Lançamento (D0)
1. **Deploy coordenado** (backend → frontend(s) → backoffice).  
2. **Monitoramento em tempo real**:
   - Logs de auditoria (base/fee/payout).  
   - Alertas de divergência de cálculo.  
3. **Canal de suporte ativo** para incidentes (pagamento, identidade de vendedor, cálculo de taxas).  

### 8.3 Pós-lançamento (D+1 a D+7)
1. **Auditoria de pedidos** para validar 100% dos cálculos.  
2. **Coleta de feedback** de compradores e vendedores (anonimato e transparência).  
3. **Ajustes rápidos** em contratos, UI e regras de negócio conforme necessidade.