Documentação Técnica Consolidada

Documento: Documentação Técnica do Sistema Sistema: Módulo Empreendedorismo Versão: 1.0 Data: Janeiro/2025

1. Visão Geral do Sistema

1.1. Descrição

O Módulo Empreendedorismo é uma plataforma web completa para gestão de planos de negócio, conectando empreendedores a agentes estruturadores, gestores e instituições financeiras. O sistema oferece funcionalidades de mentoria, análise de planos e recomendação de linhas de crédito.

1.2. Objetivos do Sistema

Facilitar a criação e gestão de planos de negócio
Conectar empreendedores a mentores qualificados
Fornecer acesso a linhas de crédito adequadas ao perfil
Gerar relatórios e métricas para gestores
Automatizar processos de notificação e comunicação

1.3. Stakeholders

Stakeholder	Papel	Interesse
Empreendedores	Usuário final	Criar e acompanhar planos de negócio
Agentes Estruturadores	Mentor	Orientar e acompanhar empreendedores
Gestores	Administrador	Supervisionar e gerar relatórios
Instituições Financeiras	Parceiro	Ofertar linhas de crédito
Equipe de TI	Suporte	Manter e evoluir o sistema

2. Arquitetura do Sistema

2.1. Diagrama de Arquitetura

                                    ┌─────────────────────────────────────────────┐
                                    │                   INTERNET                   │
                                    └──────────────────────┬──────────────────────┘
                                                           │
                                                           ▼
                                    ┌─────────────────────────────────────────────┐
                                    │              NGINX (Proxy Reverso)          │
                                    │           Porta 80/443 (HTTPS)              │
                                    └──────────────────────┬──────────────────────┘
                                                           │
                          ┌────────────────────────────────┼────────────────────────────────┐
                          │                                │                                │
                          ▼                                ▼                                ▼
            ┌─────────────────────────┐    ┌─────────────────────────┐    ┌─────────────────────────┐
            │        FRONTEND         │    │         BACKEND         │    │          MINIO          │
            │    React + TypeScript   │    │     Django + DRF        │    │    Object Storage       │
            │    Vite + MUI           │    │     Porta 8000          │    │    Porta 9000/9001      │
            │    Porta 9501           │    │                         │    │                         │
            └─────────────────────────┘    └────────────┬────────────┘    └─────────────────────────┘
                                                        │
                          ┌─────────────────────────────┼─────────────────────────────┐
                          │                             │                             │
                          ▼                             ▼                             ▼
            ┌─────────────────────────┐    ┌─────────────────────────┐    ┌─────────────────────────┐
            │       POSTGRESQL        │    │          REDIS          │    │         CELERY          │
            │    Banco de Dados       │    │     Cache + Broker      │    │   Workers Assíncronos   │
            │    Porta 5432           │    │     Porta 6379          │    │                         │
            └─────────────────────────┘    └─────────────────────────┘    └─────────────────────────┘

2.2. Padrão Arquitetural

O sistema segue uma arquitetura em camadas com separação clara de responsabilidades:

┌─────────────────────────────────────────────────────────────┐
│                    CAMADA DE APRESENTAÇÃO                   │
│  Frontend React - Interface do usuário, componentes MUI    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      CAMADA DE API                          │
│  Django REST Framework - Endpoints, Serializers, Views     │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   CAMADA DE NEGÓCIOS                        │
│  Services, Managers, Business Logic                         │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    CAMADA DE DADOS                          │
│  Models Django ORM, PostgreSQL                              │
└─────────────────────────────────────────────────────────────┘

2.3. Componentes do Sistema

2.3.1. Frontend (React)

Tecnologia	Versão	Finalidade
React	19.x	Framework UI
TypeScript	5.x	Tipagem estática
Vite	5.x	Build tool
Material-UI (MUI)	5.x	Componentes UI
Zustand	4.x	Gerenciamento de estado
React Router	6.x	Roteamento
Axios	1.x	Cliente HTTP
React Query	5.x	Cache e sincronização

Estrutura de Pastas:

frontend/src/
├── components/          # Componentes reutilizáveis
│   ├── common/         # Componentes genéricos
│   ├── forms/          # Componentes de formulário
│   └── layouts/        # Layouts de página
├── pages/              # Páginas/Views
├── services/           # Serviços de API
├── stores/             # Stores Zustand
├── hooks/              # Custom hooks
├── utils/              # Utilitários
├── types/              # Definições TypeScript
└── assets/             # Arquivos estáticos

2.3.2. Backend (Django)

Tecnologia	Versão	Finalidade
Python	3.11+	Linguagem
Django	5.x	Framework web
Django REST Framework	3.x	API REST
Celery	5.x	Tarefas assíncronas
django-cors-headers	4.x	CORS
djangorestframework-simplejwt	5.x	Autenticação JWT
drf-spectacular	0.27+	Documentação OpenAPI
Pillow	10.x	Processamento de imagens
boto3/minio	-	Storage S3/MinIO

Estrutura de Apps:

backend/
├── apps/
│   ├── accounts/              # Autenticação e usuários
│   ├── business_plans/        # Planos de negócio
│   ├── credit_lines/          # Linhas de crédito
│   ├── entrepreneurs/         # Empreendedores
│   ├── financial_institutions/# Instituições financeiras
│   ├── managers/              # Gestores
│   ├── notifications/         # Notificações
│   ├── reports/               # Relatórios
│   └── structuring_agents/    # Agentes estruturadores
├── core/                      # Configurações Django
│   ├── settings.py
│   ├── urls.py
│   ├── celery.py
│   └── management/commands/
└── templates/                 # Templates de email

2.3.3. Banco de Dados (PostgreSQL)

Configuração	Valor
Versão	16.x
Encoding	UTF-8
Collation	pt_BR.UTF-8
Max Connections	100

2.3.4. Cache e Message Broker (Redis)

Configuração	Valor
Versão	7.x (Alpine)
Databases	0: Celery, 1: Cache
Max Memory	256MB
Eviction Policy	allkeys-lru

2.3.5. Object Storage (MinIO)

Configuração	Valor
Bucket Principal	empreendedorismo
Política	Privado (acesso via presigned URLs)
Max File Size	100MB

3. Modelo de Dados

3.1. Diagrama ER Simplificado

┌─────────────────┐       ┌─────────────────────┐       ┌─────────────────────┐
│      User       │       │    Entrepreneur     │       │   BusinessPlan      │
├─────────────────┤       ├─────────────────────┤       ├─────────────────────┤
│ id              │──1:1──│ user_id (FK)        │──1:N──│ entrepreneur_id(FK) │
│ email           │       │ cpf                 │       │ name                │
│ password        │       │ phone               │       │ description         │
│ is_active       │       │ birth_date          │       │ activity_sector     │
│ user_type       │       │ created_at          │       │ stage               │
│ created_at      │       └─────────────────────┘       │ status              │
└─────────────────┘                                      │ created_at          │
        │                                                └─────────────────────┘
        │                                                         │
        │ 1:1                                                     │ 1:1
        ▼                                                         ▼
┌─────────────────────┐                               ┌─────────────────────┐
│  StructuringAgent   │                               │     Mentorship      │
├─────────────────────┤                               ├─────────────────────┤
│ user_id (FK)        │──────────────────────────────│ agent_id (FK)       │
│ institution         │                               │ business_plan_id    │
│ activity_area       │                               │ status              │
│ created_at          │                               │ started_at          │
└─────────────────────┘                               │ finished_at         │
                                                      └─────────────────────┘

┌─────────────────────┐       ┌─────────────────────┐
│ FinancialInstitution│       │     CreditLine      │
├─────────────────────┤       ├─────────────────────┤
│ id                  │──1:N──│ institution_id (FK) │
│ name                │       │ name                │
│ cnpj                │       │ description         │
│ email               │       │ min_value           │
│ created_at          │       │ max_value           │
└─────────────────────┘       │ interest_rate       │
                              │ requirements        │
                              └─────────────────────┘

3.2. Principais Entidades

3.2.1. User (accounts)

class User(AbstractUser):
    email = models.EmailField(unique=True)
    user_type = models.CharField(choices=UserType.choices)
    is_verified = models.BooleanField(default=False)
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

Tipos de Usuário:

ENTREPRENEUR: Empreendedor
STRUCTURING_AGENT: Agente Estruturador
MANAGER: Gestor
FINANCIAL_INSTITUTION: Instituição Financeira

3.2.2. BusinessPlan (business_plans)

class BusinessPlan(models.Model):
    entrepreneur = models.ForeignKey(Entrepreneur)
    name = models.CharField(max_length=200)
    description = models.TextField()
    activity_sector = models.CharField(choices=ActivitySector.choices)
    stage = models.CharField(choices=BusinessPlanStage.choices)
    target_audience = models.CharField(choices=TargetAudience.choices)
    status = models.CharField(choices=BusinessPlanStatus.choices)
    financing_option = models.CharField(choices=FinancingOption.choices)
    created_at = models.DateTimeField(auto_now_add=True)

Status do Plano:

DRAFT: Rascunho
PENDING: Pendente de análise
IN_ANALYSIS: Em análise
IN_MENTORSHIP: Em mentoria
APPROVED: Aprovado
REJECTED: Rejeitado

3.3. Enumerações (Choices)

Enum	Valores
ActivitySector	COMMERCE, INDUSTRY, SERVICES, AGRIBUSINESS
BusinessPlanStage	IDEA, VALIDATION, MVP, GROWTH, SCALE
TargetAudience	B2B, B2C, B2G, B2B2C
FinancingOption	BNDES, PRONAMPE, FAMPE, FINEP, OTHER
BusinessPlanStatus	DRAFT, PENDING, IN_ANALYSIS, IN_MENTORSHIP, APPROVED, REJECTED

4. API REST

4.1. Convenções

Base URL: /api/v1/
Autenticação: JWT (Bearer Token)
Formato: JSON
Paginação: ?page=1&page_size=20
Ordenação: ?ordering=-created_at
Filtros: ?status=approved&sector=services

4.2. Endpoints Principais

4.2.1. Autenticação

Método	Endpoint	Descrição
POST	`/api/v1/auth/register/`	Cadastro de usuário
POST	`/api/v1/auth/login/`	Login (retorna tokens)
POST	`/api/v1/auth/refresh/`	Renovar access token
POST	`/api/v1/auth/logout/`	Logout (invalidar token)
POST	`/api/v1/auth/password/reset/`	Solicitar reset de senha
POST	`/api/v1/auth/password/confirm/`	Confirmar nova senha

4.2.2. Empreendedores

Método	Endpoint	Descrição
GET	`/api/v1/entrepreneurs/`	Listar empreendedores
GET	`/api/v1/entrepreneurs/{id}/`	Detalhe do empreendedor
PUT	`/api/v1/entrepreneurs/{id}/`	Atualizar empreendedor
GET	`/api/v1/entrepreneurs/me/`	Perfil do empreendedor logado

4.2.3. Planos de Negócio

Método	Endpoint	Descrição
GET	`/api/v1/business-plans/`	Listar planos
POST	`/api/v1/business-plans/`	Criar plano
GET	`/api/v1/business-plans/{id}/`	Detalhe do plano
PUT	`/api/v1/business-plans/{id}/`	Atualizar plano
DELETE	`/api/v1/business-plans/{id}/`	Excluir plano
POST	`/api/v1/business-plans/{id}/submit/`	Enviar para análise
POST	`/api/v1/business-plans/{id}/request-mentorship/`	Solicitar mentoria

4.2.4. Mentorias

Método	Endpoint	Descrição
GET	`/api/v1/mentorships/`	Listar mentorias
POST	`/api/v1/mentorships/{id}/accept/`	Aceitar mentoria
POST	`/api/v1/mentorships/{id}/feedback/`	Enviar feedback
POST	`/api/v1/mentorships/{id}/complete/`	Finalizar mentoria

4.2.5. Linhas de Crédito

Método	Endpoint	Descrição
GET	`/api/v1/credit-lines/`	Listar linhas de crédito
GET	`/api/v1/credit-lines/{id}/`	Detalhe da linha
GET	`/api/v1/credit-lines/recommendations/`	Recomendações por perfil

4.3. Formato de Resposta

Sucesso (200/201):

{
  "id": 1,
  "name": "Meu Plano de Negócio",
  "status": "draft",
  "created_at": "2025-01-19T10:00:00Z"
}

Erro de Validação (400):

{
  "detail": "Validation error",
  "errors": {
    "name": ["Este campo é obrigatório."],
    "description": ["Mínimo de 50 caracteres."]
  }
}

Erro de Autenticação (401):

{
  "detail": "Token inválido ou expirado."
}

Erro de Permissão (403):

{
  "detail": "Você não tem permissão para esta ação."
}

5. Fluxos de Dados

5.1. Fluxo de Autenticação

┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐
│ Cliente │     │ Frontend│     │ Backend │     │   DB    │
└────┬────┘     └────┬────┘     └────┬────┘     └────┬────┘
     │               │               │               │
     │ 1. Login      │               │               │
     │──────────────>│               │               │
     │               │ 2. POST /auth/login           │
     │               │──────────────>│               │
     │               │               │ 3. Validate   │
     │               │               │──────────────>│
     │               │               │<──────────────│
     │               │ 4. JWT Tokens │               │
     │               │<──────────────│               │
     │ 5. Store tokens               │               │
     │<──────────────│               │               │
     │               │               │               │
     │ 6. Request com Bearer Token   │               │
     │──────────────>│               │               │
     │               │ 7. Verify JWT │               │
     │               │──────────────>│               │
     │               │ 8. Response   │               │
     │               │<──────────────│               │
     │ 9. Data       │               │               │
     │<──────────────│               │               │

5.2. Fluxo de Criação de Plano de Negócio

┌─────────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐
│Empreendedor │     │ Frontend│     │ Backend │     │  Celery │     │  MinIO  │
└──────┬──────┘     └────┬────┘     └────┬────┘     └────┬────┘     └────┬────┘
       │                 │               │               │               │
       │ 1. Preenche form│               │               │               │
       │────────────────>│               │               │               │
       │                 │ 2. Upload docs│               │               │
       │                 │───────────────────────────────────────────────>│
       │                 │               │               │ 3. Store file │
       │                 │<──────────────────────────────────────────────│
       │                 │ 4. POST /business-plans       │               │
       │                 │──────────────>│               │               │
       │                 │               │ 5. Validate + Save            │
       │                 │               │──────────────>│ (DB)          │
       │                 │               │ 6. Queue email task           │
       │                 │               │──────────────>│               │
       │                 │               │               │ 7. Send email │
       │                 │ 8. Response   │               │               │
       │                 │<──────────────│               │               │
       │ 9. Success      │               │               │               │
       │<────────────────│               │               │               │

5.3. Fluxo de Mentoria

┌─────────────┐     ┌─────────────┐     ┌─────────┐     ┌─────────┐
│Empreendedor │     │   Agente    │     │ Backend │     │   DB    │
└──────┬──────┘     └──────┬──────┘     └────┬────┘     └────┬────┘
       │                   │                 │               │
       │ 1. Request Mentorship               │               │
       │────────────────────────────────────>│               │
       │                   │                 │ 2. Create     │
       │                   │                 │──────────────>│
       │                   │ 3. Notify agent │               │
       │                   │<────────────────│               │
       │                   │                 │               │
       │                   │ 4. Accept       │               │
       │                   │────────────────>│               │
       │                   │                 │ 5. Update     │
       │                   │                 │──────────────>│
       │ 6. Notify empreendedor              │               │
       │<────────────────────────────────────│               │
       │                   │                 │               │
       │                   │ 7. Send feedback│               │
       │                   │────────────────>│               │
       │ 8. Receive feedback                 │               │
       │<────────────────────────────────────│               │
       │                   │                 │               │
       │                   │ 9. Complete     │               │
       │                   │────────────────>│               │
       │ 10. Mentorship completed            │               │
       │<────────────────────────────────────│               │

6. Segurança

6.1. Autenticação e Autorização

Aspecto	Implementação
Autenticação	JWT (JSON Web Tokens)
Refresh Token	7 dias de validade
Access Token	15 minutos de validade
Senha	Hash bcrypt (Django default)
Política de Senha	Mínimo 8 caracteres, alfanumérico

6.2. Permissões por Perfil

Recurso	Empreendedor	Agente	Gestor	Inst. Financeira
Planos próprios	CRUD	Read	Read All	-
Mentorias	Request	CRUD	Read All	-
Linhas de crédito	Read	Read	Read All	CRUD
Usuários	Self	Self	CRUD	Self
Relatórios	Own	Own	All	Own

6.3. Proteções Implementadas

CORS: Configurado para domínios autorizados
CSRF: Token em formulários
XSS: Sanitização de inputs
SQL Injection: Django ORM (queries parametrizadas)
Rate Limiting: Throttling em endpoints sensíveis
HTTPS: Obrigatório em produção
Headers de Segurança: X-Frame-Options, X-Content-Type-Options, etc.

7. Integração e Implantação

7.1. Ambientes

Ambiente	URL	Branch	Finalidade
Desenvolvimento	localhost	feature/*	Desenvolvimento local
Homologação	hml.dominio.com	develop	Testes e validação
Produção	dominio.com	main	Ambiente produtivo

7.2. Pipeline CI/CD

┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐
│  Push   │────>│  Lint   │────>│  Test   │────>│  Build  │────>│ Deploy  │
└─────────┘     └─────────┘     └─────────┘     └─────────┘     └─────────┘
                     │               │               │               │
                 ESLint          pytest        Docker build    docker-compose
                 Flake8       coverage > 80%   npm build          up -d
                 TypeScript

7.3. Containers Docker

Container	Imagem Base	Porta	Recursos
backend	python:3.11-slim	8000	1 CPU, 1GB RAM
frontend	node:20-alpine + nginx	9501	0.5 CPU, 512MB RAM
db	postgres:16	5432	1 CPU, 2GB RAM
redis	redis:7-alpine	6379	0.5 CPU, 256MB RAM
minio	minio/minio	9000/9001	0.5 CPU, 512MB RAM
celery-worker	python:3.11-slim	-	1 CPU, 1GB RAM
celery-worker-emails	python:3.11-slim	-	0.5 CPU, 512MB RAM

8. Monitoramento e Logs

8.1. Health Checks

Serviço	Endpoint	Intervalo
Backend	`/api/health/`	30s
Frontend	`/`	30s
PostgreSQL	`pg_isready`	30s
Redis	`PING`	30s
MinIO	`/minio/health/live`	30s

8.2. Métricas Monitoradas

Métrica	Limite Warning	Limite Critical
CPU	70%	90%
Memória	80%	95%
Disco	70%	85%
Tempo de resposta API	500ms	2000ms
Taxa de erro	0.1%	1%
Conexões DB	70%	90%

8.3. Estrutura de Logs

{
  "timestamp": "2025-01-19T10:30:00.000Z",
  "level": "INFO",
  "logger": "django.request",
  "message": "GET /api/v1/business-plans/",
  "request_id": "abc123",
  "user_id": 42,
  "method": "GET",
  "path": "/api/v1/business-plans/",
  "status_code": 200,
  "duration_ms": 45
}

9. Glossário

Termo	Definição
Empreendedor	Usuário que cria e gerencia planos de negócio
Agente Estruturador	Mentor que orienta empreendedores
Plano de Negócio	Documento que descreve uma ideia de negócio
Mentoria	Processo de acompanhamento entre agente e empreendedor
Linha de Crédito	Opção de financiamento oferecida por instituição
JWT	JSON Web Token - método de autenticação
RTO	Recovery Time Objective - tempo máximo de recuperação
RPO	Recovery Point Objective - perda máxima de dados

10. Referências

Fim do Documento

1. Visão Geral do Sistema​

1.1. Descrição​

1.2. Objetivos do Sistema​

1.3. Stakeholders​

2. Arquitetura do Sistema​

2.1. Diagrama de Arquitetura​

2.2. Padrão Arquitetural​

2.3. Componentes do Sistema​

2.3.1. Frontend (React)​

2.3.2. Backend (Django)​

2.3.3. Banco de Dados (PostgreSQL)​

2.3.4. Cache e Message Broker (Redis)​

2.3.5. Object Storage (MinIO)​

3. Modelo de Dados​

3.1. Diagrama ER Simplificado​

3.2. Principais Entidades​

3.2.1. User (accounts)​

3.2.2. BusinessPlan (business_plans)​

3.3. Enumerações (Choices)​

4. API REST​

4.1. Convenções​

4.2. Endpoints Principais​

4.2.1. Autenticação​

4.2.2. Empreendedores​

4.2.3. Planos de Negócio​

4.2.4. Mentorias​

4.2.5. Linhas de Crédito​

4.3. Formato de Resposta​

5. Fluxos de Dados​

5.1. Fluxo de Autenticação​

5.2. Fluxo de Criação de Plano de Negócio​

5.3. Fluxo de Mentoria​

6. Segurança​

6.1. Autenticação e Autorização​

6.2. Permissões por Perfil​

6.3. Proteções Implementadas​

7. Integração e Implantação​

7.1. Ambientes​

7.2. Pipeline CI/CD​

7.3. Containers Docker​

8. Monitoramento e Logs​

8.1. Health Checks​

8.2. Métricas Monitoradas​

8.3. Estrutura de Logs​

9. Glossário​

10. Referências​