Reem-Notas/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project overview

Reem Logística is a Rails 7 web application for controlling delivery costs for Gade Hospitalar (account_id: 95907). It manages consolidations of driver payments across delivery routes (UBS SUL, UBS LESTE, EMAD, STS, SAD, etc.).

Commands

All commands run inside Docker. The PostgreSQL database lives externally (not in docker-compose).

# Start
docker-compose up -d

# Rails console
docker-compose exec app bundle exec rails console

# Run migrations
docker-compose exec app bundle exec rails db:migrate

# Seed (creates admin + test drivers)
docker-compose exec app bundle exec rails db:seed

# Logs
docker-compose logs -f app

# Tests (RSpec)
docker-compose exec app bundle exec rspec
docker-compose exec app bundle exec rspec spec/models/consolidacao_spec.rb  # single file

# Rake task (runs manually what the cron job runs hourly)
docker-compose exec app bundle exec rake historico:atualizar

# Activate the hourly cron job on the server
docker-compose exec app bundle exec whenever --update-crontab

Setup from scratch

cp .env.example .env
# Edit .env: set DB_HOST, DB_PASSWORD, and generate SECRET_KEY_BASE with:
#   openssl rand -hex 64
docker-compose build --no-cache
docker-compose up -d
docker-compose exec app bundle exec rails db:create db:migrate db:seed

Default credentials (change in production): admin@gade.com / Gade@2026!

Critical constraint: read-only external table

The table public.db_reem_simplerout_2026 is owned by an external system (SimpleRoute) that updates it every hour. NEVER create migrations for it, and never run INSERT/UPDATE/DELETE/DROP/TRUNCATE on it.

Entrega (app/models/entrega.rb) maps to this table and enforces readonly? = true. All queries go through its scopes — the most important being .pagas (status='completed' AND checkout IS NOT NULL), which defines payment eligibility. Consolidations filter eligible deliveries by vehicle (vehicle column → Consolidacao#vehicle_ids), not by route.

Architecture

Data flow

1. External system writes to db_reem_simplerout_2026 hourly
2. Atualizar HistoricoEstimadoJob (triggered by Whenever cron every hour) counts paid deliveries per driver and writes to historico_estimados
3. Admins/managers create Consolidações (payment batches) covering a date range + list of drivers
4. A 3-step wizard classifies each delivery per driver (Normal/Retirada/Bônus/Desconto toggles)
5. Finalizing a consolidation sends WhatsApp (Twilio) and email notifications to drivers
6. Drivers view their own panel at /motorista using a 4-digit PIN or QR code from their printed payslip

Key models

Model	Table	Notes
Entrega	db_reem_simplerout_2026	Read-only. External data.
Consolidacao	consolidacoes	Payment batch. Enum status: rascunho/finalizada/arquivada. Soft-delete via deleted_at.
ConsolidacaoMotorista	consolidacao_motoristas	Join: which drivers are in a consolidation.
ConsolidacaoEntrega	consolidacao_entregas	Each classified delivery. Enum tipo: normal/retirada/bonus/desconto.
HistoricoEstimado	historico_estimados	Snapshot of hourly estimated values per driver.
Configuracao	configuracoes	Key-value store for prices and feature flags. Access via Configuracao.valor('chave').
AuditoriaLog	auditoria_logs	Audit trail. Controllers include Auditavel concern and call auditar!(:acao, registro).
User	users	Devise auth. Roles: admin/gerente/operador/motorista. Drivers may have no email — they log in via pin_code (4 digits, unique per driver) or login_token (QR).

Authorization

Pundit policies in app/policies/. ApplicationController includes Pundit::Authorization and calls authenticate_user! on every action. The motorista panel (/motorista/**) uses a separate session mechanism (motorista/sessoes_controller.rb) — drivers are NOT authenticated via Devise.

Two login flows for drivers

• /auth/login (Devise, Fase 2) — PIN tab on the standard login page
• /motorista/login (Fase 8) — dedicated numeric keypad, used by QR codes printed on payslips. Prefer this for mobile. Both use pin_code.

PDF generation

app/services/pdf/ contains three classes:

• BasePdf — shared black/orange header and footer layout
• RelatorioMotoristaPdf — detailed delivery table per driver
• HoleritePdf — payslip style + embedded QR code (via rqrcode/chunky_png) linking to /motorista/acesso/:token

The consolidation wizard

/consolidacoes/:id/wizard → /consolidacao_entregas/validar → /consolidacao_entregas/revisar

• Passo 1 (wizard): pick a driver. Shows progress per driver.
• Passo 2 (validar): color-coded toggle buttons per delivery (orange=Normal, dark orange=Retirada, white=Bônus, black=Desconto). Toggle individual or mass-classify. Stimulus controller (validacao_controller.js) handles real-time totals and progress.
• Passo 3 (revisar): summary for the selected driver, then move to the next driver or save as draft.

Finalizing is blocked (server-side + UI) until all drivers have all eligible deliveries classified.

Notifications (NotificacaoService)

Controlled by Configuracao flags notificacao_whatsapp and notificacao_email. Failures are rescued and logged — they never abort the finalization. WhatsApp requires Twilio ENV vars + driver telefone field in +5511999998888 format.

Design system

Dark theme (default). Colors: background #0a0a0a, cards #1a1a1a, accent/buttons #f97316 (orange), text #ffffff, success #22c55e, error #ef4444. Minimum font 16px desktop / 18px mobile. Touch targets minimum 48px height.

Environment variables

All config comes from .env (never hardcoded). Key variables:

• DB_HOST / DB_NAME / DB_USER / DB_PASSWORD — PostgreSQL connection
• DB_EXISTING_ACCOUNT_ID — filters db_reem_simplerout_2026 to Gade's account (default: 95907)
• SECRET_KEY_BASE — generate with openssl rand -hex 64
• APP_HOST — used in QR code URLs and notification links
• TWILIO_* — WhatsApp notifications (optional)
• SMTP_* — Email notifications (optional, only activates if SMTP_USERNAME is set)