feat: CRM Clinicas SaaS - MVP completo

- Auth: Login/Register con creacion de clinica - Dashboard: KPIs reales, graficas recharts - Pacientes: CRUD completo con busqueda - Agenda: FullCalendar, drag-and-drop, vista recepcion - Expediente: Notas SOAP, signos vitales, CIE-10 - Facturacion: Facturas con IVA, campos CFDI SAT - Inventario: Productos, stock, movimientos, alertas - Configuracion: Clinica, equipo, catalogo servicios - Supabase self-hosted: 18 tablas con RLS multi-tenant - Docker + Nginx para produccion Co-Authored-By: claude-flow <ruv@ruv.net>
2026-03-03 07:04:14 +00:00
commit 79b5d86325
1612 changed files with 109181 additions and 0 deletions
--- a/docs/plans/2026-03-02-crm-clinicas-design.md
+++ b/docs/plans/2026-03-02-crm-clinicas-design.md
@@ -0,0 +1,238 @@
+# CRM Clinicas SaaS — Documento de Diseno
+
+**Fecha:** 2026-03-02
+**Estado:** Aprobado
+**Cliente:** Clinica general multiespecialidad (Mexico)
+**Deployment:** Self-hosted en VM Ubuntu 24.04 (4 CPU, 15GB RAM, 24GB disco)
+
+---
+
+## 1. Vision General
+
+CRM SaaS completo para clinicas medicas en Mexico. MVP orientado a una clinica pequena (1-3 doctores) con arquitectura multi-tenant preparada para escalar a multiples clientes.
+
+## 2. Stack Tecnologico
+
+| Capa | Tecnologia |
+|------|-----------|
+| Frontend | Next.js 15 (App Router) + TypeScript + Tailwind CSS + shadcn/ui |
+| Backend/BaaS | Supabase Self-Hosted (PostgreSQL + Auth + Storage + Realtime) |
+| CFDI | Facturama API |
+| WhatsApp | Twilio / 360dialog |
+| Pagos SaaS | Conekta |
+| Reverse Proxy | Nginx |
+| SSL | Certbot + Let's Encrypt (cuando haya dominio) |
+| Contenedores | Docker + Docker Compose |
+| OS | Ubuntu 24.04 LTS |
+
+## 3. Arquitectura
+
+```
+VM (Ubuntu 24.04)
+  Docker Compose:
+    - Nginx (:80) -> reverse proxy
+    - Next.js App (:3000)
+    - Supabase Stack:
+      - PostgreSQL (:5432)
+      - GoTrue Auth (:9999)
+      - Storage (:5000)
+      - Realtime (:4000)
+      - Kong API Gateway (:8000)
+      - Studio (:3001) — admin panel
+```
+
+### Multi-tenancy
+
+Row-Level Security (RLS) en PostgreSQL. Cada tabla tiene `clinic_id`. Politicas RLS filtran automaticamente segun el JWT del usuario autenticado. Ningun query puede cruzar datos entre clinicas.
+
+## 4. Modulos del MVP
+
+### 4.1 Gestion de Pacientes
+- CRUD completo con datos demograficos, CURP, alergias, tipo de sangre
+- Busqueda rapida por nombre, telefono, CURP
+- Timeline cronologico (citas, consultas, facturas, archivos)
+- Comunicacion WhatsApp
+- Fuente de captacion (referido, redes, Google)
+- Import/export CSV
+
+### 4.2 Agenda y Citas
+- Calendario visual (dia/semana/mes) por doctor
+- Drag-and-drop para reagendar
+- Slots configurables por doctor (duracion, horarios por dia)
+- Bloqueo de horarios (vacaciones, juntas)
+- Estados: scheduled -> confirmed -> in_progress -> completed / cancelled / no_show
+- Recordatorios automaticos WhatsApp 24h y 1h antes
+- Lista de espera
+- Vista de recepcion (citas del dia, quien llego, quien esta en consulta)
+
+### 4.3 Expediente Clinico Electronico
+- Historia clinica: antecedentes familiares, personales, quirurgicos, medicamentos, alergias, inmunizaciones
+- Nota de consulta SOAP (Subjective, Objective, Assessment, Plan)
+- Signos vitales con graficas de tendencia
+- Diagnosticos CIE-10
+- Receta digital PDF con cedula profesional
+- Archivos adjuntos (labs, imagenes, estudios)
+- Firma digital del doctor
+- Export PDF del expediente completo
+
+### 4.4 Facturacion y Pagos
+- Catalogo de servicios con claves SAT
+- Creacion de factura desde consulta completada
+- Timbrado CFDI 4.0 via Facturama API
+- Cancelacion CFDI con motivo
+- Formas de pago: efectivo, tarjeta, transferencia
+- Cuentas por cobrar y parcialidades
+- Corte de caja diario
+- Reportes de ingresos por periodo, doctor, servicio
+
+### 4.5 Inventario
+- Catalogo de productos (medicamento, insumo, material, equipo)
+- Control de stock por sucursal
+- Movimientos: entrada, salida, ajuste, merma
+- Alertas de stock minimo
+- Vinculacion a consulta (descuento automatico)
+- Vinculacion a factura
+- Reporte de movimientos
+
+### 4.6 Dashboard y Reportes
+- KPIs: pacientes nuevos, citas del dia, ingresos del mes, tasa ausentismo
+- Graficas: ingresos por mes, citas por doctor, servicios mas solicitados
+- Ocupacion de agenda por doctor
+- Inventario critico
+
+## 5. Modelo de Datos
+
+### Tablas principales:
+
+```
+clinics (tenant)
+users (doctores, staff — vinculado a auth.users)
+patients
+doctor_schedules
+appointments
+medical_records (antecedentes)
+consultation_notes (notas SOAP por visita)
+prescriptions
+medical_files
+services_catalog
+invoices
+invoice_items
+payments
+products
+inventory_stock
+inventory_movements
+branches
+audit_log
+```
+
+### Campos clave por tabla:
+
+**clinics:** id, name, slug, rfc, razon_social, regimen_fiscal, codigo_postal, pac_provider, pac_api_key (encrypted), subscription_plan, subscription_status
+
+**patients:** id, clinic_id, first_name, last_name, date_of_birth, gender, curp, phone, email, address (jsonb), blood_type, allergies (text[]), emergency_contact (jsonb), source
+
+**appointments:** id, clinic_id, patient_id, doctor_id, starts_at, ends_at, status, type, reason, reminder_sent
+
+**consultation_notes:** id, clinic_id, patient_id, doctor_id, appointment_id, subjective, objective, assessment, plan, vital_signs (jsonb), diagnoses (jsonb CIE-10), is_signed
+
+**invoices:** id, clinic_id, patient_id, invoice_number, cfdi_uuid, cfdi_status, uso_cfdi, forma_pago, metodo_pago, subtotal, tax_amount, total, payment_status
+
+**products:** id, clinic_id, sku, name, category, unit, purchase_price, sale_price, min_stock
+
+**inventory_movements:** id, clinic_id, product_id, type, quantity, reason, reference_id
+
+## 6. Seguridad y Cumplimiento
+
+- NOM-004-SSA3-2012: Notas SOAP, firma digital, historial inmutable (soft delete)
+- NOM-024-SSA3-2012: Control de acceso, bitacora de accesos, integridad
+- LFPDPPP: Aviso de privacidad, consentimiento, encriptacion, derechos ARCO
+- CFDI 4.0 SAT: PAC certificado (Facturama), claves SAT, XML firmado
+- Multi-tenancy: RLS de PostgreSQL
+- Encriptacion: HTTPS (cuando hay dominio), encriptacion at-rest, pgcrypto para campos sensibles
+- Auditoria: tabla audit_log con triggers automaticos
+- Roles: owner > admin > doctor > receptionist
+- Backups: pg_dump cron diario con rotacion 7 dias
+
+## 7. Estructura del Proyecto
+
+```
+src/
+  app/
+    (auth)/          — login, register, forgot-password
+    (dashboard)/     — layout protegido con sidebar
+      patients/
+      appointments/
+      medical-records/
+      billing/
+      inventory/
+      settings/
+    api/webhooks/    — conekta, whatsapp
+  components/
+    ui/              — shadcn/ui
+    forms/
+    calendar/
+    medical/
+    layout/
+  lib/
+    supabase/        — client, server, admin
+    cfdi/            — integracion PAC
+    whatsapp/
+    utils/
+  hooks/
+  types/
+supabase/
+  migrations/
+  seed.sql
+  functions/         — edge functions (reminders, cfdi)
+docker-compose.yml
+nginx.conf
+```
+
+## 8. Integraciones Externas
+
+| Servicio | Uso | Costo |
+|----------|-----|-------|
+| Facturama | CFDI SAT | ~$1.50 MXN/factura |
+| Twilio/360dialog | WhatsApp | ~$0.50 MXN/mensaje |
+| Conekta | Pagos suscripciones | 2.9% + $2.50/tx |
+| Resend | Emails transaccionales | Free tier |
+
+## 9. Modelo de Negocio SaaS
+
+| Plan | Precio | Doctores | Sucursales | Features |
+|------|--------|----------|------------|----------|
+| Basico | $799 MXN/mes | 1 | 1 | Agenda + Expediente |
+| Pro | $1,499 MXN/mes | 3 | 2 | + Facturacion + Inventario |
+| Enterprise | $2,999 MXN/mes | Ilimitado | Ilimitado | + WhatsApp + Reportes avanzados |
+
+Trial gratuito: 14 dias (Plan Pro)
+
+## 10. Costos Operativos (Self-Hosted)
+
+| Concepto | Mensual |
+|----------|---------|
+| VM | $0 (existente) |
+| Dominio | ~$17 MXN/mes |
+| Facturama | ~$300 MXN/mes |
+| Twilio | ~$200 MXN/mes |
+| **Total** | **~$520 MXN/mes** |
+
+## 11. Roadmap
+
+| Fase | Semanas | Entregable |
+|------|---------|-----------|
+| 1 - Fundacion | 1-2 | Docker setup, auth, multi-tenancy RLS, layout, CRUD pacientes |
+| 2 - Agenda | 3-4 | Calendario, slots, citas, estados, vista recepcion |
+| 3 - Expediente | 5-7 | Historia clinica, notas SOAP, recetas PDF, archivos |
+| 4 - Facturacion | 8-10 | Catalogo servicios, facturas, CFDI, pagos, corte de caja |
+| 5 - Inventario | 11-12 | Productos, stock, movimientos, alertas |
+| 6 - Polish | 13-14 | Dashboard, reportes, WhatsApp, testing, produccion |
+
+## 12. Deployment (Self-Hosted)
+
+- Docker Compose con todos los servicios
+- Nginx como reverse proxy (:80)
+- Acceso por IP publica (sin dominio por ahora)
+- SSL con Certbot cuando se agregue dominio
+- Backups automaticos con pg_dump + cron
+- Monitoreo basico con docker logs + healthchecks