---
# System prepended metadata

title: Documento de Especificação Técnica

---

# Documento de Especificação Técnica

**Projeto: FaciMED - Plataforma de E-commerce Farmacêutico**

## Visão Geral

Este documento tem como objetivo descrever os aspectos técnicos, funcionais e estruturais do projeto FaciMED. A plataforma será voltada para a comercialização de produtos farmacêuticos e hospitalares, oferecendo aos usuários uma experiência de compra moderna, segura e eficiente, com funcionalidades robustas e integração com sistemas externos de pagamento e logística.

---

## 1. Funcionalidades da Aplicação

### 🔐 Autenticação e Cadastro

- [POST] `/auth/login` — Login via e-mail e senha.
- [POST] `/auth/social` — Login com Firebase (Google/Facebook).
- [POST] `/auth/recover` — Envio de e-mail de recuperação de senha.
- [POST] `/auth/reset` — Redefinição de senha com token.
- [POST] `/auth/register` — Criação de nova conta.
- [GET] `/auth/logout` — Logout do usuário autenticado.

### 👤 Usuário

- [GET] `/user/profile` — Detalhes do usuário (dados, endereço, pedidos, cartões, autenticação).

### 🛍 Produtos e Catálogo

- [GET] `/categories` — Todas as categorias e subcategorias com contagem de produtos.
- [GET] `/products/best-sellers` — Lista de produtos mais vendidos.
- [GET] `/products/offers` — Lista de produtos em oferta.
- [GET] `/products/search` — Busca por produtos com filtros:
  - Categoria (ex: antibióticos, anti-inflamatórios)
  - Tipo de uso (cápsulas, comprimidos)
  - Tipo de medicamento (genérico, similar)
  - Classificação (tarja vermelha, preta)
  - Faixa de preço
- [GET] `/products/:id` — Detalhes do produto (descrição, similares, especificações).
- [POST] `/products/restock-notify` — Notificações de reestoque.
- [GET] `/products/popular-searches` — Produtos mais pesquisados.
- [GET] `/brands` — Lista de marcas.

### ❤️ Favoritos

- [POST] `/favorites` — Adicionar produto aos favoritos.
- [DELETE] `/favorites/:id` — Remover produto dos favoritos.
- [GET] `/favorites` — Listar favoritos com filtro de categorias.

### 🛒 Carrinho de Compras

- [POST] `/cart` — Adicionar produto ao carrinho.
- [DELETE] `/cart/:id` — Remover item do carrinho.
- [GET] `/cart` — Listar itens do carrinho.
- [POST] `/cart/coupon` — Aplicar cupom de desconto.

### 🚚 Frete e Entrega

- [POST] `/shipping/calculate` — Cálculo de frete com base no CEP.

### 📦 Pedidos

- [POST] `/orders/address` — Criação de endereço e contato para entrega.
- [POST] `/orders/subscription` — Criar pedido de compra recorrente.
- [GET] `/orders/:id` — Detalhes do pedido.

### 🧲 Geração de Leads

- [POST] `/leads` — Captura de leads para receber ofertas e promoções.
- [CRON] Disparo automático de e-mail para leads.

---

## 2. Arquitetura Técnica

### 🏗️ Infraestrutura

- **Hospedagem:** Amazon Web Services (AWS)
- **Banco de dados:** PostgreSQL (relacional)
- **Cache e logs:** Redis

### 🧠 Backend

- **Framework:** NestJS (API Routes)
- **Autenticação:** JWT (com planos futuros de SSO com Firebase)
- **Gerenciamento de logs:** Sentry e Grafana Loki
- **Monitoramento de uso e interações:** Grafana

### 🧪 Qualidade de Código e Testes

- Testes apenas em lugares críticos (ex: autenticação, pagamentos)
- **Testes integrados e E2E:** Utilização de Jest (com possibilidade futura de Cypress/Playwright)
- **Cobertura mínima de testes:** 80%
- **Pipeline CI/CD:** GitHub Actions com deploy contínuo
- **Ambiente de deploy:** Docker com orquestração via Kubernetes

---

## 3. Integrações Externas

| Sistema            | Finalidade                                |
| ------------------ | ----------------------------------------- |
| **Mercado pago ou Pagbank**         | Processamento de pagamentos               |
| **Infarma**        | Consulta de estoque e geração de pedidos  |
| **Firebase Auth**  | Login com redes sociais (Google/Facebook) |
| **Transportadora** | Consulta e cálculo de frete via webhooks  |
| **cloudflare** | Integrar o "não sou um robô" |

---

## 4. Segurança e Conformidade

- Conformidade com a **LGPD** (Lei Geral de Proteção de Dados)
- Implementação de proteções contra **XSS**, **CSRF**, e **SQL Injection**
- Dados sensíveis (como cartões) armazenados de forma segura (criptografados)
- Logs auditáveis e segregados por níveis com Redis e Sentry
- Implementação de token JWT com refresh e expiração configurada
- Regras de Web Application Firewall atráves da Cloudflare

---

## 5. Performance e Escalabilidade

- Cache de páginas e buscas via Redis para reduzir carga no banco
- Load Balancer para distribuir a carga entre as instâncias de container

---

## 6. Estratégia de Monitoramento e Rollback

- **Monitoramento contínuo:** Sentry e Grafana
- **Logs estruturados:** Redis + Sentry com envio de alertas automatizados
- **Rollback:** Política de rollback imediato via deploy de versão anterior em caso de falha crítica

---

## 7. Estratégia de Pagamento

- Módulo de pagamento com suporte a:
  - Cartão de crédito (com parcelamento)
  - PIX (integração futura)
  - Boleto bancário
- Registro seguro dos dados do cartão (com tokenização e criptografia)
- Geração de comprovante e nota de pedido finalizado

---

## 8. Cronograma Inicial do Projeto

| Etapa Técnica                    | Status          | Observações                      |
| -------------------------------- | --------------- | -------------------------------  |
| Levantamento de requisitos       | ✅ Concluído    | Documentado com cliente          |
| Documentação técnica inicial     | ✅ Em andamento | Versão atual (v1.0)              |
| Desenvolvimento Backend          | ⏳ Pendente     | Início previsto após validação   |
| Integração com Stripe e Infarma  | ⏳ Pendente     | Depende de acesso às credenciais |
| Implementação Frontend (Next.js) | ⏳ Pendente     | Com base nas telas do Figma      |
| Deploy em produção               | ⏳ Pendente     | AWS + Docker + CI/CD             |

---

## 9. Dúvidas Frequentes (FAQ)

<!-- ### ❓ Como as coisas serão feitas? -->

### 🔗 Como será feita a conexão com o sistema da Infarma e o e-commerce?

A integração será realizada por meio de um processo **ETL (Extract, Transform, Load)**, onde os dados serão:

1. **Extraídos** do sistema da Infarma (diretamente do banco de dados ou via API, se disponível);
2. **Transformados** para adequar as informações ao formato necessário para o e-commerce (ajustes de estrutura, validações, tratamentos de dados);
3. **Carregados** no e-commerce, garantindo a sincronização de dados como estoque, pedidos e produtos.

A liberdade operacional é bastante ampla, permitindo configurar, automatizar e controlar esse processo conforme a necessidade do negócio.

🚩 **Ponto crítico:**
Para definir exatamente como esse ETL vai funcionar, é fundamental entender **qual é o nível de acesso disponível ao banco de dados da Infarma**. Dependendo desse acesso, podemos escolher entre:

- Conexões diretas ao banco (acesso mais completo e flexível);
- Consumo de APIs, se existirem;
- Alternativas como exportação de arquivos (CSV, XML) e automações periódicas.

<!-- ### 📦 Como funcionará a gestão de sistemas e estoques?

### 🔌 Como será feita a integração técnica? -->

### 💰 Qual o custo mensal com hospedagem e infraestrutura?
O valor pode variar conforme a escolha dos planos de hospedagem e tempo de contrato. A seguir, algumas estimativas com base na AWS:

---

## 💻 Cenários de Infraestrutura na AWS

### 🟩 **Infraestrutura Básica**
- **Descrição:** Infraestrutura mínima usando **3 VMs na AWS + 1 RDS**, sem considerar backup e monitoramento (ex.: CloudWatch).
- **Valor estimado:**  
![Imagem](https://hackmd.io/_uploads/BJVecQRWlg.jpg)
`118.04 USD por mês & 1,416.48 USD por ano`

---

### 🟦 **Contrato Anual (Economia significativa)**
- **Descrição:** Ao pagar **U$ 264,11 adiantado** e firmar contrato de **1 ano**, o custo mensal reduz consideravelmente.
- **Valor estimado:**  
![Imagem](https://hackmd.io/_uploads/HJpW97RZgg.jpg)
`66.47 USD por mês & 1,061.75 USD por ano`
---

### 🟧 **Contrato Trienal (Mais recomendado)**
- **Descrição:** Ao optar por contrato de **3 anos**, o custo mensal diminui ainda mais. Basta multiplicar o valor apresentado por 3 para obter o total do período.
- **Valor estimado:**  
![Imagem](https://hackmd.io/_uploads/HkUQ5XA-lx.jpg)
`59.13 USD por mês & 1,237.79 USD por ano`

---

## Considerações Finais

Este documento representa a base técnica e funcional para o desenvolvimento do projeto FaciMED. A partir dele, será possível alinhar o escopo com as partes interessadas, mitigar riscos técnicos e acelerar a fase de implementação. Quaisquer alterações ou adições deverão ser registradas em versões futuras deste documento.

---
