docs: Token Limits UI implementation guide
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
This commit is contained in:
@@ -0,0 +1,294 @@
|
||||
# Token Limits - Implementación Completa
|
||||
|
||||
## ✅ Estado: COMPLETADO
|
||||
|
||||
**Fecha**: 2026-03-23
|
||||
**Versión**: OpenCCB 0.2.2
|
||||
|
||||
---
|
||||
|
||||
## 📊 Resumen de la Implementación
|
||||
|
||||
### Phase 1: Database + API ✅
|
||||
- [x] Migración de base de datos
|
||||
- [x] Funciones SQL (check_token_limit, get_user_usage_stats)
|
||||
- [x] API Endpoints para gestión de límites
|
||||
- [x] Módulo common::token_limits
|
||||
|
||||
### Phase 2: UI Dashboard + User Management ✅
|
||||
- [x] Token Usage Dashboard mejorado
|
||||
- [x] User Management con columna de límites
|
||||
- [x] Admin Dashboard con card de AI Token Usage
|
||||
- [x] Edición de límites en tiempo real
|
||||
- [x] Alertas visuales de uso
|
||||
|
||||
### Phase 3: Enforce Automático ⏳ (Pendiente)
|
||||
- [ ] Agregar check en handlers de IA (CMS + LMS)
|
||||
- [ ] Sistema de alertas por email/notificación
|
||||
- [ ] Trigger SQL para notificaciones automáticas
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Dónde Encontrar Cada Feature
|
||||
|
||||
### 1. Token Usage Dashboard
|
||||
**URL**: `http://localhost:3000/admin/token-usage`
|
||||
|
||||
**Features**:
|
||||
- ✅ Ver uso de tokens por usuario
|
||||
- ✅ Ver límite mensual configurado
|
||||
- ✅ Ver porcentaje usado con barra de progreso
|
||||
- ✅ Editar límites (clic en ícono ✏️)
|
||||
- ✅ Alertas de usuarios >80% y >100%
|
||||
- ✅ Ordenar por % usado, tokens, requests, costo
|
||||
- ✅ Filtrar por rol
|
||||
|
||||
**Columnas**:
|
||||
| Usuario | Rol | Límite Mensual | % Usado | Total Tokens | Requests | Costo USD |
|
||||
|---------|-----|----------------|---------|--------------|----------|-----------|
|
||||
|
||||
---
|
||||
|
||||
### 2. User Management
|
||||
**URL**: `http://localhost:3000/admin/users`
|
||||
|
||||
**Features**:
|
||||
- ✅ Ver límite de tokens por usuario
|
||||
- ✅ Ver porcentaje usado con badge de color
|
||||
- ✅ Barra de progreso miniatura
|
||||
|
||||
**Columnas Nuevas**:
|
||||
- Token Limit: Muestra % usado y límite mensual
|
||||
|
||||
---
|
||||
|
||||
### 3. Admin Dashboard
|
||||
**URL**: `http://localhost:3000/admin`
|
||||
|
||||
**Features**:
|
||||
- ✅ Card "AI Token Usage" con resumen
|
||||
- ✅ Total tokens (formato compacto: 1.2M)
|
||||
- ✅ Total requests
|
||||
- ✅ Costo estimado en USD
|
||||
- ✅ Link a Token Usage Dashboard
|
||||
|
||||
---
|
||||
|
||||
## 🎨 UI/UX Features
|
||||
|
||||
### Sistema de Colores
|
||||
|
||||
| Porcentaje | Color | Badge | Barra |
|
||||
|------------|-------|-------|-------|
|
||||
| 0-49% | Verde | bg-green-50 | bg-green-600 |
|
||||
| 50-79% | Azul | bg-blue-50 | bg-blue-600 |
|
||||
| 80-89% | Amarillo | bg-yellow-50 | bg-yellow-600 |
|
||||
| 90-99% | Naranja | bg-orange-50 | bg-orange-600 |
|
||||
| 100%+ | Rojo | bg-red-50 | bg-red-600 |
|
||||
|
||||
### Alertas
|
||||
|
||||
**Amarilla**: Usuarios con ≥80% de uso
|
||||
```
|
||||
⚠️ Usuarios cerca del límite
|
||||
X usuario(s) han usado ≥80% de su límite mensual.
|
||||
```
|
||||
|
||||
**Roja**: Usuarios con ≥100% de uso
|
||||
```
|
||||
⚠️ Límite excedido
|
||||
X usuario(s) han excedido su límite mensual.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Cómo Usar
|
||||
|
||||
### 1. Ver Uso de Tokens
|
||||
|
||||
1. Navega a `/admin/token-usage`
|
||||
2. Verás tabla con todos los usuarios
|
||||
3. Ordena por "% Usado" para ver quienes están cerca del límite
|
||||
|
||||
### 2. Editar Límite de Usuario
|
||||
|
||||
1. En `/admin/token-usage` o `/admin/users`
|
||||
2. Busca el usuario en la tabla
|
||||
3. Haz clic en el ícono ✏️ junto al límite
|
||||
4. Ingresa nuevo límite (0 = ilimitado)
|
||||
5. Haz clic en ✓ para guardar
|
||||
|
||||
### 3. Configuración Masiva (SQL)
|
||||
|
||||
```sql
|
||||
-- Estudiantes: 50K tokens/mes
|
||||
UPDATE users
|
||||
SET monthly_token_limit = 50000, token_limit_reset_day = 1
|
||||
WHERE role = 'student';
|
||||
|
||||
-- Instructores: 200K tokens/mes
|
||||
UPDATE users
|
||||
SET monthly_token_limit = 200000, token_limit_reset_day = 1
|
||||
WHERE role = 'instructor';
|
||||
|
||||
-- Admins: Ilimitado
|
||||
UPDATE users
|
||||
SET monthly_token_limit = 0
|
||||
WHERE role = 'admin';
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Métricas y Queries Útiles
|
||||
|
||||
### Ver Usuarios por Porcentaje de Uso
|
||||
|
||||
```sql
|
||||
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())
|
||||
WHERE u.monthly_token_limit IS NOT NULL
|
||||
GROUP BY u.id
|
||||
ORDER BY percentage DESC;
|
||||
```
|
||||
|
||||
### Ver Uso por Día
|
||||
|
||||
```sql
|
||||
SELECT
|
||||
DATE(created_at) as date,
|
||||
COUNT(*) as requests,
|
||||
SUM(tokens_used) as total_tokens,
|
||||
SUM(estimated_cost_usd) as cost_usd
|
||||
FROM ai_usage_logs
|
||||
WHERE created_at >= NOW() - INTERVAL '30 days'
|
||||
GROUP BY DATE(created_at)
|
||||
ORDER BY date DESC;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Próximos Pasos (Opcional)
|
||||
|
||||
### 1. Enforce Automático en Handlers de IA
|
||||
|
||||
Agregar en cada handler que usa IA:
|
||||
|
||||
```rust
|
||||
// Check token limit before proceeding (estimate X tokens)
|
||||
if let Err(_) = common::token_limits::check_ai_token_limit(&pool, claims.sub, 2000).await {
|
||||
return Err(StatusCode::TOO_MANY_REQUESTS);
|
||||
}
|
||||
```
|
||||
|
||||
**Handlers a actualizar**:
|
||||
- `generate_quiz` (2000 tokens)
|
||||
- `generate_course` (5000 tokens)
|
||||
- `generate_hotspots` (2000 tokens)
|
||||
- `generate_role_play` (2500 tokens)
|
||||
- `summarize_lesson` (1500 tokens)
|
||||
- `chat_with_tutor` (LMS, 1000 tokens)
|
||||
- `evaluate_audio` (LMS, 1500 tokens)
|
||||
|
||||
### 2. Sistema de Alertas Automáticas
|
||||
|
||||
```sql
|
||||
CREATE TRIGGER token_limit_alert
|
||||
AFTER INSERT ON ai_usage_logs
|
||||
FOR EACH ROW
|
||||
EXECUTE FUNCTION check_token_limit_alert();
|
||||
```
|
||||
|
||||
### 3. Notificaciones por Email
|
||||
|
||||
- Email al alcanzar 80%
|
||||
- Email al alcanzar 90%
|
||||
- Email al alcanzar 100%
|
||||
|
||||
---
|
||||
|
||||
## 📁 Archivos Modificados
|
||||
|
||||
### Backend
|
||||
- `shared/common/src/token_limits.rs` (NUEVO)
|
||||
- `shared/common/src/lib.rs`
|
||||
- `services/cms-service/src/handlers_admin.rs`
|
||||
- `services/cms-service/src/main.rs`
|
||||
- `services/cms-service/migrations/20260323000000_monthly_token_limits.sql` (NUEVO)
|
||||
|
||||
### Frontend
|
||||
- `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
|
||||
- `TOKEN_LIMITS_GUIDE.md` (NUEVO)
|
||||
- `TOKEN_LIMITS_STATUS.md` (NUEVO)
|
||||
- `TOKEN_LIMITS_UI_COMPLETE.md` (ESTE ARCHIVO)
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Ejemplo de Uso Real
|
||||
|
||||
### Escenario: Universidad con 1000 estudiantes
|
||||
|
||||
**Configuración Inicial**:
|
||||
```sql
|
||||
-- Límites por rol
|
||||
UPDATE users SET monthly_token_limit = 50000 WHERE role = 'student'; -- 50K
|
||||
UPDATE users SET monthly_token_limit = 200000 WHERE role = 'instructor'; -- 200K
|
||||
UPDATE users SET monthly_token_limit = 0 WHERE role = 'admin'; -- Unlimited
|
||||
```
|
||||
|
||||
**Monitoreo Semanal**:
|
||||
1. Revisar `/admin/token-usage`
|
||||
2. Ordenar por "% Usado"
|
||||
3. Identificar estudiantes con >80%
|
||||
4. Ajustar límites si es necesario
|
||||
|
||||
**Ajuste de Límites**:
|
||||
```sql
|
||||
-- Aumentar límite para estudiantes avanzados
|
||||
UPDATE users
|
||||
SET monthly_token_limit = 100000
|
||||
WHERE role = 'student' AND gpa > 3.5;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Checklist de Testing
|
||||
|
||||
- [ ] Navegar a `/admin/token-usage`
|
||||
- [ ] Ver tabla con usuarios y límites
|
||||
- [ ] Editar límite de un usuario (✏️)
|
||||
- [ ] Ver alerta amarilla (>80%)
|
||||
- [ ] Ver alerta roja (>100%)
|
||||
- [ ] Navegar a `/admin/users`
|
||||
- [ ] Ver columna Token Limit
|
||||
- [ ] Navegar a `/admin`
|
||||
- [ ] Ver card AI Token Usage
|
||||
- [ ] Ver link a Token Usage Dashboard
|
||||
- [ ] Probar en mobile (responsive)
|
||||
- [ ] Probar en dark mode
|
||||
|
||||
---
|
||||
|
||||
## 📞 Soporte
|
||||
|
||||
**Documentación Completa**: `TOKEN_LIMITS_GUIDE.md`
|
||||
**Estado**: `TOKEN_LIMITS_STATUS.md`
|
||||
**Issues**: Reportar en GitHub
|
||||
|
||||
---
|
||||
|
||||
**Implementado por**: Equipo de Desarrollo OpenCCB
|
||||
**Fecha**: 2026-03-23
|
||||
**Versión**: 0.2.2
|
||||
Reference in New Issue
Block a user