eminuxCRM/README.md

eminuxCRM

CRM commerciale standalone focalizzato su una domanda:

Cosa devo fare oggi per trasformare i miei prospect in clienti?

Applicazione Rails tradizionale (Hotwire / Turbo / Stimulus + Tailwind), pensata per poche persone, veloce da usare e semplice da mantenere. Completamente indipendente da MatchLiveTV.

Architettura

• Ruby on Rails 8 + PostgreSQL 16
• Hotwire (Turbo + Stimulus) — nessuna SPA
• Tailwind CSS
• Autenticazione locale con has_secure_password (bcrypt)
• Audit base created_by / updated_by sulle entità principali
• Timezone: Europe/Rome · UI: italiano

Servizi Docker

Servizio	Ruolo
web	Applicazione Rails (porta 3000)
postgres	Database PostgreSQL 16

Requisiti

• Docker + Docker Compose
• (Opzionale) Ruby 3.3+ per sviluppo fuori da Docker

Avvio rapido (Docker)

cp .env.example .env
# modifica SECRET_KEY_BASE e password DB se necessario

docker compose up -d --build

Al primo avvio vengono eseguiti automaticamente:

1. bundle install (in build)
2. tailwindcss:build
3. db:prepare (create + migrate)
4. db:seed

Apri: http://localhost:3001

Su questa macchina la porta 3000 è già usata da un altro stack: di default eminuxCRM usa 3001. Puoi cambiarla con APP_PORT nel file .env.

Progetti = istanze CRM separate

Ogni progetto ha un URL dedicato:

• Launcher: /
• MatchLiveTV: /p/matchlivetv
• RiskMeter: /p/riskmeter
• Cardoo: /p/cardoo

Dentro ogni istanza trovi dashboard, organizzazioni, pipeline, task, report e impostazioni del solo quel progetto.

• Gli admin vedono tutti i progetti
• Gli utenti solo i progetti abilitati
• In sidebar: “Tutti i progetti” + switch rapido tra istanze

Credenziali development (solo seed)

Email	Password	Ruolo	Progetti
admin@simplecrm.local	password123	Admin	Tutti
marco@simplecrm.local	password123	Utente	MatchLiveTV, RiskMeter
lucia@simplecrm.local	password123	Utente	MatchLiveTV, Cardoo

Configurazione .env

Copia .env.example → .env. Variabili principali:

• POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB
• DATABASE_HOST (in Docker: postgres)
• SECRET_KEY_BASE
• MAILER_FROM
• APP_HOST / APP_PORT
• TZ=Europe/Rome

Non committare .env con secret reali.

Migration e seed

docker compose exec web bin/rails db:migrate
docker compose exec web bin/rails db:seed

Reset completo (distruttivo):

docker compose exec web bin/rails db:reset

Test

docker compose exec web bin/rails db:test:prepare
docker compose exec web bin/rails test

Backup / restore

bin/backup
# crea tmp/backups/simplecrm_YYYYMMDD_HHMMSS.sql.gz

bin/restore tmp/backups/simplecrm_YYYYMMDD_HHMMSS.sql.gz

Con Docker Compose attivo gli script usano pg_dump / psql sul container postgres.

Import CSV

Pagina: Impostazioni → Import CSV oppure /imports/new.

Formato standard (file esempio: examples/organizations_import_sample.csv):

organization_name,organization_type,sport,country,region,province,city,website,organization_email,contact_first_name,contact_last_name,contact_role,contact_email,contact_phone,lead_source,notes

Duplicati evitati confrontando nome organizzazione, email e sito.

Export CSV

Disponibile da liste Organizzazioni, Contatti e Opportunità (rispetta i filtri attivi dove applicabile).

Struttura database (principale)

• users — autenticazione, ruolo admin/user
• organizations — prospect/clienti
• contacts — contatti per organizzazione
• opportunities — pipeline commerciale
• activities — timeline
• tasks — follow-up / next actions
• sales_goals — obiettivi dashboard
• products — catalogo prodotti (Light, Full, …)

Pipeline stages: Da contattare → Contattato → Ha risposto → Interessato → Demo/Trial → Primo utilizzo → Proposta → Cliente / Perso.

Funzionalità principali

• Dashboard con obiettivo, KPI, funnel, “Cosa fare oggi”, indicatori di attenzione
• Pagina /today operativa
• Scheda Organization come centro operativo + quick actions
• Kanban pipeline con drag & drop (Stimulus) e cambio stage da menu
• Task con evidenziazione scaduti / oggi / futuri
• Report: funnel, lead source, won/lost, lost reasons, sales owner, revenue
• Import/export CSV

Deploy (suggerimento semplice)

1. Copia il progetto su una VM
2. Configura .env di produzione (RAILS_ENV=production, SECRET_KEY_BASE, password DB forti)
3. docker compose up -d --build (oppure builda il target production del Dockerfile)
4. Metti un reverse proxy (Caddy/Nginx) con HTTPS davanti alla porta 3000
5. Esegui backup periodici con bin/backup

API JSON per agenti

I client HTML restano su cookie di sessione. Gli agenti (Cursor, Claude Code, Codex) usano un token Bearer.

1. Nel CRM: Token API (menu utente, oppure Impostazioni piattaforma se sei admin)
2. Crea un token: il valore crm_… si vede una sola volta
3. Header: Authorization: Bearer crm_…

Endpoint v1 (tutti tranne GET /api/v1/projects richiedono :project_code):

Metodo	Path	Ruolo
GET	/api/v1/projects	progetti accessibili
GET	/api/v1/p/:project_code/today	task scaduti / oggi / in arrivo + opportunità ferme
GET	/api/v1/p/:project_code/search?q=	org, contatti, opportunità
GET	/api/v1/p/:project_code/organizations/:id	scheda operativa
POST	/api/v1/p/:project_code/tasks	crea task
POST	/api/v1/p/:project_code/tasks/:id/complete	completa task
POST	/api/v1/p/:project_code/activities	annota timeline
PATCH	/api/v1/p/:project_code/opportunities/:id/stage	cambia stage pipeline

L’agente agisce come l’utente del token (stessi progetti, stesso created_by). Fuori da questa v1: mailing, utenti, delete, import CSV.

Esempio:

curl -sS -H "Authorization: Bearer crm_…" \
  http://localhost:3001/api/v1/p/matchlivetv/today

MCP (Cursor CLI / Claude Code / Codex)

Gli agenti parlano con il CRM su HTTP: http://localhost:3001/mcp (stesso Bearer del token API). Non serve Ruby sull’host.

1. Avvia il CRM (docker compose up)
2. Crea un token in Token API
3. Esporta il token e lancia l’agente dalla root del repo:

export CRM_API_TOKEN='crm_…'
# Cursor CLI:
agent "Interagisci col CRM su MatchLiveTV: cosa c'è da fare oggi?"
# Claude Code:
claude "Interagisci col CRM su MatchLiveTV: cosa c'è da fare oggi?"

Config già nel repo (il token sta solo in env, non nei file):

• Cursor / Cursor CLI: .cursor/mcp.json
• Claude Code: .mcp.json
• Codex: copia mcp/codex.config.toml.example in ~/.codex/config.toml

Istruzioni per gli agenti: AGENTS.md.

Tool: list_projects, today, search, get_organization, create_task, complete_task, create_activity, update_opportunity_stage, update_organization_email, check_mail_bounces.

Stdio (mcp/server.rb / bin/crm-mcp) resta come alternativa se un client non parla HTTP.

Esempio in chat: «Interagisci col CRM e fai alcune cose per me su MatchLiveTV.»

Sviluppo locale senza Docker (opzionale)

bundle install
bin/rails db:prepare db:seed
bin/dev   # server + tailwind watch

Volutamente fuori scope (fase successiva)

• Integrazioni Gmail/SMTP avanzate, sync email, calendario
• Stripe, webhook
• Dark mode, BI avanzata, microservizi

Licenza

Uso interno / progetto privato.