CARONTE v1.0 - Plataforma de Gestão Social

2026-02-08 23:10:32 -03:00
commit c98c806865
60 changed files with 9450 additions and 0 deletions
--- a/docs/CARONTE-Manual-Tecnico.md
+++ b/docs/CARONTE-Manual-Tecnico.md
@@ -0,0 +1,365 @@
+# CARONTE — Manual Técnico v1.0
+
+> 🚣 "O barqueiro que guia famílias pelo rio burocrático pós-óbito"
+
+---
+
+## 1. Visão Geral da Arquitetura
+
+O CARONTE é uma aplicação web full-stack composta por:
+
+| Camada | Tecnologia | Porta Padrão |
+|--------|-----------|-------------|
+| **Frontend** | Next.js 14 (App Router) + React 18 + Tailwind CSS | 3102 |
+| **Backend** | FastAPI (Python 3.12) + SQLAlchemy Async | 8102 |
+| **Banco de Dados** | PostgreSQL (produção) / SQLite (desenvolvimento) | 5432 |
+| **Proxy Reverso** | Nginx + Cloudflare | 80/443 |
+| **Process Manager** | PM2 | — |
+
+### Diagrama de Arquitetura
+
+```
+[Cloudflare CDN/DNS]
+        ↓
+    [Nginx :80]
+     ├── /api/*  → FastAPI :8102
+     └── /*      → Next.js :3102
+                      ↓
+               [PostgreSQL :5432]
+```
+
+---
+
+## 2. Estrutura de Pastas
+
+```
+caronte/
+├── backend/
+│   ├── app/
+│   │   ├── main.py              # Entry point FastAPI
+│   │   ├── __init__.py
+│   │   ├── api/v1/              # Rotas da API
+│   │   │   ├── auth.py          # Autenticação (registro, login, /me)
+│   │   │   ├── familias.py      # CRUD famílias, membros, falecidos
+│   │   │   ├── checklist.py     # Checklist burocrático
+│   │   │   ├── beneficios.py    # Scanner de benefícios
+│   │   │   ├── documentos.py    # Geração de documentos PDF
+│   │   │   └── dashboard.py     # Dashboard consolidado
+│   │   ├── core/
+│   │   │   ├── config.py        # Configurações (Pydantic Settings)
+│   │   │   ├── database.py      # Engine SQLAlchemy async
+│   │   │   └── security.py      # JWT, bcrypt, OAuth2
+│   │   ├── models/              # Modelos SQLAlchemy
+│   │   │   ├── usuario.py
+│   │   │   ├── familia.py       # Familia + MembroFamilia
+│   │   │   ├── falecido.py
+│   │   │   ├── checklist.py
+│   │   │   ├── beneficio.py
+│   │   │   └── documento.py
+│   │   ├── schemas/
+│   │   │   └── schemas.py       # Pydantic schemas (request/response)
+│   │   ├── services/
+│   │   │   ├── checklist_engine.py    # Geração automática de checklist
+│   │   │   ├── beneficio_scanner.py   # Scanner de benefícios elegíveis
+│   │   │   └── document_generator.py  # Geração de PDFs (ReportLab)
+│   │   └── data/
+│   │       └── checklist_templates.json  # Templates de checklist
+│   ├── uploads/                 # PDFs gerados
+│   ├── requirements.txt
+│   └── seed_data.py
+├── frontend/
+│   ├── src/
+│   │   ├── app/
+│   │   │   ├── layout.js        # Layout global
+│   │   │   ├── page.js          # Página inicial
+│   │   │   ├── login/page.js
+│   │   │   ├── registro/page.js
+│   │   │   ├── dashboard/page.js
+│   │   │   └── familia/[id]/
+│   │   │       ├── page.js          # Detalhe da família
+│   │   │       ├── checklist/page.js
+│   │   │       ├── beneficios/page.js
+│   │   │       └── documentos/page.js
+│   │   ├── components/
+│   │   │   └── Sidebar.js
+│   │   └── lib/
+│   │       └── api.js           # Cliente HTTP para a API
+│   ├── package.json
+│   ├── tailwind.config.js
+│   └── postcss.config.js
+├── docs/                        # Documentação
+├── start-backend.sh
+└── start-frontend.sh
+```
+
+---
+
+## 3. Modelos de Dados
+
+### 3.1 Usuario
+| Campo | Tipo | Descrição |
+|-------|------|-----------|
+| id | Integer (PK) | Auto-increment |
+| nome | String | Nome completo |
+| email | String (unique) | Email de login |
+| senha_hash | String | Hash bcrypt |
+| telefone | String (nullable) | Telefone |
+| created_at | DateTime | Auto |
+
+### 3.2 Familia
+| Campo | Tipo | Descrição |
+|-------|------|-----------|
+| id | Integer (PK) | Auto-increment |
+| nome | String | Nome da família |
+| usuario_id | Integer (FK) | Usuário responsável |
+| created_at | DateTime | Auto |
+
+### 3.3 MembroFamilia
+| Campo | Tipo | Descrição |
+|-------|------|-----------|
+| id | Integer (PK) | Auto-increment |
+| familia_id | Integer (FK) | Família |
+| nome | String | Nome do membro |
+| parentesco | String | Grau de parentesco |
+| cpf, telefone, email | String (nullable) | Dados de contato |
+
+### 3.4 Falecido
+| Campo | Tipo | Descrição |
+|-------|------|-----------|
+| id | Integer (PK) | Auto-increment |
+| familia_id | Integer (FK) | Família |
+| nome | String | Nome completo |
+| cpf | String (nullable) | CPF |
+| data_nascimento | Date (nullable) | Nascimento |
+| data_obito | Date | Data do óbito |
+| causa_obito | String (nullable) | Causa |
+| tipo_vinculo | String | empregado, aposentado, autonomo, servidor |
+| empregador | String (nullable) | Nome do empregador |
+| tinha_carteira_assinada | Integer | 0/1 |
+| tinha_fgts | Integer | 0/1 |
+| era_aposentado | Integer | 0/1 |
+| tinha_seguro_vida | Integer | 0/1 |
+| tinha_imoveis | Integer | 0/1 |
+| tinha_veiculos | Integer | 0/1 |
+| salario_estimado | Float (nullable) | Último salário |
+
+### 3.5 ChecklistItem
+| Campo | Tipo | Descrição |
+|-------|------|-----------|
+| id | Integer (PK) | Auto-increment |
+| familia_id | Integer (FK) | Família |
+| falecido_id | Integer (FK) | Falecido |
+| titulo | String | Título da tarefa |
+| descricao | Text (nullable) | Descrição detalhada |
+| fase | String | imediato, primeira_semana, 30_dias, 60_dias |
+| categoria | String | certidoes, inss, fgts, inventario... |
+| status | String | pendente, andamento, concluido |
+| prazo_dias | Integer (nullable) | Prazo em dias |
+| ordem | Integer | Ordem de execução |
+| dependencia_id | Integer (nullable) | Item que precede |
+
+### 3.6 Beneficio
+| Campo | Tipo | Descrição |
+|-------|------|-----------|
+| id | Integer (PK) | Auto-increment |
+| familia_id | Integer (FK) | Família |
+| falecido_id | Integer (FK) | Falecido |
+| tipo | String | fgts, pis, pensao_morte, seguro_vida, rescisao |
+| nome | String | Nome do benefício |
+| descricao | String (nullable) | Descrição |
+| status | String | identificado, em_processo, sacado |
+| valor_estimado | Float (nullable) | Valor estimado |
+| valor_sacado | Float (nullable) | Valor efetivamente sacado |
+
+### 3.7 Documento
+| Campo | Tipo | Descrição |
+|-------|------|-----------|
+| id | Integer (PK) | Auto-increment |
+| familia_id | Integer (FK) | Família |
+| falecido_id | Integer (FK, nullable) | Falecido |
+| tipo | String | procuracao, requerimento_fgts, peticao_pensao |
+| nome | String | Nome do documento |
+| arquivo_path | String (nullable) | Caminho do PDF |
+| status | String | gerado, enviado, aprovado |
+
+---
+
+## 4. API — Endpoints
+
+Base URL: `/api/v1`
+
+### 4.1 Autenticação
+
+| Método | Endpoint | Descrição | Auth |
+|--------|----------|-----------|------|
+| POST | `/auth/registro` | Criar conta | ❌ |
+| POST | `/auth/login` | Login (OAuth2 form) → JWT | ❌ |
+| GET | `/auth/me` | Dados do usuário logado | ✅ |
+
+### 4.2 Famílias
+
+| Método | Endpoint | Descrição | Auth |
+|--------|----------|-----------|------|
+| GET | `/familias/` | Listar famílias do usuário | ✅ |
+| POST | `/familias/` | Criar família | ✅ |
+| GET | `/familias/{id}` | Detalhe da família | ✅ |
+| POST | `/familias/{id}/membros` | Adicionar membro | ✅ |
+| GET | `/familias/{id}/membros` | Listar membros | ✅ |
+| POST | `/familias/{id}/falecido` | Registrar falecido (gera checklist + benefícios) | ✅ |
+| GET | `/familias/{id}/falecidos` | Listar falecidos | ✅ |
+
+### 4.3 Checklist
+
+| Método | Endpoint | Descrição | Auth |
+|--------|----------|-----------|------|
+| GET | `/familias/{id}/checklist/` | Listar itens do checklist | ✅ |
+| PUT | `/familias/{id}/checklist/{item_id}` | Atualizar status | ✅ |
+| GET | `/familias/{id}/checklist/proximo` | Próximo passo recomendado | ✅ |
+
+### 4.4 Benefícios
+
+| Método | Endpoint | Descrição | Auth |
+|--------|----------|-----------|------|
+| GET | `/familias/{id}/beneficios/` | Listar benefícios | ✅ |
+| POST | `/familias/{id}/beneficios/scan` | Re-escanear benefícios | ✅ |
+
+### 4.5 Documentos
+
+| Método | Endpoint | Descrição | Auth |
+|--------|----------|-----------|------|
+| GET | `/familias/{id}/documentos/` | Listar documentos | ✅ |
+| POST | `/familias/{id}/documentos/gerar` | Gerar PDF | ✅ |
+| GET | `/familias/{id}/documentos/{doc_id}/download` | Download PDF | ✅ |
+
+**Tipos de documento suportados:** `procuracao`, `requerimento_fgts`, `peticao_pensao`
+
+### 4.6 Dashboard
+
+| Método | Endpoint | Descrição | Auth |
+|--------|----------|-----------|------|
+| GET | `/dashboard/` | Resumo consolidado do usuário | ✅ |
+
+---
+
+## 5. Autenticação
+
+- **Método:** JWT Bearer Token (OAuth2 Password Flow)
+- **Hash:** bcrypt via passlib
+- **Algoritmo:** HS256
+- **Expiração:** 1440 minutos (24h)
+- **Header:** `Authorization: Bearer <token>`
+
+---
+
+## 6. Variáveis de Ambiente
+
+| Variável | Descrição | Padrão |
+|----------|-----------|--------|
+| `DATABASE_URL` | URL de conexão ao banco | `sqlite+aiosqlite:///./caronte.db` |
+| `SECRET_KEY` | Chave secreta para JWT | `caronte-secret-key-change-in-production` |
+| `ALGORITHM` | Algoritmo JWT | `HS256` |
+| `ACCESS_TOKEN_EXPIRE_MINUTES` | Expiração do token | `1440` |
+| `UPLOAD_DIR` | Diretório de uploads | `./uploads` |
+
+**Produção (PostgreSQL):**
+```
+DATABASE_URL=postgresql+asyncpg://caronte:Caronte2026!@localhost:5432/caronte
+```
+
+> ⚠️ Para PostgreSQL, adicionar `asyncpg` ao requirements.txt e usar driver `postgresql+asyncpg://`
+
+---
+
+## 7. Requisitos de Sistema
+
+### Backend
+- Python 3.12+
+- Dependências: FastAPI, SQLAlchemy, aiosqlite/asyncpg, python-jose, passlib, reportlab, pydantic-settings
+
+### Frontend
+- Node.js 18+
+- Next.js 14, React 18, Tailwind CSS, lucide-react
+
+### Produção
+- Ubuntu 22.04+ / Debian 12+
+- PostgreSQL 15+
+- Nginx
+- PM2 (Node.js process manager)
+- Cloudflare (DNS + CDN)
+
+---
+
+## 8. Deploy de Produção
+
+### 8.1 Backend
+```bash
+cd /opt/caronte/backend
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+pip install asyncpg  # driver PostgreSQL
+
+# Criar .env
+echo 'DATABASE_URL=postgresql+asyncpg://caronte:Caronte2026!@localhost:5432/caronte' > .env
+echo 'SECRET_KEY=<gerar-chave-segura>' >> .env
+
+# Iniciar com PM2
+pm2 start "source .venv/bin/activate && uvicorn app.main:app --host 0.0.0.0 --port 8102" --name caronte-backend
+```
+
+### 8.2 Frontend
+```bash
+cd /opt/caronte/frontend
+npm install
+npm run build   # NUNCA usar next dev em produção
+pm2 start "npm start -- -p 3102" --name caronte-frontend
+```
+
+### 8.3 Nginx
+```nginx
+server {
+    listen 80;
+    server_name caronte.aivertice.com;
+
+    location /api/ {
+        proxy_pass http://127.0.0.1:8102/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    location / {
+        proxy_pass http://127.0.0.1:3102;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+---
+
+## 9. Serviços Inteligentes
+
+### 9.1 Checklist Engine
+Ao registrar um falecido, o sistema gera automaticamente um checklist burocrático personalizado baseado no perfil (tipo de vínculo, tinha FGTS, era aposentado, etc.). Os templates são carregados de `checklist_templates.json` e filtrados por condições.
+
+### 9.2 Benefício Scanner
+Analisa o perfil do falecido e identifica automaticamente benefícios elegíveis:
+- **FGTS** (se tinha FGTS) — estimativa: 3.5x salário
+- **PIS/PASEP** (se tinha carteira assinada) — estimativa: 0.8x salário
+- **Pensão por Morte** (sempre) — estimativa: 12x salário
+- **Seguro de Vida** (se tinha) — estimativa: 24x salário
+- **Verbas Rescisórias** (se tinha carteira assinada) — estimativa: 2x salário
+
+### 9.3 Document Generator
+Gera PDFs profissionais via ReportLab:
+- **Procuração** — representação perante órgãos
+- **Requerimento FGTS** — saque por falecimento (Lei 8.036/90)
+- **Petição Pensão por Morte** — requerimento INSS (Lei 8.213/91)
+
+---
+
+*Documento gerado em 08/02/2026 — CARONTE v1.0*