# Plan — Administración de tokens de IA a nivel Holding

> Estado: **diseño para revisión** (no implementado). Decidido 2026-08-16.
> Unidad de cuota: **tokens** (model-agnóstico), con **costo en USD de referencia** al lado.
> Se apoya en lo ya construido: medición (`ai_consumo`), tarifas (`ai_tarifas`), tope por
> empresa (`ai_empresa_config.limite_tokens_mensual` + `AiUsageService.verificarCuota`),
> jerarquía `empresa_padre` (holding→subsidiarias) y módulo de Suscripciones/Planes.

## 1. Objetivo

Que el **holding** administre el consumo de IA de sus empresas: definir cuánta IA incluye
cada plan, ver consumo/costo por empresa, recargar cuotas, y decidir el modelo de costo.
Y que la **empresa**, si agota su cuota, pueda seguir usando IA con su **propia API key** o
**pedir aumento** al holding.

## 2. Modelo de credencial (quién paga)

Nuevo campo en `ai_empresa_config`:
- **`credencial_modo`** VARCHAR(12): `PLATAFORMA` | `PROPIA`.
  - `PLATAFORMA` → usa la **API key del holding**; consumo se descuenta de la **cuota del plan**;
    el **costo lo corre el holding**. Sujeto a `verificarCuota`.
  - `PROPIA` → usa la **API key de la empresa** (`api_key_encrypted` actual); la empresa paga;
    sin tope de plataforma (o auto-tope opcional que la propia empresa se fije).
- Default: empresas cuyo plan incluye IA → `PLATAFORMA`; el resto → `PROPIA`.
- `ai_consumo.credencial_propia` (ya existe) se setea según el modo, para separar el costo
  facturable al holding del que paga la empresa.

**Resolución de la key efectiva** (nuevo método en `AiConfigService`, ej. `getKeyEfectiva(empresaId)`):
1. Si `credencial_modo = PROPIA` → key propia de la empresa.
2. Si `PLATAFORMA` → subir por `empresa_padre` hasta el **holding** y usar SU `api_key_encrypted`
   (la "key de plataforma"). Si el holding no tiene key → error accionable.
`AiProviderService.completar` debe pedir la key por este resolver (hoy usa siempre la propia).

## 3. Cuota incluida en el plan

- Nuevo campo en el **Plan** (Suscripciones → Planes): **`tokens_ia_mensual`** INT (0 = no incluye IA).
- Al activar/renovar la suscripción, la empresa hereda esa cuota como `limite_tokens_mensual`
  (con `origen_limite = 'PLAN'`). El holding puede sobrescribir por empresa (`origen_limite = 'MANUAL'`)
  para recargas/top-ups.
- Nuevo campo `ai_empresa_config.origen_limite` VARCHAR(10): `PLAN` | `MANUAL` (para saber si un
  recálculo de plan puede pisar el valor o si fue ajuste manual del holding).
- Unidad: **tokens**. El costo USD se deriva de `ai_tarifas` (ya implementado) y se muestra como referencia.

## 4. Enforcement (extender lo existente)

`AiUsageService.verificarCuota(empresaId)`:
- Si `credencial_modo = PROPIA` → no aplica tope de plataforma (salvo auto-tope propio).
- Si `PLATAFORMA` → enforcea `limite_tokens_mensual` (ya lo hace). Al exceder, el mensaje ofrece
  **las dos salidas**: (a) "Configurá tu propia API key" (cambia a `PROPIA`), (b) "Pedí aumento al holding".

## 5. Dónde administra cada actor

### Holding — Suscripciones → nueva pestaña "Consumo IA" (holding-scope)
- Tabla por empresa de la red: consumo del mes (tokens), **costo USD**, cuota, % usado, modo
  (plataforma/propia), plan.
- Acciones: **recargar/ajustar cuota** por empresa (setea `limite_tokens_mensual`, `origen_limite=MANUAL`),
  ver histórico, y (opcional) aprobar solicitudes de aumento.
- Config de la **key de plataforma** (en la config del holding).
- Endpoints (holding-scope, validar que el usuario sea del holding y las empresas sean de su red):
  - `GET  /ai-holding/consumo` → agregado por empresa (reusa `ai_consumo` + `ai_tarifas`).
  - `PATCH /ai-holding/empresas/:empresaId/cuota` → set cuota + modo.
  - `GET/PATCH /ai-holding/key-plataforma`.

### Empresa — Config IA (ya existe, extender)
- Muestra su consumo + cuánto le queda (ya hecho: chip + barra + desglose por feature).
- Toggle **"Usar mi propia API key"** (cambia `credencial_modo` a `PROPIA` y pide la key).
- Botón **"Solicitar aumento al holding"** → crea una solicitud/notificación.

## 6. Solicitudes de aumento (opcional, simple)

Tabla `ai_solicitud_cuota` (empresa_id, tokens_pedidos, motivo, estado PENDIENTE|APROBADA|RECHAZADA,
resuelta_por, fecha). La empresa crea; el holding aprueba desde su panel (aprobar = subir la cuota).
Arranca manual si se quiere: la empresa avisa y el holding ajusta directamente.

## 7. Fases sugeridas

1. ✅ **HECHO (2026-08-16) — Modo credencial**: `ai_empresa_config.credencial_modo` (PROPIA|PLATAFORMA,
   migración `20260816_ai_credencial_modo`); `AiConfigService.getConfigEfectiva(empresaId)` resuelve la
   key por jerarquía (`empresas.holding_empresa_id`) — en PLATAFORMA usa proveedor/modelo/key del holding;
   `AiProviderService.completar` usa la config efectiva y registra `credencial_propia` real; `verificarCuota`
   NO aplica tope en PROPIA y sí en PLATAFORMA; toggle "Origen de la credencial" en Config IA (frontend).
   Verificado: PROPIA→key propia; PLATAFORMA→key del holding. **Cartera**: aplicado (usa `getConfigEfectiva`
   vía helper `resolverConfigIa` + pasa `credencial_propia`). **Ayuda IA**: por decisión, queda siempre a
   cuenta del holding (no usa credencial_modo).

2. ✅ **HECHO (2026-08-16) — Cuota por plan**: `planes.tokens_ia_mensual` (migración `20260816_ai_cuota_plan`) +
   `ai_empresa_config.origen_limite` (PLAN|MANUAL). `AiConfigService.aplicarCuotaDesdePlan` (no pisa el modo si
   la empresa ya eligió) llamado desde `SuscripcionesService.create`/`changePlan` (inyección @Optional para no
   romper los otros módulos que proveen el service). Campo `tokens_ia_mensual` expuesto en el CRUD de Planes
   (backend + PlanModal frontend).

3. ✅ **HECHO (2026-08-16) — Panel Holding "Consumo IA"**: módulo `src/ai-holding/` con `GET /ai-holding/consumo`
   (consumo/costo/cuota/modo por empresa de la red, resuelta por jerarquía) y `PATCH /ai-holding/empresas/:id/cuota`
   (ajuste manual del holding). Frontend: nueva pestaña "Consumo IA" en Suscripciones (`ConsumoIaHolding.jsx`):
   KPIs (tokens/costo del mes), tabla por empresa y diálogo para ajustar cuota + modo.

   **Renumeradas** (lo que sigue):
2. **Cuota por plan**: `tokens_ia_mensual` en Plan + herencia al activar suscripción + `origen_limite`.
3. **Panel Holding "Consumo IA"** en Suscripciones (ver/ajustar cuotas, costo USD por empresa, key plataforma).
4. **Solicitud de aumento** (empresa pide, holding aprueba).

## 8. Qué NO cambia
- El módulo de Conciliación (y toda la IA) sigue funcionando igual; solo cambia de **dónde sale la key**
  y **contra qué cuota** se mide. Empresas en modo `PROPIA` funcionan como hoy.
- Medición, tarifas, tope por empresa y chip de consumo ya están implementados y se reutilizan tal cual.

## 9. Riesgos / decisiones abiertas
- **Key de plataforma por holding vs global del sistema**: recomendado por holding (cada holding trae su
  propia cuenta de proveedor). Definir si un holding puede no tener key (entonces sus empresas deben usar PROPIA).
- **Reseteo mensual**: la cuota es por mes calendario (igual que `verificarCuota` hoy). Definir si los
  top-ups son por mes o saldo acumulable.
- **Concurrencia**: `verificarCuota` agrega por `ai_consumo`; con alto volumen, cachear o mover a contador.