NEXUS Credits

Resumo técnico

Plugin NEXUS (core) que gerencia os créditos e o consumo de recursos do NEXUS — monitora o uso das IAs, dispara alerta único ao atingir o limite configurável (padrão 90%) e mantém histórico completo de transações, com modal de billing, pools de bônus/plano e comando /credits no chat.

Escopo executado

• plugin.json: v1.0.0, slug nexus-credits, categoria "Core", is_core: true.
• Sem aba própria (sem tab.php): registerDoc "Sistema de Créditos" (ícone credit-card) + registerModal("credits") + 4 API actions + Fastr.
• Estado — JSON em admin_configs (cfg_key = 'credits_state'): total (550), used, bonus_total (500), bonus_used (409), plan_total (50), plan_used, warn_sent; histórico em credits_history (id INT PK AI, amount DECIMAL, reason TEXT, created_at DATETIME).
• credits_read() — defaults + merge do estado salvo + últimas 50 transações (amount, reason, created_at as at).
• credits_write() — remove history do estado e grava o JSON com INSERT ... ON DUPLICATE KEY UPDATE.
• credits_add($amount, $reason) — soma em used, grava a transação, calcula pct = used/total*100 e, quando pct >= credits.warn_pct (default 90%, via setting()) com warn_sent falso, chama notify_credit_warning() e marca warn_sent = true — alerta enviado uma única vez por ciclo.
• credits_set_total() — redefine o limite e reseta a flag de alerta.
• credits_reset() — apaga o estado, TRUNCATE credits_history e reinicia com os defaults (CREDIT_TOTAL, used 0, warn_sent false).
• credits_pct() — min(100, used/total*100).
• API: 4 actions — credits (leitura), credits_add (amount float + reason), ia_credits ({ ia_credits: leitura } para as IAs) e ia_credits_legacy (compat).
• Modal modals/credits.php (118 linhas, PHP server-rendered, tema slate + indigo/violet) — "System Billing / Resource Consumption"; cards Bonus Resource Pool (barra gradiente indigo-600 → violet-600 com glow; "Cycle expires in 29 days") e Base Tier Credits (barra slate-200, valores emerald-600); bloco condicional Distributed Node Telemetry com breakdown por IA (emoji, autor, last_updated, barras Bonus indigo-500/40 + Base emerald-500/40 — renderiza só quando $ia_credits['ias'] é preenchido externamente); painel admin Credential Management (bg-indigo-50) com form credits_set (Total Allocated Credits $, step 0.01, botão UPDATE POOL indigo-600) e form credits_reset (TERMINATE CYCLE & RESET COUNTER).
• Fastr — /credits (arg_required: false) — mostra saldo e histórico.
• Cron vazio (jobs: [], on-demand); sem migrations; sem i18n (UI do modal em inglês).

Stack e ferramentas

• PHP 8 (sem framework)
• MySQL 8 (admin_configs + credits_history)
• Tailwind CSS + Alpine.js (premium light, slate/indigo/violet)
• Plugin NEXUS (PluginManager: docs, modals, API actions, Fastr)

Tags operacionais

• Credits
• Créditos
• Billing
• Consumo de Recursos
• IA
• Core Plugin
• Plugin NEXUS

Resultado operacional

• Controle central do consumo: estado de créditos em um único JSON com histórico completo em MySQL.
• Alerta automático a 90%: notificação disparada uma única vez por ciclo (evita spam) quando o uso cruza o limiar configurável.
• Dois pools independentes: bônus (bonus_total/bonus_used) e plano (plan_total/plan_used) com visualização em barras no modal.
• Compatibilidade com as IAs: actions ia_credits e ia_credits_legacy expõem o saldo para o consumo dos assistentes.
• Controle administrativo: redefinir limite alocado e reiniciar o ciclo com 1 clique (UPDATE POOL / TERMINATE CYCLE & RESET COUNTER).
• Acesso rápido: comando /credits no chat mostra saldo e histórico sem abrir o painel.