cabo-health-ai

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# Cabo Health Nova 🏥

> Asistente Médico con IA Conversacional de Próxima Generación

[![Estado](https://img.shields.io/badge/Estado-Producción-success)](https://etric4luf0vq.space.minimax.io)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue)](https://www.typescriptlang.org/)
[![React](https://img.shields.io/badge/React-18.3-61dafb)](https://reactjs.org/)
[![Supabase](https://img.shields.io/badge/Supabase-Backend-green)](https://supabase.com/)

## 🌐 Aplicación en Vivo

**URL:** https://etric4luf0vq.space.minimax.io  
**Cuenta de Prueba:** arxaonpy@minimax.com

## 📖 Descripción

Cabo Health Nova es una aplicacion medica de vanguardia que utiliza IA conversacional para realizar entrevistas clinicas detalladas. Integra tecnologia de voz nativa con Gemini 3 Flash para crear una experiencia natural de consulta medica, generando automaticamente resumenes clinicos en formato SOAP.

### Sistema de Cola de Resumenes

El sistema garantiza que **ninguna entrevista se pierda** mediante una arquitectura de cola asincrona:

1. **Guardado Prioritario**: Al finalizar la sesion, el transcript se guarda PRIMERO en `pending_summaries`
2. **Procesamiento con Fallback**: Gemini 3 Flash (primario) con fallback a Gemini 2.5 Flash
3. **Recuperacion Automatica**: Si el procesamiento falla, el transcript permanece seguro para reintentos

### ✨ Características Principales

✅ **Conversación Voz a Voz** - Interacción natural con IA usando WebRTC  
✅ **Transcripción en Tiempo Real** - Visualiza la conversación mientras ocurre  
✅ **Resúmenes SOAP Automatizados** - Generación de resúmenes clínicos profesionales  
✅ **Sistema de Persistencia** - Checkpoints automáticos, nunca pierdas tu progreso  
✅ **Backend Completo** - Persistencia de datos con Supabase  
✅ **Envío de Emails** - Envía resúmenes directamente al médico  
✅ **Bilingüe** - Soporte completo para Español e Inglés  
✅ **Seguro** - Autenticación, RLS, sanitización HTML  

## 🚀 Inicio Rápido

### Requisitos Previos

- **Node.js** 18+
- **pnpm** (recomendado) o npm
- **Cuenta de Google AI Studio** (para GEMINI_API_KEY)

### Instalación

```bash
# 1. Clonar el repositorio
git clone https://github.com/guaderrama/cabo-health-clinic.git
cd cabo-health-clinic

# 2. Instalar dependencias
pnpm install

# 3. Copiar variables de entorno
cp .env.example .env

# 4. Configurar GEMINI_API_KEY en .env
echo "VITE_GEMINI_API_KEY=tu_api_key_de_gemini" >> .env
```

### Desarrollo Local

```bash
# Iniciar servidor de desarrollo
pnpm dev

# La aplicación estará disponible en http://localhost:3000
```

### Compilar para Producción

```bash
# Crear build optimizado
pnpm build

# Vista previa del build
pnpm preview
```

## ⚙️ Configuración

### Variables de Entorno Requeridas

```env
# API Key de Gemini (OBLIGATORIO)
VITE_GEMINI_API_KEY=tu_api_key_de_gemini

# Configuración de Supabase (Ya configurado en producción)
VITE_SUPABASE_URL=https://cozsoshuctvhvdbmkmwc.supabase.co
VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

### Variables de Entorno Opcionales

```env
# API Key de Resend para envío real de emails
RESEND_API_KEY=tu_api_key_de_resend
```

### Cómo Obtener las API Keys

#### GEMINI_API_KEY
1. Visita [Google AI Studio](https://makersuite.google.com/app/apikey)
2. Crea un proyecto nuevo
3. Genera una API key
4. Configúrala en tu archivo `.env`

#### RESEND_API_KEY (Opcional)
1. Visita [Resend](https://resend.com)
2. Crea una cuenta gratuita
3. Genera una API key
4. Configúrala en Supabase Dashboard

## 🏗️ Arquitectura

### Stack Tecnológico

| Componente | Tecnología | Versión |
|------------|------------|---------|
| **Frontend** | React + TypeScript | 18.3 + 5.6 |
| **Build Tool** | Vite | 6.2 |
| **Backend** | Supabase | Latest |
| **Base de Datos** | PostgreSQL | 15+ |
| **IA** | Gemini 3 Flash (primario) / Gemini 2.5 Flash (fallback) | Latest |
| **UI** | TailwindCSS + Radix UI | Latest |
| **Audio** | WebRTC + Web Audio API | Native |

### Estructura del Proyecto

```
cabo-health-nova/
├── src/
│   ├── components/       # Componentes React (25+)
│   ├── contexts/        # Context API (Auth)
│   ├── lib/            # Utilidades (Supabase client)
│   ├── utils/          # Helpers (audio, sanitize)
│   ├── services/       # Servicios (audio, summaryQueue)
│   └── App.tsx         # Componente principal
├── supabase/
│   └── functions/      # Edge Functions (4)
├── .ai-context/        # Contexto para agentes
├── memory/            # Contexto entre sesiones
├── docs/              # Documentación técnica
└── public/            # Assets estáticos
```

### Flujo de Datos

1. **Audio Input** → WebRTC → Gemini AI
2. **Transcripción** → Edge Functions → Supabase Database
3. **Resumen SOAP** → Edge Functions → Email/Display
4. **Persistencia** → localStorage + Supabase (dual backup)

## 🗄️ Base de Datos

### Esquema Principal

| Tabla | Descripción | Registros |
|-------|-------------|-----------|
| `patients` | Información de pacientes | User-based |
| `consultations` | Consultas médicas | Generated |
| `transcriptions` | Transcripciones de conversaciones | Real-time |
| `summaries` | Resúmenes clínicos SOAP | Auto-generated |
| `sessions` | Sesiones de consultas | Session-based |
| `session_checkpoints` | Checkpoints de persistencia | Auto-saved |
| `pending_summaries` | Cola de generacion de resumenes | Queue-based |

### Edge Functions

| Función | Propósito | Estado |
|---------|-----------|--------|
| `save-consultation` | Guarda consulta completa | ✅ Activa |
| `generate-summary` | Genera resumen SOAP | ✅ Activa |
| `send-summary-email` | Envía email al médico | ✅ Activa |
| `get-consultations` | Obtiene historial | ✅ Activa |

## 🔒 Seguridad

- ✅ **RLS (Row Level Security)** en todas las tablas
- ✅ **Sanitización HTML** con DOMPurify
- ✅ **Autenticación JWT** con Supabase
- ✅ **Variables de entorno** seguras
- ✅ **CORS configurado** en Edge Functions

## 🧪 Uso de la Aplicación

### 1. Autenticación
- Registrarse con email y contraseña
- Iniciar sesión

### 2. Iniciar Consulta
- Ingresar nombre del paciente
- Seleccionar idioma (Español/Inglés)
- Permitir acceso al micrófono
- Hacer clic en "Iniciar Sesión"

### 3. Conversación con Nova
- Hablar naturalmente con la IA
- Responder preguntas del cuestionario
- Ver transcripción en tiempo real
- **Checkpoints automáticos** cada 2 mensajes

### 4. Finalizar y Enviar
- Hacer clic en "Finalizar Sesión"
- Revisar resumen SOAP generado
- Completar formulario de paciente
- Enviar al médico

## 🎯 Sistema de Persistencia

### Características
- **Guardado automático** cada 2 mensajes
- **Recuperación automática** de sesiones interrumpidas
- **Fallback dual**: localStorage + Supabase
- **Cleanup automático** al completar sesión

### Recuperación
- El sistema detecta automáticamente sesiones incompletas
- Modal de recuperación muestra información detallada
- Opciones: Continuar o Descartar sesión

## 📊 Métricas y Performance

### Build Stats
- **Bundle Size**: 720.34 kB (optimizado)
- **Build Time**: ~4 segundos
- **TypeScript**: 100% tipado
- **Code Coverage**: Manual testing + futuro automatizado

### Performance
- **Load Time**: < 3 segundos
- **Time to Interactive**: < 5 segundos
- **Audio Latency**: ~500ms
- **API Response**: < 2 segundos

## 🛠️ Comandos de Desarrollo

```bash
# Desarrollo
pnpm dev                    # Servidor de desarrollo
pnpm dev:local             # Desarrollo con variables locales

# Build y Deploy
pnpm build                 # Compilar para producción
pnpm build:prod           # Build optimizado
pnpm preview              # Vista previa del build

# Calidad de Código
pnpm lint                  # Verificar código
pnpm lint:fix             # Corregir problemas automáticamente
pnpm type-check           # Verificar tipos TypeScript

# Utilidades
pnpm clean                 # Limpiar dependencias
```

## 🐛 Errores Corregidos

Este proyecto incluye correcciones para:

1. ✅ **Variables de entorno inconsistentes** - Estandarizado con Vite
2. ✅ **Sanitización HTML insegura** - DOMPurify con configuración segura
3. ✅ **Duplicación de transcripciones** - Lógica mejorada sin duplicados
4. ✅ **Gestión de memoria de audio** - Cleanup completo implementado
5. ✅ **Simulación de envío de datos** - Backend real con Supabase

Ver [DOCUMENTACION_COMPLETA.md](https://github.com/guaderrama/cabo-health-ai/blob/HEAD/DOCUMENTACION_COMPLETA.md) para detalles.

## 📝 Documentación Adicional

- **[Arquitectura](https://github.com/guaderrama/cabo-health-ai/blob/HEAD/docs/ARCHITECTURE.md)** - Detalles técnicos del sistema
- **[Seguridad](https://github.com/guaderrama/cabo-health-ai/blob/HEAD/docs/SECURITY.md)** - Configuración de variables y secretos
- **[Operaciones](https://github.com/guaderrama/cabo-health-ai/blob/HEAD/docs/OPERATIONS.md)** - Deploy y mantenimiento
- **[Sistema de Persistencia](https://github.com/guaderrama/cabo-health-ai/blob/HEAD/docs/SISTEMA_PERSISTENCIA.md)** - Checkpoints y recuperación

## 🤝 Contribuciones

Las contribuciones son bienvenidas. Por favor:

1. Fork el proyecto
2. Crear una rama para tu feature
3. Commit tus cambios
4. Push a la rama
5. Abrir un Pull Request

## 📧 Contacto

Para soporte o consultas sobre este proyecto, contactar al autor original.

---

**Desarrollado con ❤️ por MiniMax Agent**

**Tecnologías:** React · TypeScript · Supabase · Gemini AI · TailwindCSS

---

*📚 Documentación completa disponible en la carpeta `docs/`*

Cabo Health Nova 🏥

Asistente Médico con IA Conversacional de Próxima Generación

🌐 Aplicación en Vivo

URL: https://etric4luf0vq.space.minimax.io
Cuenta de Prueba: arxaonpy@minimax.com

📖 Descripción

Cabo Health Nova es una aplicacion medica de vanguardia que utiliza IA conversacional para realizar entrevistas clinicas detalladas. Integra tecnologia de voz nativa con Gemini 3 Flash para crear una experiencia natural de consulta medica, generando automaticamente resumenes clinicos en formato SOAP.

Sistema de Cola de Resumenes

El sistema garantiza que ninguna entrevista se pierda mediante una arquitectura de cola asincrona:

Guardado Prioritario: Al finalizar la sesion, el transcript se guarda PRIMERO en pending_summaries
Procesamiento con Fallback: Gemini 3 Flash (primario) con fallback a Gemini 2.5 Flash
Recuperacion Automatica: Si el procesamiento falla, el transcript permanece seguro para reintentos

✨ Características Principales

✅ Conversación Voz a Voz - Interacción natural con IA usando WebRTC
✅ Transcripción en Tiempo Real - Visualiza la conversación mientras ocurre
✅ Resúmenes SOAP Automatizados - Generación de resúmenes clínicos profesionales
✅ Sistema de Persistencia - Checkpoints automáticos, nunca pierdas tu progreso
✅ Backend Completo - Persistencia de datos con Supabase
✅ Envío de Emails - Envía resúmenes directamente al médico
✅ Bilingüe - Soporte completo para Español e Inglés
✅ Seguro - Autenticación, RLS, sanitización HTML

🚀 Inicio Rápido

Requisitos Previos

Node.js 18+
pnpm (recomendado) o npm
Cuenta de Google AI Studio (para GEMINI_API_KEY)

Instalación

# 1. Clonar el repositorio
git clone https://github.com/guaderrama/cabo-health-clinic.git
cd cabo-health-clinic

# 2. Instalar dependencias
pnpm install

# 3. Copiar variables de entorno
cp .env.example .env

# 4. Configurar GEMINI_API_KEY en .env
echo "VITE_GEMINI_API_KEY=tu_api_key_de_gemini" >> .env

Desarrollo Local

# Iniciar servidor de desarrollo
pnpm dev

# La aplicación estará disponible en http://localhost:3000

Compilar para Producción

# Crear build optimizado
pnpm build

# Vista previa del build
pnpm preview

⚙️ Configuración

Variables de Entorno Requeridas

# API Key de Gemini (OBLIGATORIO)
VITE_GEMINI_API_KEY=tu_api_key_de_gemini

# Configuración de Supabase (Ya configurado en producción)
VITE_SUPABASE_URL=https://cozsoshuctvhvdbmkmwc.supabase.co
VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Variables de Entorno Opcionales

# API Key de Resend para envío real de emails
RESEND_API_KEY=tu_api_key_de_resend

Cómo Obtener las API Keys

GEMINI_API_KEY

Visita Google AI Studio
Crea un proyecto nuevo
Genera una API key
Configúrala en tu archivo .env

RESEND_API_KEY (Opcional)

Visita Resend
Crea una cuenta gratuita
Genera una API key
Configúrala en Supabase Dashboard

🏗️ Arquitectura

Stack Tecnológico

Componente	Tecnología	Versión
Frontend	React + TypeScript	18.3 + 5.6
Build Tool	Vite	6.2
Backend	Supabase	Latest
Base de Datos	PostgreSQL	15+
IA	Gemini 3 Flash (primario) / Gemini 2.5 Flash (fallback)	Latest
UI	TailwindCSS + Radix UI	Latest
Audio	WebRTC + Web Audio API	Native

Estructura del Proyecto

cabo-health-nova/
├── src/
│   ├── components/       # Componentes React (25+)
│   ├── contexts/        # Context API (Auth)
│   ├── lib/            # Utilidades (Supabase client)
│   ├── utils/          # Helpers (audio, sanitize)
│   ├── services/       # Servicios (audio, summaryQueue)
│   └── App.tsx         # Componente principal
├── supabase/
│   └── functions/      # Edge Functions (4)
├── .ai-context/        # Contexto para agentes
├── memory/            # Contexto entre sesiones
├── docs/              # Documentación técnica
└── public/            # Assets estáticos

Flujo de Datos

Audio Input → WebRTC → Gemini AI
Transcripción → Edge Functions → Supabase Database
Resumen SOAP → Edge Functions → Email/Display
Persistencia → localStorage + Supabase (dual backup)

🗄️ Base de Datos

Esquema Principal

Tabla	Descripción	Registros
`patients`	Información de pacientes	User-based
`consultations`	Consultas médicas	Generated
`transcriptions`	Transcripciones de conversaciones	Real-time
`summaries`	Resúmenes clínicos SOAP	Auto-generated
`sessions`	Sesiones de consultas	Session-based
`session_checkpoints`	Checkpoints de persistencia	Auto-saved
`pending_summaries`	Cola de generacion de resumenes	Queue-based

Edge Functions

Función	Propósito	Estado
`save-consultation`	Guarda consulta completa	✅ Activa
`generate-summary`	Genera resumen SOAP	✅ Activa
`send-summary-email`	Envía email al médico	✅ Activa
`get-consultations`	Obtiene historial	✅ Activa

🔒 Seguridad

✅ RLS (Row Level Security) en todas las tablas
✅ Sanitización HTML con DOMPurify
✅ Autenticación JWT con Supabase
✅ Variables de entorno seguras
✅ CORS configurado en Edge Functions

🧪 Uso de la Aplicación

1. Autenticación

Registrarse con email y contraseña
Iniciar sesión

2. Iniciar Consulta

Ingresar nombre del paciente
Seleccionar idioma (Español/Inglés)
Permitir acceso al micrófono
Hacer clic en "Iniciar Sesión"

3. Conversación con Nova

Hablar naturalmente con la IA
Responder preguntas del cuestionario
Ver transcripción en tiempo real
Checkpoints automáticos cada 2 mensajes

4. Finalizar y Enviar

Hacer clic en "Finalizar Sesión"
Revisar resumen SOAP generado
Completar formulario de paciente
Enviar al médico

🎯 Sistema de Persistencia

Características

Guardado automático cada 2 mensajes
Recuperación automática de sesiones interrumpidas
Fallback dual: localStorage + Supabase
Cleanup automático al completar sesión

Recuperación

El sistema detecta automáticamente sesiones incompletas
Modal de recuperación muestra información detallada
Opciones: Continuar o Descartar sesión

📊 Métricas y Performance

Build Stats

Bundle Size: 720.34 kB (optimizado)
Build Time: ~4 segundos
TypeScript: 100% tipado
Code Coverage: Manual testing + futuro automatizado

Performance

Load Time: < 3 segundos
Time to Interactive: < 5 segundos
Audio Latency: ~500ms
API Response: < 2 segundos

🛠️ Comandos de Desarrollo

# Desarrollo
pnpm dev                    # Servidor de desarrollo
pnpm dev:local             # Desarrollo con variables locales

# Build y Deploy
pnpm build                 # Compilar para producción
pnpm build:prod           # Build optimizado
pnpm preview              # Vista previa del build

# Calidad de Código
pnpm lint                  # Verificar código
pnpm lint:fix             # Corregir problemas automáticamente
pnpm type-check           # Verificar tipos TypeScript

# Utilidades
pnpm clean                 # Limpiar dependencias

🐛 Errores Corregidos

Este proyecto incluye correcciones para:

✅ Variables de entorno inconsistentes - Estandarizado con Vite
✅ Sanitización HTML insegura - DOMPurify con configuración segura
✅ Duplicación de transcripciones - Lógica mejorada sin duplicados
✅ Gestión de memoria de audio - Cleanup completo implementado
✅ Simulación de envío de datos - Backend real con Supabase

Ver DOCUMENTACION_COMPLETA.md para detalles.

📝 Documentación Adicional

Arquitectura - Detalles técnicos del sistema
Seguridad - Configuración de variables y secretos
Operaciones - Deploy y mantenimiento
Sistema de Persistencia - Checkpoints y recuperación

🤝 Contribuciones

Las contribuciones son bienvenidas. Por favor:

Fork el proyecto
Crear una rama para tu feature
Commit tus cambios
Push a la rama
Abrir un Pull Request

📧 Contacto

Para soporte o consultas sobre este proyecto, contactar al autor original.

Desarrollado con ❤️ por MiniMax Agent

Tecnologías: React · TypeScript · Supabase · Gemini AI · TailwindCSS

📚 Documentación completa disponible en la carpeta docs/