Files

T

Nurfog dce68d76df docs: Token Limits complete summary (100% implementation)

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

2026-03-23 17:23:52 -03:00

7.4 KiB

Raw Blame History

Token Limits - Implementación 100% Completa

✅ ESTADO: COMPLETADO (100%) - 2026-03-23

Versión: OpenCCB 0.2.4
Commits: 5 commits en el día

📊 Implementación Completa

✅ Phase 1: Database + API

Migración de base de datos
Funciones SQL (check_token_limit, get_user_usage_stats)
API Endpoints para gestión de límites
Módulo common::token_limits

✅ Phase 2: UI Dashboard + User Management

Token Usage Dashboard mejorado
User Management con columna de límites
Admin Dashboard con card de AI Token Usage
Edición de límites en tiempo real
Alertas visuales de uso

✅ Phase 3: Sistema de Alertas Automáticas

Trigger SQL en ai_usage_logs
Notificaciones al 80%, 90%, 100%
Tabla token_limit_alerts para historial
Función send_token_limit_notification()

✅ Phase 4: Enforce Automático en Handlers

generate_quiz (2000 tokens)
generate_course (5000 tokens)
generate_hotspots (2000 tokens)
generate_role_play (2500 tokens)
summarize_lesson (1500 tokens)
chat_with_tutor (1000 tokens) - LMS
evaluate_audio_response (1500 tokens) - LMS

🎯 Dónde Encontrar Cada Feature

1. Admin Dashboard

URL: http://localhost:3000/admin

Qué verás:

Card "AI Token Usage" (4ta card)
Total tokens (formato compacto)
Total requests • Costo USD
Link a Token Usage Dashboard

2. Token Usage Dashboard

URL: http://localhost:3000/admin/token-usage

Features:

Tabla editable de usuarios
Columna "Límite Mensual" con editor ✏️
Columna "% Usado" con barra de progreso
Alertas amarillas (>80%) y rojas (>100%)
Ordenar por % usado

3. User Management

URL: http://localhost:3000/admin/users

Features:

Columna "Token Limit"
Badge de % usado con color
Mini barra de progreso

4. Notificaciones de Alerta

Dónde: Icono de campana en el header

Mensajes:

80%: "📊 80% de Tokens IA Utilizados"
90%: "⚡ 90% de Tokens IA Utilizados"
100%: "⚠️ Límite de Tokens IA Excedido"

🚀 Cómo Configurar

Configuración Inicial (SQL)

-- Ver configuración actual
SELECT email, role, monthly_token_limit, token_limit_reset_day
FROM users ORDER BY role, email;

-- Configurar por rol
UPDATE users SET monthly_token_limit = 50000 WHERE role = 'student';
UPDATE users SET monthly_token_limit = 200000 WHERE role = 'instructor';
UPDATE users SET monthly_token_limit = 0 WHERE role = 'admin';

Editar Límite Individual (UI)

Navegar a /admin/token-usage
Buscar usuario en la tabla
Clic en ✏️ junto al límite
Ingresar nuevo valor (0 = ilimitado)
Clic en ✓ para guardar

🔔 Sistema de Alertas

Cómo Funciona

Trigger en ai_usage_logs INSERT
Calcula uso mensual del usuario
Compara con su límite mensual
Envía notificación si alcanza 80%, 90%, o 100%
Registra alerta para no repetir en el mismo mes

Niveles

%	Mensaje	Acción
80%	📊 Warning	Monitorear uso
90%	⚡ Critical	Reducir uso de IA
100%	⚠️ Error	Contacto admin

🚫 Enforce Automático

Qué Pasa Cuando Se Excede el Límite

Usuario intenta usar función de IA
Sistema verifica: check_ai_token_limit()
Si excede límite → HTTP 429 Too Many Requests
Mensaje: "Monthly AI token limit exceeded"
Usuario debe contactar admin

Funciones Protegidas

CMS (5):

generate_quiz → 2000 tokens
generate_course → 5000 tokens
generate_hotspots → 2000 tokens
generate_role_play → 2500 tokens
summarize_lesson → 1500 tokens

LMS (2):

chat_with_tutor → 1000 tokens
evaluate_audio_response → 1500 tokens

📊 Monitoreo

Queries Útiles

-- Top usuarios por uso
SELECT 
    u.email,
    u.role,
    u.monthly_token_limit,
    SUM(au.tokens_used) as used_tokens,
    ROUND((SUM(au.tokens_used)::NUMERIC / 
        CASE WHEN u.monthly_token_limit = 0 THEN 1 
             ELSE u.monthly_token_limit END * 100), 2) as percentage
FROM users u
LEFT JOIN ai_usage_logs au ON u.id = au.user_id
    AND au.created_at >= DATE_TRUNC('month', NOW())
GROUP BY u.id
ORDER BY percentage DESC;

-- Uso por día
SELECT 
    DATE(created_at) as date,
    COUNT(*) as requests,
    SUM(tokens_used) as total_tokens
FROM ai_usage_logs
WHERE created_at >= NOW() - INTERVAL '30 days'
GROUP BY DATE(created_at)
ORDER BY date DESC;

-- Alertas enviadas
SELECT 
    u.email,
    n.title,
    n.created_at
FROM notifications n
JOIN users u ON n.user_id = u.id
WHERE n.notification_type = 'token_limit_alert'
ORDER BY n.created_at DESC;

📁 Archivos Modificados

Backend (8 archivos)

shared/common/src/token_limits.rs ✅
shared/common/src/lib.rs ✅
services/cms-service/src/handlers_admin.rs ✅
services/cms-service/src/handlers.rs ✅
services/cms-service/src/main.rs ✅
services/lms-service/src/handlers.rs ✅
services/cms-service/migrations/20260323000000_monthly_token_limits.sql ✅
services/cms-service/migrations/20260323000001_token_limit_alerts.sql ✅

Frontend (3 archivos)

web/studio/src/app/admin/token-usage/page.tsx ✅
web/studio/src/app/admin/users/page.tsx ✅
web/studio/src/app/admin/page.tsx ✅

Documentación (5 archivos)

TOKEN_LIMITS_GUIDE.md ✅
TOKEN_LIMITS_STATUS.md ✅
TOKEN_LIMITS_UI_COMPLETE.md ✅
TOKEN_LIMITS_FINAL.md ✅
TOKEN_LIMITS_COMPLETE_SUMMARY.md ✅ (este archivo)

🧪 Testing Checklist

Navegar a /admin
Ver card "AI Token Usage"
Hacer clic en "View Details"
Navegar a /admin/token-usage
Ver tabla con usuarios y límites
Ordenar por "% Usado"
Editar límite de un usuario (✏️)
Ver alerta amarilla (>80%)
Ver alerta roja (>100%)
Navegar a /admin/users
Ver columna "Token Limit"
Configurar límites por rol (SQL)
Probar función de IA (quiz/course)
Verificar enforce automático (429 error)
Ver notificaciones de alerta

🎓 Ejemplo de Uso Completo

1. Configuración Inicial

-- Configurar límites
UPDATE users SET monthly_token_limit = 50000 WHERE role = 'student';
UPDATE users SET monthly_token_limit = 200000 WHERE role = 'instructor';
UPDATE users SET monthly_token_limit = 0 WHERE role = 'admin';

2. Monitoreo Semanal

Ir a /admin/token-usage
Ordenar por "% Usado"
Identificar usuarios con >80%
Ajustar límites si es necesario

3. Alertas Automáticas

El sistema automáticamente:

Detecta cuando usuario alcanza 80%, 90%, 100%
Envía notificación en plataforma
Registra alerta (una vez por umbral/mes)

4. Enforce Automático

Cuando usuario excede límite:

Intenta generar quiz → Error 429
Intenta chatear con tutor → Error 429
Mensaje: "Monthly AI token limit exceeded"
Debe contactar admin para aumento

📞 Soporte

Documentación Completa: TOKEN_LIMITS_GUIDE.md
UI Guide: TOKEN_LIMITS_UI_COMPLETE.md
Implementation: TOKEN_LIMITS_FINAL.md
Issues: Reportar en GitHub

🏆 Logros del Día

✅ 5 Commits realizados
✅ 4 Phases completadas
✅ 7 Handlers protegidos
✅ 3 Alertas automáticas
✅ 100% Feature Complete

Implementado por: Equipo de Desarrollo OpenCCB
Fecha: 2026-03-23
Versión: 0.2.4
Estado: ✅ Production Ready

7.4 KiB Raw Blame History