rckrdmrd/template-saas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
68d3c54023
template-saas/docs/01-modulos/SAAS-006-ai-integration.md
rckrdmrd 68d3c54023 docs(ai): Update documentation and fix DDL scripts 
Documentation:
- Update SAAS-006-ai-integration.md with full implementation details
- Update _MAP.md with AI schema (30 tables, 11 schemas)
- Update PROJECT-STATUS.md (67% completion)

Database fixes:
- Add update_updated_at_column() function to 03-functions.sql
- Add trigger creation for ai.configs in 03-functions.sql
- Fix partial index in 02-ai-usage.sql (remove CURRENT_DATE)
- Add AI schema grants to create-database.sh
- Add AI to SCHEMA_ORDER array

Validated: Database recreation successful with all AI objects

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-07 07:21:56 -06:00

8.7 KiB
Raw Blame History

SAAS-006: Integracion IA

Metadata

  • Codigo: SAAS-006
  • Modulo: AI Integration
  • Prioridad: P1
  • Estado: Implementado
  • Fase: 5 - Integraciones
  • Fecha Implementacion: 2026-01-07

Descripcion

Wrapper agnostico para integracion con multiples proveedores de LLM (Claude, OpenAI, Gemini): configuracion por tenant, tracking de uso, rate limiting, y costo estimado.

Objetivos

  1. Abstraccion multi-proveedor
  2. Configuracion por tenant
  3. Tracking de tokens
  4. Rate limiting
  5. Estimacion de costos

Alcance

Incluido

  • Soporte: Claude (Anthropic), GPT-4 (OpenAI), Gemini (Google)
  • Via OpenRouter como gateway
  • Configuracion de modelo por tenant
  • Conteo de tokens input/output
  • Rate limiting por minuto y por mes
  • Logs de uso

Excluido

  • Embeddings - fase posterior
  • Fine-tuning
  • Vision/imagenes - fase posterior
  • Streaming - fase posterior

Proveedores Soportados

Proveedor Modelos Via
Anthropic claude-3-opus, claude-3-sonnet, claude-3-haiku OpenRouter
OpenAI gpt-4-turbo, gpt-4, gpt-3.5-turbo OpenRouter
Google gemini-pro, gemini-1.5-pro OpenRouter

Arquitectura

┌─────────────────────────────────────────────────────────┐
│                     AI Service                          │
├─────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │   Config    │  │   Router    │  │   Tracker   │     │
│  │  per Tenant │  │  (Model)    │  │   (Usage)   │     │
│  └─────────────┘  └──────┬──────┘  └─────────────┘     │
│                          │                              │
│                   ┌──────▼──────┐                       │
│                   │ OpenRouter  │                       │
│                   │   Client    │                       │
│                   └──────┬──────┘                       │
│                          │                              │
└──────────────────────────┼──────────────────────────────┘
                           │
         ┌─────────────────┼─────────────────┐
         │                 │                 │
    ┌────▼────┐      ┌─────▼─────┐     ┌────▼────┐
    │ Claude  │      │   GPT-4   │     │ Gemini  │
    └─────────┘      └───────────┘     └─────────┘

Modelo de Datos

Schema: ai

ai.configs (Configuracion por tenant)

Columna Tipo Descripcion
id UUID PK
tenant_id UUID FK -> tenants.tenants
provider ai_provider openrouter, openai, anthropic, google
default_model VARCHAR(100) Modelo por defecto
fallback_model VARCHAR(100) Modelo de respaldo
temperature NUMERIC(3,2) 0.0 - 2.0
max_tokens INTEGER Max tokens por respuesta
system_prompt TEXT Prompt de sistema
is_enabled BOOLEAN Habilitar AI
allow_custom_prompts BOOLEAN Permitir prompts custom
log_conversations BOOLEAN Guardar historial

ai.usage (Tracking de uso)

Columna Tipo Descripcion
id UUID PK
tenant_id UUID FK -> tenants.tenants
user_id UUID FK -> users.users
provider ai_provider Proveedor usado
model VARCHAR(100) Modelo usado
input_tokens INTEGER Tokens de entrada
output_tokens INTEGER Tokens de salida
total_tokens INTEGER Total (computed)
cost_input NUMERIC(12,6) Costo entrada USD
cost_output NUMERIC(12,6) Costo salida USD
cost_total NUMERIC(12,6) Total (computed)
latency_ms INTEGER Latencia en ms
status usage_status pending, completed, failed

ai.monthly_usage (Vista agregada)

  • request_count, total_tokens, total_cost, avg_latency_ms

Endpoints API

Metodo Endpoint Descripcion Estado
POST /ai/chat Chat completion Implementado
GET /ai/models Modelos disponibles Implementado
GET /ai/config Config del tenant Implementado
PATCH /ai/config Actualizar config Implementado
GET /ai/usage Historial de uso Implementado
GET /ai/usage/current Uso del mes actual Implementado
GET /ai/health Estado del servicio Implementado

Implementacion Backend

Estructura de archivos

apps/backend/src/modules/ai/
├── ai.module.ts              # Modulo NestJS
├── ai.controller.ts          # Endpoints REST
├── index.ts                  # Exports
├── clients/
│   └── openrouter.client.ts  # Cliente OpenRouter API
├── services/
│   ├── ai.service.ts         # Logica de negocio
│   └── index.ts
├── entities/
│   ├── ai-config.entity.ts   # TypeORM entity
│   ├── ai-usage.entity.ts    # TypeORM entity
│   └── index.ts
└── dto/
    ├── chat.dto.ts           # Request/Response DTOs
    └── index.ts

Configuracion requerida

// .env
OPENROUTER_API_KEY=sk-or-...
AI_DEFAULT_MODEL=anthropic/claude-3-haiku
AI_FALLBACK_MODEL=openai/gpt-3.5-turbo
AI_TIMEOUT_MS=30000

Implementacion Frontend

Estructura de archivos

apps/frontend/src/
├── services/
│   └── api.ts                # aiApi client
├── hooks/
│   └── useAI.ts              # React Query hooks
├── components/ai/
│   ├── AIChat.tsx            # Chat interactivo
│   ├── AISettings.tsx        # Config UI
│   ├── ChatMessage.tsx       # Mensaje individual
│   └── index.ts
└── pages/dashboard/
    └── AIPage.tsx            # Pagina AI

Hooks disponibles

// Configuracion
useAIConfig()                 // GET config
useUpdateAIConfig()           // PATCH config

// Modelos
useAIModels()                 // GET modelos disponibles

// Chat
useAIChat()                   // POST chat completion

// Uso
useAIUsage(page, limit)       // GET historial
useCurrentAIUsage()           // GET uso mes actual

// Health
useAIHealth()                 // GET estado servicio

Rate Limiting

Por Plan

Plan Tokens/min Tokens/mes
Pro 10,000 50,000
Enterprise 50,000 200,000

Implementacion

  • In-memory rate limiter (Redis en produccion)
  • Por tenant_id
  • Tokens y requests

Costos Estimados

Modelo Input/1K Output/1K
claude-3-haiku $0.00025 $0.00125
claude-3-sonnet $0.003 $0.015
gpt-4-turbo $0.01 $0.03
gemini-pro $0.00025 $0.0005

Entregables

Entregable Estado Archivo
Database DDL Completado ddl/schemas/ai/tables/
ai.module.ts Completado modules/ai/
openrouter.client.ts Completado clients/
ai.service.ts Completado services/
ai.controller.ts Completado ai.controller.ts
Frontend hooks Completado hooks/useAI.ts
Chat component Completado components/ai/
Settings UI Completado AISettings.tsx
AI Page Completado pages/dashboard/AIPage.tsx

Dependencias

Depende de

  • SAAS-002 (Tenants) - tenant_id FK
  • SAAS-003 (Users) - user_id FK
  • SAAS-005 (Plans - feature flag)
  • OpenRouter API key

Bloquea a

  • Features de IA en otros modulos

Criterios de Aceptacion

  • Chat funciona con Claude
  • Chat funciona con GPT-4
  • Chat funciona con Gemini
  • Tokens se cuentan correctamente
  • Rate limiting funciona
  • Uso se registra
  • UI de chat funcional
  • Settings de AI por tenant

Rutas Frontend

Ruta Componente Descripcion
/dashboard/ai AIPage Chat con AI
/dashboard/settings (tab AI) AISettings Configuracion

Navegacion

  • Sidebar: "AI Assistant" con icono Bot
  • Settings: Tab "AI" en pagina de configuracion

Ultima actualizacion: 2026-01-07 Version: 1.0.0 Autor: Claude Code