# CRM1 - SaaS Multitenant (MVP Pro+)

## Modulos implementados (15 mejoras en RBAC/Seguridad)
1. Navegacion por modulos con sidebar + navbar.
2. RBAC por rol/modulo/accion.
3. Contactos CRUD multi-tenant + filtros + export CSV.
4. Pipeline Kanban con creacion/movimiento de oportunidades.
5. Automatizaciones basicas ejecutables manual/cron.
6. Hardening: CSRF, headers de seguridad, bloqueo temporal por intentos, validacion de sesion activa.
7. Limites SaaS por plan (contactos/usuarios) y resumen de uso.
8. Auditoria + observabilidad (audit logs + error logs + notificaciones).
9. UX mejorada: toasts, confirmaciones SweetAlert, tablas y paneles por modulo.
10. API versionada `api/v1` + endpoint de documentacion.
11. Roles personalizados por tenant + permisos condicionales.
12. Matriz visual y simulador de permisos.
13. Versionado avanzado (diff + rollback parcial por rol/modulo).
14. Tokens API por usuario y export de auditoria.
15. Politicas enterprise de seguridad (password/sesion/MFA trusted device) + test de humo.

## Modulo 4: Suscripciones, Planes y Facturacion
- Planes con precio mensual/anual y limites por plan.
- Suscripcion por tenant con estado (`trialing`, `active`, `past_due`, `cancelled`).
- Gestion de trial gratis (dias configurables).
- Cobro recurrente manual/cron (`/cron/billing`) con generacion de facturas.
- Facturas (`open/paid/failed`) y transacciones de pago.
- Flujo de pago manual para regularizar `past_due`.
- Cierre enterprise: webhooks, perfil fiscal, metodos de pago, health monitor, historial de estado, backups y run logs.

## Modulo 5: Empresas (Cuentas) y Contactos 360
- CRUD de cuentas (empresas) y contactos.
- Etiquetas para cuentas/contactos.
- Campos personalizados (contact/account).
- Adjuntos por contacto.
- Historial 360 por contacto (eventos, interacciones, adjuntos, oportunidades).
- Extensiones enterprise: soft delete/restore, scoring, multi-cuenta por contacto, notas/tareas, segmentos, dedupe/merge, import jobs y sync logs.

## Modulo 6: Leads y Captacion
- Formularios publicos por tenant.
- Captura de leads desde web form y API.
- Importacion CSV de leads.
- Asignacion automatica (round robin / usuario / equipo / least-load).
- Scoring avanzado por reglas y decay de score.
- Conversion de lead a contacto.
- Doble opt-in, anti-spam, dedupe, SLA, webhooks y lotes CSV (preview/apply/rollback).

## Modulo 7: Pipeline de Ventas (Oportunidades)
- Kanban por etapas (drag and drop con orden persistente).
- Monto, estado y categoria de forecast por oportunidad.
- Forecast ponderado por probabilidad de etapa (`win_probability`).
- Cierre de oportunidades (`won` / `lost`) y reapertura.
- Motivos de perdida catalogados por tenant.
- Historial de cambios de etapa y cierre.
- Hardening enterprise:
- checklist por etapa
- reglas entry/exit por etapa
- probabilidad dinamica y score de confianza
- motivo de ganada
- competidores
- SLA por etapa y alertas
- aging de pipeline
- forecast por ventana y escenarios
- permisos por etapa
- campos personalizados de oportunidad
- playbooks por etapa
- deteccion de duplicados
- dashboard ejecutivo de conversion

## Modulo 8: Actividades y Seguimiento
- Agenda central de actividades (llamada, reunion, email, tarea, seguimiento).
- Estados de ejecucion (`planned`, `in_progress`, `done`, `cancelled`) con historial.
- Priorizacion (`low`, `medium`, `high`) y fechas (`starts_at`, `due_at`).
- Asociacion opcional a contacto, lead, oportunidad o cuenta.
- Recordatorios por actividad con despacho a notificaciones.
- KPIs operativos: abiertas, vencidas, completadas 7d y proximas 48h.
- Cierre enterprise (15 mejoras):
- calendario por ventana
- SLA por tipo/prioridad con alertas
- recurrencia
- dependencias
- cola diaria
- plantillas por etapa/contexto
- auto-creacion por eventos
- reasignacion least-load
- score de cumplimiento
- motivos de cancelacion
- log de cambios
- comentarios/@menciones
- adjuntos
- webhooks externos
- dashboard ejecutivo con snapshots

## Modulo 9: Proyectos y Tareas Colaborativas
- Tableros colaborativos estilo Monday por tenant.
- Columnas/estados por tablero con orden y color.
- Tareas con prioridad, estado, fechas y progreso.
- Multiples responsables por tarea (con responsable principal).
- Subtareas por tarea con seguimiento independiente.
- Comentarios y trazabilidad de cambios.

## Modulo 3 agregado: Usuarios, Equipos, Roles y Permisos
- Usuarios por empresa (tenant): crear/listar/editar/eliminar.
- Equipos: crear equipos, asignar usuarios, jerarquia con prevencion de ciclos y eliminar equipo.
- Permisos granulares: override por rol y por usuario en nivel modulo/accion/campo.
- Edicion inline de usuario (nombre/email/rol/status).
- Remover miembros de equipo desde UI + custom roles (activar/desactivar/eliminar/asignar/remover).
- Plantillas RBAC por rol (`sales_agent`, `readonly_audit`, `ops_manager`).
- Matriz RBAC editable de forma masiva.
- Flujo de aprobaciones con aplicacion automatica al aprobar.
- Verificacion de firma y cadena de auditoria.
- Tokens API con `Bearer` + enforcement por scopes.
- Enforcement real de permisos por campo en Contactos y Pipeline.

## Mejoras Kanban adicionales
- Drag and drop desktop + movil con SortableJS.
- Reordenamiento persistente por columna (`sort_order`).
- Historial de cambios de etapa en `opportunity_stage_history`.

## Migraciones
Manual (orden fijo):
1. `database/migrations/001_multitenant_core.sql`
2. `database/migrations/002_auth_security.sql`
3. `database/migrations/003_crm_modules.sql`
4. `database/migrations/004_pipeline_order_history.sql`
5. `database/migrations/005_users_teams_rbac.sql`
6. `database/migrations/006_rbac_enterprise_extensions.sql`
7. `database/migrations/007_rbac_enterprise_hardening.sql`
8. `database/migrations/008_subscriptions_billing.sql`
9. `database/migrations/009_tenant_license_events.sql`
10. `database/migrations/010_impersonation_tokens.sql`
11. `database/migrations/011_module4_closure_hardening.sql`
12. `database/migrations/012_accounts_contacts_360.sql`
13. `database/migrations/013_module5_enterprise_extensions.sql`
14. `database/migrations/014_leads_capture.sql`
15. `database/migrations/015_leads_capture_hardening.sql`
16. `database/migrations/016_pipeline_sales_forecast.sql`
17. `database/migrations/017_pipeline_enterprise_hardening.sql`
18. `database/migrations/018_activities_followup.sql`
19. `database/migrations/019_activities_enterprise_hardening.sql`
20. `database/migrations/020_projects_tasks_collaboration.sql`
21. `database/migrations/021_projects_enterprise_hardening.sql`
22. `database/migrations/022_projects_closure_hardening.sql`
23. `database/migrations/023_automations_workflows.sql`
24. `database/migrations/024_automations_enterprise_hardening.sql`
25. `database/migrations/025_communications_notifications.sql`

Runner CLI:
- `php scripts/migrate.php`
- `php scripts/rollback.php 1`

Seed QA modulo 3:
- `database/seeds/qa_module3_seed.sql`

## Usuario demo
- tenant: `demo`
- email: `admin@demo.local`
- password: `Admin123!`

## Rutas web
- `GET /login?tenant=demo`
- `GET /dashboard?tenant=demo&module=dashboard`
- `GET /dashboard?tenant=demo&module=contacts`
- `GET /dashboard?tenant=demo&module=leads`
- `GET /dashboard?tenant=demo&module=activities`
- `GET /dashboard?tenant=demo&module=projects`
- `GET /dashboard?tenant=demo&module=pipeline`
- `GET /dashboard?tenant=demo&module=automations`
- `GET /dashboard?tenant=demo&module=audit`
- `GET /dashboard?tenant=demo&module=users`
- `GET /dashboard?tenant=demo&module=teams`
- `GET /dashboard?tenant=demo&module=rbac`
- `GET /dashboard?tenant=demo&module=billing`
- `GET /dashboard?tenant=demo&module=settings`
- `GET /dashboard?tenant=demo&module=api-docs`
- `GET /lead/form?tenant=demo&form=web-demo`

## Rutas API
- `GET /api/v1/docs?tenant=demo`
- `GET /api/v1/contacts?tenant=demo&page=1&q=`
- `GET /api/v1/leads?tenant=demo&page=1&q=`
- `GET /api/v1/leads/forms?tenant=demo`
- `GET /api/v1/leads/metrics?tenant=demo`
- `GET /api/v1/leads/duplicates?tenant=demo`
- `GET /api/v1/activities?tenant=demo`
- `GET /api/v1/activities/kpis?tenant=demo`
- `GET /api/v1/projects/boards?tenant=demo`
- `GET /api/v1/projects/board?tenant=demo&board_id=1`
- `GET /api/v1/projects/dependencies?tenant=demo&task_id=1`
- `GET /api/v1/projects/checklist?tenant=demo&task_id=1`
- `GET /api/v1/projects/sla-rules?tenant=demo`
- `GET /api/v1/projects/tags?tenant=demo`
- `GET /api/v1/projects/comments?tenant=demo&task_id=1`
- `GET /api/v1/projects/attachments?tenant=demo&task_id=1`
- `POST /api/v1/contacts?tenant=demo`
- `POST /api/v1/activities?tenant=demo`
- `POST /api/v1/activities/status?tenant=demo`
- `POST /api/v1/projects/boards?tenant=demo`
- `POST /api/v1/projects/tasks?tenant=demo`
- `POST /api/v1/projects/tasks/move?tenant=demo`
- `POST /api/v1/projects/tasks/status?tenant=demo`
- `POST /api/v1/projects/dependencies?tenant=demo`
- `POST /api/v1/projects/checklist?tenant=demo`
- `POST /api/v1/projects/checklist/status?tenant=demo`
- `POST /api/v1/projects/sla-rules?tenant=demo`
- `POST /api/v1/projects/sla/monitor?tenant=demo`
- `POST /api/v1/projects/tags?tenant=demo`
- `POST /api/v1/projects/task-tags?tenant=demo`
- `POST /api/v1/projects/comments?tenant=demo`
- `POST /api/v1/projects/attachments?tenant=demo`
- `POST /api/v1/projects/duplicates/scan?tenant=demo`
- `POST /api/v1/projects/snapshots/daily?tenant=demo`
- `POST /api/v1/projects/snapshots/workload?tenant=demo`
- `GET /api/v1/automations/rules?tenant=demo`
- `GET /api/v1/automations/events?tenant=demo&limit=50`
- `GET /api/v1/automations/condition-schemas?tenant=demo`
- `GET /api/v1/automations/retry-policies?tenant=demo`
- `GET /api/v1/automations/dead-letters?tenant=demo&limit=80`
- `GET /api/v1/automations/runs?tenant=demo&limit=80`
- `GET /api/v1/automations/alerts?tenant=demo&limit=80`
- `POST /api/v1/automations/rules?tenant=demo`
- `POST /api/v1/automations/events?tenant=demo`
- `POST /api/v1/automations/simulate?tenant=demo`
- `POST /api/v1/automations/condition-schemas?tenant=demo`
- `POST /api/v1/automations/retry-policies?tenant=demo`
- `POST /api/v1/automations/run?tenant=demo`
- `POST /api/v1/automations/webhooks/process?tenant=demo`
- `POST /api/v1/automations/alerts/ack?tenant=demo`
- `GET /api/v1/communications/notifications?tenant=demo&limit=50`
- `GET /api/v1/communications/channels?tenant=demo`
- `GET /api/v1/communications/messages?tenant=demo&channel_id=1&limit=100`
- `GET /api/v1/communications/email-templates?tenant=demo&locale=es`
- `GET /api/v1/communications/alerts?tenant=demo&limit=80`
- `GET /api/v1/communications/realtime/events?tenant=demo&stream_key=alerts&since_id=0&limit=100`
- `POST /api/v1/communications/notifications?tenant=demo`
- `POST /api/v1/communications/notifications/read?tenant=demo`
- `POST /api/v1/communications/channels?tenant=demo`
- `POST /api/v1/communications/messages?tenant=demo`
- `POST /api/v1/communications/email-templates?tenant=demo`
- `POST /api/v1/communications/email/send?tenant=demo`
- `POST /api/v1/communications/alerts?tenant=demo`
- `POST /api/v1/communications/alerts/ack?tenant=demo`
- `POST /api/v1/communications/realtime/publish?tenant=demo`
- `POST /api/v1/leads/import/mock?tenant=demo`
- `POST /api/v1/leads/convert?tenant=demo`
- `POST /api/v1/leads/qualification?tenant=demo`
- `POST /api/v1/leads/score/decay?tenant=demo`
- `POST /api/v1/leads/sla/monitor?tenant=demo`
- `POST /api/v1/leads/reassign/stale?tenant=demo`
- `PUT /api/v1/contacts/{id}?tenant=demo`
- `DELETE /api/v1/contacts/{id}?tenant=demo`
- `GET /api/v1/pipeline?tenant=demo`
- `POST /api/v1/pipeline/move?tenant=demo`
- `GET /api/v1/pipeline/loss-reasons?tenant=demo`
- `GET /api/v1/pipeline/win-reasons?tenant=demo`
- `GET /api/v1/pipeline/competitors?tenant=demo`
- `GET /api/v1/pipeline/forecast/window?tenant=demo&from=YYYY-MM-DD&to=YYYY-MM-DD`
- `GET /api/v1/pipeline/scenarios?tenant=demo`
- `GET /api/v1/pipeline/dashboard?tenant=demo`
- `POST /api/v1/pipeline/loss-reasons?tenant=demo`
- `POST /api/v1/pipeline/win-reasons?tenant=demo`
- `POST /api/v1/pipeline/competitors?tenant=demo`
- `POST /api/v1/pipeline/close?tenant=demo`
- `POST /api/v1/pipeline/reopen?tenant=demo`
- `POST /api/v1/pipeline/forecast?tenant=demo`
- `POST /api/v1/pipeline/duplicates/scan?tenant=demo`
- `GET /api/v1/users?tenant=demo`
- `GET /api/v1/teams?tenant=demo`
- `GET /api/v1/rbac/overrides?tenant=demo`
- `GET /api/v1/billing/subscription?tenant=demo`
- `GET /api/v1/billing/invoices?tenant=demo`
- `GET /api/v1/billing/payment-methods?tenant=demo`
- `GET /api/v1/billing/status-history?tenant=demo`
- `GET /api/v1/billing/health?tenant=demo`
- `POST /api/v1/billing/run-cycle?tenant=demo`
- `POST /api/v1/billing/retry?tenant=demo`
- `GET /api/v1/billing/companies?tenant=demo`
- `GET /api/v1/audit/verify?tenant=demo`

## Scopes API token recomendados
- `contacts.read`
- `contacts.write`
- `pipeline.read`
- `pipeline.write`
- `audit.read`
- `tokens.manage`
- `admin.rbac`

## Seguridad
- Obtener CSRF: `GET /auth/csrf?tenant=demo`
- Enviar token en header `X-CSRF-Token` o campo `csrf_token`.

## Cron de automatizaciones (MVP)
- `POST /cron/automations?tenant=demo`
- `POST /cron/automations-webhooks?tenant=demo`
- `POST /cron/billing?tenant=demo`
- `POST /cron/projects-sla?tenant=demo`
- `POST /cron/projects-snapshot?tenant=demo`
- `POST /cron/projects-workload?tenant=demo`
- `POST /cron/projects-duplicates?tenant=demo`
- `POST /cron/automations?tenant=demo&event_name=lead.qualified`
- `POST /cron/communications-emails?tenant=demo`
- `POST /cron/billing-retry?tenant=demo`
- `POST /cron/billing-monitor?tenant=demo`
- `POST /cron/backup?tenant=demo`
- `POST /cron/pipeline-sla?tenant=demo`
- `POST /cron/pipeline-snapshot?tenant=demo`
- `POST /cron/activities-reminders?tenant=demo`
- `POST /cron/activities-sla?tenant=demo`
- `POST /cron/activities-recurrence?tenant=demo`
- `POST /cron/activities-reassign?tenant=demo`
- `POST /cron/activities-snapshot?tenant=demo`

## Tests
- Smoke general: `php tests/security_smoke.php`
- Regresion RBAC: `php tests/rbac_regression.php 1 1`
- Cierre modulo 3: `php tests/module3_closure_smoke.php`
- Billing: `php tests/billing_smoke.php`
- Cierre modulo 4: `php tests/module4_closure_smoke.php`
- Cierre modulo 5: `php tests/module5_closure_smoke.php`
- Cierre modulo 7: `php tests/module7_closure_smoke.php`
- Cierre modulo 8: `php tests/module8_closure_smoke.php`

## Operacion backup
- Registro de backup manual: `php scripts/backup.php demo backups/demo_YYYYMMDD.sql.gz full`

## Operacion y cierre modulo 4
- Runbook: `docs/module4_operacion.md`
- Checklist E2E: `docs/module4_cierre_checklist.md`

## Operacion modulo 5
- Runbook: `docs/module5_operacion.md`
- Checklist E2E: `docs/module5_cierre_checklist.md`

## Operacion modulo 6
- Runbook: `docs/module6_operacion.md`

## Operacion modulo 7
- Runbook: `docs/module7_operacion.md`

## Operacion modulo 8
- Runbook: `docs/module8_operacion.md`
- Checklist E2E: `docs/module8_cierre_checklist.md`

## Operacion modulo 9
- Runbook: `docs/module9_operacion.md`

## Licenciamiento empresas (renta)
- Alta empresa + licencia desde modulo Billing (owner).
- Actualizacion de licencia por empresa (plan/ciclo/proveedor).
- Seguimiento por timeline en `tenant_license_events`.
- Acceso directo a CRM empresa via impersonacion one-time (`Entrar al CRM`).
- Modo impersonacion `crm_only` configurable por `.env`:
  - `IMPERSONATION_CRM_MODULES=dashboard,contacts,pipeline,automations,audit`
  - Solo se permiten esos modulos por menu y por URL.
  - `IMPERSONATION_READ_ONLY=1` para impedir escrituras durante impersonacion.

## Variables de entorno nuevas
- `APP_INTERNAL_SECRET=...` (protege cron/webhooks via header `X-Internal-Secret` o `secret`).
- `IMPERSONATION_READ_ONLY=0|1`.
- `STRIPE_WEBHOOK_SECRET=whsec_...` para validar firma Stripe.
- `STRIPE_SECRET_KEY=sk_test_...` para customer/charge Stripe.

## Webhooks de pago (base)
- `POST /billing/webhook?tenant={slug}` con `provider`, `event_id`, `event_type`, `payload`.
- Requiere `APP_INTERNAL_SECRET`.
- Rutas web Stripe:
- `POST /billing/stripe/customer/sync?tenant={slug}`
- `POST /billing/stripe/payment-method/attach?tenant={slug}`
- `POST /billing/stripe/invoice/charge?tenant={slug}`
- `GET /billing/invoice/print?tenant={slug}&id={invoice_id}`

## Operacion y cierre modulo 3
- Runbook operativo: `docs/module3_operacion.md`
- Checklist E2E: `docs/module3_cierre_checklist.md`