rede5/saveinmed
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
saveinmed/README.md

759 lines
19 KiB
Markdown
Raw Blame History

# SaveInMed
## Status (pronto x faltando)
**Pronto**
- Conteúdo descrito neste documento.
**Faltando**
- Confirmar no código o estado real das funcionalidades e atualizar esta seção conforme necessário.
---
# SaveInMed 🏥
## 📊 Status do Projeto (Atualizado: Fev/2026)
| Módulo | Status | Detalhes |
| :--- | :--- | :--- |
| **Login** | ✅ PRONTO | Autenticação JWT corrigida e funcional. |
| **Registro de Usuário** | 🚧 PENDENTE | Tela exibe "Em breve". Necessário implementar fluxo de self-service. |
| **Gerenciar Empresas** | ⚠️ AJUSTAR | CRUD funcional. **Falta:** Máscara de CNPJ e Upload de Licença Sanitária. |
| **Gerenciar Usuários** | ✅ PRONTO | Criação de perfis (Admin, Dono, Colaborador, Entregador). |
| **Produtos / Pedidos** | ✅ PRONTO | Fluxos básicos de marketplace operacionais. |
| **Logística / Avaliações**| ❌ VAZIO | Módulos aguardando definição de requisitos. |
---
## 🗺️ Fluxo de Funcionalidades (Wireframe)
```mermaid
graph TD
%% Atores
User((Usuário Deslogado))
Admin((Admin/Dono))
Deliv((Entregador))
%% Fluxo de Entrada
User -->|Acessa| Login[Login Page]
Login -->|Sucesso| Dashboard
Login -->|Novo Usuário| Register[Cadastro de Novo Usuário]
Register -.->|Pendente| MsgBreve[Msg: 'Em Breve']
%% Dashboard Geral
Dashboard --> ModUsers[Gerenciar Usuários]
Dashboard --> ModEmpresas[Gerenciar Empresas]
Dashboard --> ModProd[Gerenciar Produtos]
Dashboard --> ModPed[Gerenciar Pedidos]
Dashboard --> ModLog[Logística]
Dashboard --> ModAval[Avaliações]
%% Detalhes dos Módulos
subgraph "Módulo Usuários"
ModUsers --> CreateUser[Criar Novo Usuário]
CreateUser --> Roles[Define: Colaborador, Entregador, Dono, Admin]
end
subgraph "Módulo Empresas"
ModEmpresas --> ListEmp[Listar Empresas]
ListEmp --> StatusEmp{Status?}
StatusEmp -->|Pendente| Verify[Verificar]
StatusEmp -->|Verificada| Active[Ativa]
ModEmpresas --> CadEmp[Cadastrar Empresa]
CadEmp --> FieldsEmp[Campos: Razão, CNPJ, Categoria, Licença, Localização]
end
subgraph "Pendências Críticas"
CadEmp -.->|Falta| MaskCNPJ[Máscara/Validação CNPJ]
CadEmp -.->|Falta| UploadDoc[Upload Licença Sanitária]
ModLog -.->|Vazio| EmptyLog[Funcionalidade Inexistente]
ModAval -.->|Vazio| EmptyAval[Funcionalidade Inexistente]
end
```
---
**Plataforma B2B de Marketplace Farmacêutico**
SaveInMed é uma plataforma completa de marketplace B2B que conecta farmácias e distribuidoras farmacêuticas, facilitando a compra e venda de medicamentos e produtos farmacêuticos com eficiência, segurança e transparência.
---
## <20> Como Executar o Projeto (Guia Rápido)
Para rodar o sistema completo localmente, siga os passos abaixo:
### 1. Pré-requisitos
- **Go**: Instale a versão mais recente através do site oficial: [go.dev](https://go.dev/)
- **Node.js**: Certifique-se de ter o Node.js instalado para rodar o frontend.
### 2. Rodando o Back-end (Legado)
O core do marketplace está na pasta `backend-old`.
```bash
# Entre na pasta do backend antigo
cd saveinmed/backend-old
# Execute a API
go run ./cmd/api
```
### 3. Rodando o Marketplace (Frontend)
Em um novo terminal:
```bash
# Entre na pasta do marketplace
cd saveinmed/marketplace
# Instale as dependências
npm install
# Inicie o servidor de desenvolvimento
npm run dev
```
---
## <20>📋 Índice
- [Visão Geral](#-visão-geral)
- [Arquitetura do Sistema](#-arquitetura-do-sistema)
- [Componentes do Projeto](#-componentes-do-projeto)
- [Tecnologias Utilizadas](#-tecnologias-utilizadas)
- [Setup Completo](#-setup-completo)
- [Fluxo de Desenvolvimento](#-fluxo-de-desenvolvimento)
- [Deploy](#-deploy)
- [Contribuindo](#-contribuindo)
- [Licença](#-licença)
- [Documentação Complementar](#-documentação-complementar)
---
## 🎯 Visão Geral
SaveInMed é uma solução completa que oferece:
- ✅ **Marketplace B2B**: Conecta farmácias compradoras com distribuidoras vendedoras
- ✅ **Gestão de Catálogo**: Controle completo de produtos, lotes e validades
- ✅ **Processamento de Pedidos**: Fluxo completo desde o carrinho até a entrega
- ✅ **Pagamentos Integrados**: Mercado Pago com split automático de comissões
- ✅ **Dashboard Administrativo**: Métricas, relatórios e gestão completa
- ✅ **Multi-tenant**: Suporte para múltiplas empresas e usuários
- ✅ **Alta Performance**: APIs otimizadas em Go para operações críticas
- ✅ **Escalabilidade**: Arquitetura moderna e cloud-native
---
## 📚 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)
- [Plano de Conclusão do Backend](#-plano-de-conclusão-do-backend)
---
## 🏗️ Arquitetura do Sistema
```mermaid
graph TD
subgraph "Frontend Layer"
WEB[Website<br/>Fresh/Deno<br/>:8000]
MKT[Marketplace Frontend<br/>React/Vite<br/>:5173]
end
subgraph "Backend Layer"
API[Backend API<br/>Go 1.24<br/>:8080]
BACK[Backoffice<br/>NestJS/Fastify<br/>:3000]
end
subgraph "Data Layer"
PG[(PostgreSQL<br/>Database)]
end
subgraph "External Services"
MP[Mercado Pago<br/>Payments]
AS[Asaas<br/>Payments]
ST[Stripe<br/>Payments]
end
MKT -->|Marketplace| API
MKT -->|Auth/Profile| BACK
API --> PG
BACK --> PG
API --> MP
API --> AS
API --> ST
BACK --> MP
BACK --> AS
BACK --> ST
style WEB fill:#4ade80
style MKT fill:#60a5fa
style API fill:#f87171
style BACK fill:#fb923c
style PG fill:#94a3b8
```
---
## 🧭 Plano de Conclusão do Backend
Como gerente de projetos, o objetivo é fechar o backend do marketplace B2B garantindo alinhamento com os **3 pilares**: **Escopo**, **Prazo** e **Custo/Recursos**. O plano abaixo é um passo a passo enxuto para execução e acompanhamento.
### ✅ Pilares de Gestão
1. **Escopo (o que será entregue)**
- Funcionalidades mínimas do marketplace B2B: cadastro de empresas/usuários, catálogo, carrinho/pedido, pagamento, logística, e compliance.
- Integrações críticas (Mercado Pago, notificações, webhooks).
- Observabilidade e segurança (logs, auditoria, LGPD).
2. **Prazo (quando será entregue)**
- Trabalhar em **sprints quinzenais** com metas claras.
- Entregas contínuas por módulo para validação antecipada.
3. **Custo/Recursos (quem e quanto)**
- Times mínimos: 1 backend sênior, 1 backend pleno, 1 QA, 1 PO/PM.
- Infra de dev/qa com banco PostgreSQL e serviços externos mockados.
---
### 📌 Passo a Passo (Plano Executivo Detalhado)
1. **Alinhamento Inicial (Semana 1)**
- Revisar lacunas no documento [GAPS_ANALISE_B2B](./docs/GAPS_ANALISE_B2B.md) e mapear riscos.
- Definir o **MVP do backend** com critérios de aceite por módulo (dados, performance, segurança).
- Atualizar backlog com dependências críticas, owners e estimativas (XS/S/M/L).
- Definir calendário de ritos: planning, review, demo, retro e checkpoint executivo.
2. **Arquitetura, Base Técnica & Observabilidade (Semana 1-2)**
- Validar o diagrama de contexto e fluxos (auth, pedidos, pagamentos, logística).
- Padronizar logging estruturado, tracing e correlação de request.
- Definir versionamento de APIs (OpenAPI/Swagger + changelog).
- Configurar ambientes (dev/stage) com CI básico, seeds e migrations.
- Criar checklist de SLOs (latência, erros, disponibilidade).
3. **Modelagem de Dados & Core Domínio (Semana 2-3)**
- Validar e ajustar schema do banco ([docs/database-schema.md](./docs/database-schema.md)).
- Finalizar entidades core: empresas, usuários, produtos, pedidos.
- Implementar validações de domínio e regras de negócio.
- Definir tabelas de auditoria e eventos críticos.
4. **Autenticação, Autorização & RBAC (Semana 3)**
- Consolidar fluxo de login, refresh e logout com cookies httpOnly.
- Validar RBAC por nível de acesso (admin, seller, buyer).
- Revisar políticas de senha, rate-limit e bloqueio por tentativas.
- Garantir rota /auth/me para identificar o usuário em todas as apps.
5. **Catálogo & Estoque (Semana 3-4)**
- CRUD de produtos, lotes, validades e preços.
- Regras de disponibilidade e visibilidade por empresa.
- Importação de catálogo e validação de compliance.
6. **Carrinho & Pedido (Semana 4-5)**
- Fluxo completo: carrinho → pedido → status.
- Regras de frete, endereços e múltiplos fornecedores.
- Cálculo de impostos e condições comerciais.
7. **Pagamentos & Comissionamento (Semana 5-6)**
- Integração Mercado Pago com split.
- Webhooks, antifraude básico e reconciliação.
- Simulações de chargeback e cancelamento.
8. **Logística & Notificações (Semana 6-7)**
- Integração de tracking, status de entrega.
- Notificações por email e eventos internos.
- Templates de comunicação e fallback de envio.
9. **Segurança & Compliance (Semana 7-8)**
- Revisão de autenticação/autorização e hardening de endpoints.
- Auditoria de ações, LGPD e retenção de dados.
- Checklist de segurança (OWASP Top 10).
10. **Testes & Hardening (Semana 8-9)**
- Cobertura mínima: unit/integration tests.
- Testes de carga nos endpoints críticos.
- Correções finais e documentação técnica.
- Validação com QA e testes de regressão.
11. **Operação Assistida & Go-live (Semana 9-10)**
- Checklist de release e rollback.
- Monitoramento e plano de suporte pós-lançamento.
- Treinamento de operação e documentação para suporte.
---
### 📊 Indicadores de Sucesso (KPIs)
- **Cobertura de testes** mínima (>= 70% endpoints críticos).
- **SLA** de resposta: < 500ms em endpoints principais.
- **Erros críticos** < 1% por release.
- **Tempo de ciclo** por módulo: <= 2 semanas.
## 📦 Componentes do Projeto
### 1. **backend** - API de Alta Performance (Go)
**Propósito**: Núcleo de performance para operações críticas
**Tecnologias**: Go 1.24, PostgreSQL, Swagger
**Porta**: 8080
**Principais Funcionalidades**:
- Gestão de empresas (farmácias, distribuidoras)
- Catálogo de produtos com lote e validade
- Processamento de pedidos
- Integração Mercado Pago com split de pagamento
- Respostas JSON otimizadas com compressão gzip
**Documentação**: [backend/README.md](./backend/README.md)
**Como executar**:
```bash
cd backend
export DATABASE_URL=postgres://postgres:postgres@localhost:5432/saveinmed?sslmode=disable
go run ./cmd/api
```
---
### 2. **backoffice** - Sistema Administrativo (NestJS)
**Propósito**: Interface de gestão e administração
**Tecnologias**: NestJS 10, Fastify, Prisma, PostgreSQL
**Porta**: 3000
**Principais Funcionalidades**:
- Autenticação JWT (access + refresh tokens)
- Gestão de usuários e permissões
- Controle de inventário
- Processamento de webhooks Mercado Pago
- Dashboard administrativo
**Documentação**: [backoffice/README.md](./backoffice/README.md)
**Como executar**:
```bash
cd backoffice
pnpm install
pnpm prisma:generate
pnpm start:dev
```
---
### 3. **marketplace** - Frontend do Marketplace (React)
**Propósito**: Interface do marketplace B2B
**Tecnologias**: React 18, Vite 5, TailwindCSS, Zustand
**Porta**: 5173
**Principais Funcionalidades**:
- Catálogo de produtos com virtualização
- Carrinho de compras
- Checkout com Mercado Pago
- Dashboard de pedidos
- Autenticação e rotas protegidas
**Documentação**: [marketplace/README.md](./marketplace/README.md)
**Como executar**:
```bash
cd marketplace
npm install
npm run dev
```
---
### 5. **saveinmed-frontend** - Frontend Principal (Next.js)
**Propósito**: Aplicação frontend completa e principal
**Tecnologias**: Next.js 15, React 19, TailwindCSS 4, Appwrite
**Porta**: 3000
**Principais Funcionalidades**:
- Interface completa para farmácias e distribuidoras
- Gestão de catálogo de produtos
- Sistema de pedidos e pagamentos
- Dashboard com gráficos (Chart.js)
- Integração Appwrite para backend
- Checkout Mercado Pago
- Envio de emails (Nodemailer)
**Documentação**: [saveinmed-frontend/README.md](./saveinmed-frontend/README.md)
**Como executar**:
```bash
cd saveinmed-frontend
npm install
npm run dev
```
---
### 6. **website** - Site Institucional (Fresh/Deno)
**Propósito**: Landing pages e marketing
**Tecnologias**: Fresh v2, Deno 2, Preact, TailwindCSS
**Porta**: 8000
**Principais Funcionalidades**:
- Landing pages institucionais
- Captura de leads
- Blog e conteúdo educacional
- SEO otimizado
- Islands Architecture (hidratação parcial)
**Documentação**: [website/README.md](./website/README.md)
**Como executar**:
```bash
cd website
deno task dev
```
---
## 🛠️ Tecnologias Utilizadas
### Backend
| Componente | Linguagem | Framework | Banco de Dados |
|------------|-----------|-----------|----------------|
| **backend** | Go 1.24 | - | PostgreSQL |
| **backoffice** | TypeScript | NestJS 10 + Fastify | PostgreSQL (Prisma) |
### Frontend
| Componente | Framework | Versão | Estilização |
|------------|-----------|--------|-------------|
| **marketplace** | React + Vite | 18 + 5 | TailwindCSS 3 |
| **saveinmed-frontend** | Next.js | 15 | TailwindCSS 4 |
| **website** | Fresh (Deno) | v2 | TailwindCSS |
### Banco de Dados
O schema completo do banco de dados está documentado em [docs/database-schema.md](./docs/database-schema.md).
**Principais Tabelas**:
- `companies` - Farmácias e distribuidoras
- `users` - Usuários vinculados às empresas
- `products` - Catálogo de produtos
- `orders` / `order_items` - Pedidos e itens
- `cart_items` - Carrinho de compras
- `reviews` - Avaliações
- `shipments` - Envios
### Infraestrutura e Serviços
- **Banco de Dados**: PostgreSQL 14+
- **BaaS**: Appwrite 18
- **Pagamentos**: Mercado Pago SDK
- **Geocoding**: Mapbox API
- **Email**: Nodemailer
- **Containerização**: Docker
- **Documentação**: Swagger/OpenAPI
---
## 🚀 Setup Completo
### Pré-requisitos
- **Go** 1.24+
- **Node.js** 20+
- **Python** 3.12+
- **Deno** 2.0+
- **PostgreSQL** 14+
- **pnpm** 8+ (para backoffice)
- **Docker** (opcional)
### 1. Clonar o Repositório
```bash
git clone https://github.com/rede5/saveinmed.git
cd saveinmed
```
### 2. Configurar Banco de Dados
```bash
# Criar banco de dados PostgreSQL
createdb saveinmed
# Ou via Docker
docker run --name saveinmed-postgres \
-e POSTGRES_PASSWORD=postgres \
-e POSTGRES_DB=saveinmed \
-p 5432:5432 \
-d postgres:14
```
### 3. Configurar Variáveis de Ambiente
Cada componente possui um arquivo `.env.example`. Copie e configure:
```bash
# Backend Go
cd backend
cp .env.example .env
# Edite .env com suas configurações
# Backoffice NestJS
cd ../backoffice
cp .env.example .env
# Edite .env com suas configurações
# E assim por diante para cada componente...
```
### 4. Instalar Dependências
```bash
# Backend Go
cd backend
go mod download
# Backoffice NestJS
cd ../backoffice
pnpm install
pnpm prisma:generate
pnpm prisma migrate dev
# Marketplace React
cd ../marketplace
npm install
# SaveInMed Frontend Next.js
cd ../saveinmed-frontend
npm install
# Website Fresh/Deno
cd ../website
# Deno não requer instalação de dependências
```
### 5. Executar Todos os Serviços
**Opção 1: Manualmente (em terminais separados)**
```bash
# Terminal 1 - Backend Go
cd backend && go run ./cmd/api
# Terminal 2 - Backoffice NestJS
cd backoffice && pnpm start:dev
# Terminal 3 - Marketplace React
cd marketplace && npm run dev
# Terminal 5 - SaveInMed Frontend
cd saveinmed-frontend && npm run dev
# Terminal 6 - Website
cd website && deno task dev
```
**Opção 2: Docker Compose (em desenvolvimento)**
```bash
docker-compose up
```
### 6. Acessar as Aplicações
| Serviço | URL | Descrição |
|---------|-----|-----------|
| Backend API | http://localhost:8080 | API Go |
| Backend Swagger | http://localhost:8080/docs/index.html | Docs API Go |
| Backoffice | http://localhost:3000 | Admin NestJS |
| Backoffice Swagger | http://localhost:3000/api | Docs NestJS |
| Marketplace | http://localhost:5173 | Frontend React |
| SaveInMed Frontend | http://localhost:3000 | Frontend Next.js |
| Website | http://localhost:8000 | Site Fresh/Deno |
---
## 💻 Fluxo de Desenvolvimento
### 1. Criar Nova Feature
```bash
# Criar branch
git checkout -b feature/nome-da-feature
# Desenvolver...
# Testar...
# Commit
git add .
git commit -m "feat: adiciona nova funcionalidade X"
# Push
git push origin feature/nome-da-feature
# Criar Pull Request no GitHub
```
### 2. Padrões de Commit
Seguimos [Conventional Commits](https://www.conventionalcommits.org/):
- `feat:` - Nova funcionalidade
- `fix:` - Correção de bug
- `docs:` - Documentação
- `style:` - Formatação
- `refactor:` - Refatoração
- `test:` - Testes
- `chore:` - Tarefas de build/config
### 3. Testes
```bash
# Backend Go
cd backend && go test ./...
# Backoffice NestJS
cd backoffice && pnpm test
# Frontend Next.js
cd saveinmed-frontend && npm test
```
### 4. Linting
```bash
# Backend Go
cd backend && golangci-lint run
# Backoffice NestJS
cd backoffice && pnpm lint
# Marketplace React
cd marketplace && npm run lint
# Frontend Next.js
cd saveinmed-frontend && npm run lint
```
---
## 🚢 Deploy
### Backend (Go)
```bash
# Build
cd backend
go build -o bin/api ./cmd/api
# Docker
docker build -t saveinmed-api:latest .
docker push registry.example.com/saveinmed-api:latest
```
### Backoffice (NestJS)
```bash
# Build
cd backoffice
pnpm build
# Docker
docker build -t saveinmed-backoffice:latest .
docker push registry.example.com/saveinmed-backoffice:latest
```
### Marketplace (React)
```bash
# Build
cd marketplace
npm run build
# Deploy para Vercel/Netlify
vercel --prod
```
### SaveInMed Frontend (Next.js)
```bash
# Build
cd saveinmed-frontend
npm run build
# Deploy para Vercel
vercel --prod
```
### Website (Fresh/Deno)
```bash
# Deploy para Deno Deploy
cd website
deployctl deploy --project=saveinmed-website
```
---
## 🤝 Contribuindo
1. Fork o projeto
2. Crie uma branch para sua feature (`git checkout -b feature/AmazingFeature`)
3. Commit suas mudanças (`git commit -m 'feat: Add some AmazingFeature'`)
4. Push para a branch (`git push origin feature/AmazingFeature`)
5. Abra um Pull Request
### Diretrizes
- Escreva testes para novas funcionalidades
- Mantenha a documentação atualizada
- Siga os padrões de código de cada linguagem
- Use Conventional Commits
- Revise seu próprio código antes de submeter PR
---
## 📄 Licença
Este projeto está licenciado sob a Licença MIT - veja o arquivo [LICENSE](LICENSE) para detalhes.
---
## 📞 Contato
**SaveInMed Team**
- Website: https://saveinmed.com
- Email: contato@saveinmed.com
- GitHub: https://github.com/rede5/saveinmed
---
## 🙏 Agradecimentos
- Equipe de desenvolvimento
- Contribuidores open source
- Comunidades Go, NestJS, React, Python, e Deno
---
**Desenvolvido com ❤️ pela equipe SaveInMed**
Reference in a new issue View git blame Copy permalink