Romã

Gestão de romaneios de entrega com assinatura digital — do papel ao tempo real.

O Romã controla o ciclo de vida de romaneios (guias de entrega de material): recebimento organizado em caixas por setor, assinatura digital no ato da retirada (nome + matrícula via canvas), notificação automática ao solicitante, relatórios exportáveis, dashboard analítico e trilha de auditoria. Inclui também um módulo de Qualidade para o recebimento de material de estoque, com inspeção item a item.

O nome vem da raiz de romaneio. A romã (a fruta) é uma casca que protege e organiza muitas sementes — como o produto organiza itens, caixas e entregas sob um documento único e os comprova.

Funcionalidades

• Romaneios — CRUD com filtros (data, status, solicitante), volume e caixa obrigatória. Assinado é imutável; entregue sai da caixa.
• Caixas — agrupamento por setor e envio em lote para assinatura.
• Assinatura digital — canvas → PNG, delegação de assinatura, storage selecionável (disco local em dev / S3-compatível em produção).
• Qualidade — fila de recebimento de estoque; cada item é uma ficha (FCQ) inspecionada individualmente (liberar / rejeitar com motivo).
• Notificações in-app, auditoria de ações críticas (com IP e user agent), dashboard (KPIs + gráficos) e relatórios (CSV / XLSX / PDF).
• Controle de acesso por papéis: Usuário / Almoxarifado / Admin.

Telas

Login	Romaneios	Caixas
Qualidade	Dashboard	Dashboard — gráficos

Dados de demonstração gerados por script — nomes e fornecedores são fictícios.

Stack

Camada	Tecnologia
Backend	Python 3.12 · FastAPI · SQLAlchemy 2.0 · Pydantic v2
Migrations	Alembic
Banco	MariaDB 11 (charset utf8mb4, timezone UTC)
Autenticação	JWT próprio (PyJWT) + bcrypt · RBAC com 3 papéis
Frontend	React + TypeScript + Vite (SPA)
Dados no front	TanStack Query + Axios (cookie httpOnly)
Testes	pytest + httpx (back) · Vitest + Testing Library (front)

Arquitetura

Monólito modular, monorepo. Um app por serviço (api e web), organizado por módulos de domínio com fronteiras claras:

router (HTTP) → service (regra de negócio) → repository (acesso a dados) → model (ORM)

Um módulo conversa com outro pela camada de service, nunca acessando o banco ou os internos do vizinho — simplicidade de um monolito, com fronteiras que permitiriam extrair um módulo no futuro. Validação de entrada/saída com Pydantic; papel e identidade do usuário sempre vindos do JWT (nunca do corpo da requisição).

O frontend é feature-first com TypeScript estrito; TanStack Query cuida do estado de servidor (cache e invalidação); o cliente Axios centraliza o interceptor de 401.

Módulos de domínio

Módulo	Responsabilidade
auth	Login, emissão/renovação de JWT, troca de senha
users	CRUD de usuários e papéis
romaneios	CRUD de romaneios, status, filtros, paginação
caixas	Agrupamento e envio em lote para assinatura
assinaturas	Assinatura digital (canvas) + delegação
notificacoes	Notificações in-app e contador de não lidas
relatorios	Exportação (PDF / Excel / CSV)
auditoria	Log automático de ações críticas
dashboard	Métricas e gráficos
qualidade	Fila de recebimento de estoque; inspeção por item (FCQ)

Como rodar localmente

Pré-requisitos: Docker · Python 3.12 com uv · Node 22.

git clone https://github.com/diegobernardessv/roma.git
cd roma

1. Banco (MariaDB via Docker):

docker compose up -d

2. Backend (em apps/api):

cd apps/api
cp .env.example .env          # defina ADMIN_PASSWORD e SECRET_KEY
uv sync
uv run alembic upgrade head   # cria o schema
uv run python -m app.seed     # cria o admin inicial (do .env)
uv run python -m app.dev_seeds.seed_dev   # dados de exemplo (opcional)
uv run uvicorn app.main:app --reload      # http://localhost:8000

3. Frontend (em apps/web, em outro terminal):

cd apps/web
cp .env.example .env
npm install
npm run dev                   # http://localhost:5173

4. Acesse http://localhost:5173 e entre com o admin definido no .env. Os usuários de exemplo criados pelo seed_dev usam a senha romademo123.

Para ver o app "cheio" (meses de dados para os gráficos), rode uv run python -m app.dev_seeds.seed_massa — ele limpa e gera massa de demonstração.

Testes

Os testes do backend usam SQLite em memória (não precisam do banco no ar).

# Backend (apps/api)
uv run ruff check app tests && uv run ruff format --check app tests
uv run mypy app
uv run pytest

# Frontend (apps/web)
npx tsc -b --force
npm run lint
npm run test

Estrutura

roma/
├── apps/
│   ├── api/            # Backend FastAPI (core, modules/<domínio>, alembic, tests)
│   └── web/            # Frontend React + Vite (features, components, lib)
├── docker-compose.yml  # Banco MariaDB para dev
└── .github/workflows/  # CI (lint + tipos + testes)

Licença

MIT © 2026 Diego Bernardes Silva — DBSolutions Lab.