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

267 lines
8.7 KiB
Markdown
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
```typescript
// .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
```typescript
// 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
- [x] Chat funciona con Claude
- [x] Chat funciona con GPT-4
- [x] Chat funciona con Gemini
- [x] Tokens se cuentan correctamente
- [x] Rate limiting funciona
- [x] Uso se registra
- [x] UI de chat funcional
- [x] 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
Reference in New Issue View Git Blame Copy Permalink