AchieveApex: app internal

Generado desde achieveApex-Frontend/public/ai-docs el 2026-10-15. Contiene 33 archivos de la app internal. Para el contexto general del producto ver apex-resumen.md.

Internal

Consola interna de plataforma.

• Etapa: Admin
• Landing: /internal

Modulos

Funcionalidades internas

28 funcionalidades documentadas en 4 modulos. Ver la tabla de cada modulo.

id: ai-models app: internal nombre: AI Models estado: admin permiso: admin o superadmin

AI Models

Catálogo interno de modelos de IA, sus precios y las superficies de AchieveApex donde pueden utilizarse.

Para que sirve

• Decidir qué modelos de IA puede elegir cada superficie de asistentes.
• Registrar precios mostrados al cliente y la disponibilidad de un modelo.
• Sincronizar costes y metadatos de modelos ya registrados en OpenRouter.
• Detectar asistentes que usan un modelo antes de retirarlo.
• Ver qué asistentes y organizaciones realmente consumieron un modelo en un rango de fechas, y simular otro multiplicador.
• Migrar en lote asistentes hacia un modelo de reemplazo.

Que lo hace diferente

• El catálogo controla por separado conversaciones, tickets, AI chat y voz.
• Los asistentes que usan OpenRouter se enrutan por la integración de proveedor correspondiente.
• El coste real de OpenRouter se combina con un multiplicador de coste para el cobro de uso.
• Sincronizar el proveedor actualiza sus costes y metadatos sin sustituir los precios al cliente salvo que se solicite.
• Retirar un modelo usa borrado suave, preservando el historial y las configuraciones existentes.

Acceso

• Ruta principal: /internal/models
• Como se llega: Header app switcher > Internal > AI Models
• Permiso requerido: rol de plataforma admin o superadmin

Alcance tecnico

• Frontend: src/app/(internal)/internal/models/ y src/components/internal/ai-models/
• Backend: ai-models, ai-models-openrouter, ai-models-migrate-assistants y ai-models-consumption
• Superficies publicas: ninguna
• Integraciones externas: OpenRouter

Funcionalidades internas

Relaciones

• Depende de: OpenRouter y asistentes de IA.
• Usado por: asistentes de conversaciones, tickets, AI chat y voz.

Limitaciones y notas

• Ocultar un modelo de los selectores no elimina sus configuraciones existentes.

id: assistant-model-migration modulo: ai-models app: internal nombre: Migración de modelos de asistentes tipo: accion

Migración de modelos de asistentes

Permite cambiar en lote el modelo de los asistentes que actualmente usan otro modelo.

Que se logra

• Resultado: Los asistentes existentes pasan a un modelo de reemplazo de forma controlada y auditable.
• Caso de uso: Antes de retirar un modelo, el equipo mueve sus asistentes a otro modelo soportado sin reconfigurarlos uno a uno.
• Se combina con: Catálogo y configuración de modelos.

Donde esta

• Ruta: /internal/models
• Acceso en UI: Internal > AI Models > icono de migración
• Componente(s): MigrateAssistantsDialog.tsx

Como funciona

1. El administrador elige un modelo con asistentes asociados.
2. Abre la acción de migración.
3. Selecciona el modelo de destino y confirma.
4. La lista de modelos se actualiza al finalizar.

Reglas y validaciones

• La acción está deshabilitada si el modelo no tiene asistentes asociados.

Backend

• Servicios: ai-models-migrate-assistants (create), ai-models (find).
• Efectos: reasigna el modelo utilizado por asistentes existentes.

Relaciones

• Requiere: Catálogo de modelos.
• Dispara / afecta: asistentes de IA.

Notas

• El selector excluye el modelo de origen y los modelos con estado not_supported.

id: model-catalog modulo: ai-models app: internal nombre: Catálogo de modelos tipo: vista

Catálogo de modelos

Consulta los modelos de IA registrados, sus costes, disponibilidad y uso por asistentes.

Que se logra

• Resultado: El equipo conoce qué modelos están disponibles, en qué superficies se usan y cuál es su alcance real.
• Caso de uso: Un administrador detecta un modelo obsoleto que aún usan asistentes antes de preparar una migración.
• Se combina con: Configuración de modelo y migración de asistentes.

Donde esta

• Ruta: /internal/models
• Acceso en UI: Internal > AI Models
• Componente(s): AiModelsAdminList.tsx

Como funciona

1. Se busca por nombre y se filtra por proveedor o estado.
2. La lista muestra disponibilidad en conversaciones, tickets, AI chat y voz.
3. Se consulta el número de asistentes y organizaciones asignados a cada modelo.
4. Un rango de fechas (máximo 93 días, por defecto 30) muestra cuántos de esos asistentes y organizaciones tuvieron consumo real, el cobro a clientes, el costo del proveedor y una simulación al cambiar el multiplicador.
5. El enlace de asistentes abre el detalle del modelo.

Reglas y validaciones

• La lista se pagina en grupos de 25.
• Se señalan los modelos OpenRouter marcados como obsoletos.
• Asignado no implica uso: un modelo puede tener 100 asistentes y $0 de consumo en el rango.
• El volumen se toma de organization_wallet_transactions por el model_name escrito en la descripción.
• La simulación es costo_proveedor × multiplicador y no guarda el catálogo.

Backend

• Servicios: ai-models (find), ai-model-assistants (find), ai-models-consumption (find).
• Efectos: ninguno.

Relaciones

• Requiere: asistentes de IA.
• Dispara / afecta: Configuración de modelo.

Notas

• El estado visible es independiente de la disponibilidad por superficie.

id: model-configuration modulo: ai-models app: internal nombre: Configuración de modelo tipo: configuracion

Configuración de modelo

Permite registrar, editar, ocultar o retirar modelos del catálogo interno.

Que se logra

• Resultado: El catálogo controla qué modelos se ofrecen en cada tipo de asistente y bajo qué precio al cliente.
• Caso de uso: El equipo habilita un modelo para tickets sin exponerlo todavía a asistentes de voz.
• Se combina con: Catálogo de modelos y asistentes de IA.

Donde esta

• Ruta: /internal/models y /internal/models/[modelId]
• Acceso en UI: Internal > AI Models > Add model, editar, estado o eliminar
• Componente(s): AiModelDialog.tsx, AiModelDetail.tsx, AiModelsAdminList.tsx

Como funciona

1. Add model crea una entrada; editar modifica una existente.
2. Al editar se conservan proveedor y nombre técnico del modelo.
3. Al pulsar la insignia de estado alterna entre visible y soportado pero no visible.
4. Delete solicita confirmación antes de retirar la entrada.

Reglas y validaciones

• Las superficies configurables son conversaciones, tickets, AI chat y voz.
• Para mostrarse en selectores debe tener estado visible y estar habilitado para la superficie correspondiente.

Backend

• Servicios: ai-models (create/patch/remove/find).
• Efectos: cambia los modelos disponibles a asistentes.

Relaciones

• Requiere: Catálogo de modelos.
• Dispara / afecta: asistentes de IA.

Notas

• El borrado del servicio se gestiona como borrado suave.

id: openrouter-sync modulo: ai-models app: internal nombre: Sincronización con OpenRouter tipo: integracion

Sincronización con OpenRouter

Actualiza los metadatos y costes de proveedor de los modelos OpenRouter registrados.

Que se logra

• Resultado: Los metadatos y costes de proveedor de los modelos registrados quedan alineados con OpenRouter.
• Caso de uso: El equipo sincroniza el catálogo después de un cambio de precios del proveedor y decide si actualiza precios al cliente.
• Se combina con: Catálogo y configuración de modelos.

Donde esta

• Ruta: /internal/models
• Acceso en UI: Internal > AI Models > Sync
• Componente(s): AiModelsAdminList.tsx, OpenRouterCatalogDialog.tsx

Como funciona

1. Se abre OpenRouter catalog para consultar opciones del proveedor y prellenar una alta.
2. Sync solicita la actualización de los modelos registrados.
3. La lista se recarga e informa cuántos modelos se actualizaron o no se encontraron.

Reglas y validaciones

• La sincronización normal no sustituye los precios al cliente.
• La interfaz ofrece una sincronización adicional que actualiza los precios al cliente.

Backend

• Servicios: ai-models-openrouter (find/create).
• Efectos: actualiza metadatos y costes de OpenRouter.

Relaciones

• Requiere: Catálogo de modelos y OpenRouter.
• Dispara / afecta: precios presentados en el catálogo.

Notas

• Los slugs de OpenRouter se deben obtener del proveedor, no deducirse.

id: home app: internal nombre: Inicio interno estado: admin permiso: admin o superadmin

Inicio interno

Consola de administración transversal de AchieveApex para personal de plataforma. Reúne el acceso al soporte Nova y a las áreas internas.

Para que sirve

• Supervisar la adopción, fricción, coste y calidad de Nova Support en toda la plataforma.
• Convertir feedback de respuestas de Nova en casos atendidos por personas.
• Mantener habilidades de conocimiento global para que Nova responda sobre configuraciones reales.
• Acceder a las áreas internas sin cambiar el alcance global de administración.

Que lo hace diferente

• Nova conecta las métricas de uso, el feedback y el historial conversacional con el flujo real de soporte.
• Una calificación puede convertirse en un caso enlazado a la conversación que la originó.
• El conocimiento operativo se publica como habilidades consultables por Nova, no como texto fijo en la interfaz.
• La consola opera sobre toda la plataforma y no sobre una organización seleccionada.

Acceso

• Ruta principal: /internal
• Como se llega: Header app switcher > Internal
• Permiso requerido: rol de plataforma admin o superadmin

Alcance tecnico

• Frontend: rutas bajo src/app/(internal)/internal/ y componentes src/components/internal/nova-support/
• Backend: support-chat-conversations, support-chat-messages, support-chat-message-feedback, nova-support-knowledge-skills y reports
• Superficies publicas: ninguna
• Integraciones externas: OpenRouter para la respuesta de Nova

Funcionalidades internas

Relaciones

• Depende de: Support Admin y AI Models.
• Usado por: administradores de plataforma.

Limitaciones y notas

• Las rutas internas no llevan [orgId]; el selector de organización del encabezado no cambia su alcance global.

id: admin-navigation modulo: home app: internal nombre: Navegación de administración tipo: vista

Navegación de administración

Da acceso a la consola interna global y sus secciones administrativas.

Que se logra

• Resultado: El equipo interno llega a las herramientas globales correctas sin cambiar el contexto de una organización.
• Caso de uso: Un administrador abre Internal para pasar de la supervisión de Nova a partners, payouts o informes de plataforma.
• Se combina con: Nova Support, Administración de partners, AI Models e Informes internos.

Donde esta

• Ruta: /internal
• Acceso en UI: Header app switcher > Internal
• Componente(s): src/app/(internal)/internal/page.tsx

Como funciona

1. El administrador abre Internal.
2. Usa la barra lateral para entrar a Home, Nova Support, Partner Payouts o Reports.
3. Las áreas que requieren más privilegios redirigen a quien no sea superadmin.

Reglas y validaciones

• Solo los roles de plataforma admin y superadmin pueden permanecer en /internal.
• La sección Reports es exclusiva de superadmin.

Backend

• Servicios: ninguno para la navegación.

Relaciones

• Requiere: sesión con rol de plataforma.
• Dispara / afecta: acceso a módulos internos.

Notas

• No usa [orgId], porque opera sobre toda la plataforma.

id: nova-support-conversations modulo: home app: internal nombre: Conversaciones de Nova Support tipo: vista

Conversaciones de Nova Support

Permite a la administración leer el contexto de una conversación vinculada a una calificación de Nova.

Que se logra

• Resultado: El equipo puede evaluar una respuesta de Nova con el historial que la originó antes de intervenir.
• Caso de uso: Tras una mala calificación, un administrador revisa el diálogo y decide si crea un caso de seguimiento.
• Se combina con: Feedback de Nova Support y Administración de soporte.

Donde esta

• Ruta: /internal/nova-support/feedback
• Acceso en UI: Internal > Nova Support > Feedback > View details
• Componente(s): NovaSupportFeedbackDetailSheet.tsx

Como funciona

1. Se abre el detalle de una fila de feedback.
2. La vista obtiene la conversación y sus mensajes.
3. El administrador usa el contexto para evaluar la respuesta calificada o crear un caso.

Reglas y validaciones

• Solo se consulta desde una fila que tenga conversación relacionada.

Backend

• Servicios: support-chat-conversations (get), support-chat-messages (find).
• Efectos: ninguno.

Relaciones

• Requiere: Feedback de Nova Support.
• Dispara / afecta: creación de casos de soporte.

Notas

• No se identificó una pantalla interna independiente para explorar todas las conversaciones.

id: nova-support-feedback modulo: home app: internal nombre: Feedback de Nova Support tipo: vista

Feedback de Nova Support

Centraliza las calificaciones y comentarios que los usuarios dejan sobre respuestas de Nova.

Que se logra

• Resultado: Las respuestas mal valoradas quedan trazables y pueden convertirse en atención humana con su contexto.
• Caso de uso: Un usuario califica negativamente una respuesta; el equipo lee el intercambio y abre un caso para contactarlo.
• Se combina con: Conversaciones de Nova Support y Administración de soporte.

Donde esta

• Ruta: /internal/nova-support/feedback
• Acceso en UI: Internal > Nova Support > Feedback
• Componente(s): NovaSupportFeedbackList.tsx, NovaSupportFeedbackDetailSheet.tsx, NovaSupportFeedbackCreateCaseDialog.tsx

Como funciona

1. Se revisa la fila con organización, usuario, calificación, comentario, estado y página.
2. View details abre el contexto de la respuesta y conversación relacionada.
3. Create support case crea un caso para que Support Admin contacte al solicitante.
4. Open case lleva al caso asociado cuando ya existe.

Reglas y validaciones

• El caso creado desde feedback conserva el vínculo con la conversación de Nova.

Backend

• Servicios: support-chat-message-feedback (find), support-chat-conversations (get), support-chat-messages (find), support-cases (create).
• Efectos: el caso se enlaza al feedback y entra al flujo de routing de soporte.

Relaciones

• Requiere: Uso de Nova Support.
• Dispara / afecta: Support Admin.

Notas

• Un caso creado desde esta vista queda identificado como creado manualmente.

id: nova-support-knowledge modulo: home app: internal nombre: Conocimiento de Nova Support tipo: configuracion

Conocimiento de Nova Support

Permite mantener habilidades de conocimiento globales que Nova consulta cuando son pertinentes.

Que se logra

• Resultado: Nova incorpora conocimiento operativo mantenido por el equipo sin alterar su comportamiento general.
• Caso de uso: Soporte crea una habilidad sobre una configuración frecuente para que Nova la consulte al atender a clientes.
• Se combina con: Uso, feedback y conversaciones de Nova Support.

Donde esta

• Ruta: /internal/nova-support/knowledge
• Acceso en UI: Internal > Nova Support > Knowledge
• Componente(s): NovaSupportKnowledgeList.tsx, NovaSupportKnowledgeDialog.tsx

Como funciona

1. Add knowledge skill abre el editor para crear una habilidad.
2. La lista permite consultar título, When to use, estado y contenido.
3. Edit knowledge skill actualiza una habilidad.
4. Delete knowledge skill la elimina.

Campos y opciones

Reglas y validaciones

• Nova recibe en su índice el identificador, título y When to use; obtiene el Markdown completo al invocar la habilidad.

Backend

• Servicios: nova-support-knowledge-skills (find/create/patch/remove).
• Efectos: actualiza el conocimiento disponible para Nova Support.

Relaciones

• Requiere: Nova Support.
• Dispara / afecta: respuestas de Nova Support.

Notas

• El identificador operativo sigue el formato knowledge:{id}.

id: nova-support-usage modulo: home app: internal nombre: Uso de Nova Support tipo: vista

Uso de Nova Support

Muestra la adopción, fricción y calidad operativa de Nova Support a nivel plataforma.

Que se logra

• Resultado: El equipo identifica adopción, fricción, calidad, coste y escalaciones de Nova en toda la plataforma.
• Caso de uso: El responsable de soporte excluye el uso interno y detecta qué organizaciones o páginas generan más escalaciones.
• Se combina con: Feedback, conocimiento y escalaciones de Nova Support.

Donde esta

• Ruta: /internal/nova-support/usage
• Acceso en UI: Internal > Nova Support > Usage
• Componente(s): NovaSupportUsageDashboard.tsx, NovaSupportUsageCharts.tsx

Como funciona

1. Se selecciona el rango de fechas y la granularidad.
2. Se puede activar Exclude internal usage para ocultar conversaciones de administradores.
3. Se consultan indicadores, crecimiento, cohortes, páginas, herramientas, escalaciones, feedback y organizaciones.
4. Refresh vuelve a cargar los datos.

Reglas y validaciones

• El filtro de uso interno se activa por defecto.
• Las métricas de coste y latencia solo aparecen cuando existe metadato de IA.

Backend

• Servicios: reports (get: novaSupportUsageOverview, novaSupportUsagePages, novaSupportUsageTools, novaSupportUsageOrganizations, novaSupportUsageCohorts).
• Efectos: ninguno.

Relaciones

• Requiere: conversaciones y mensajes de Nova Support.
• Dispara / afecta: la priorización de mejoras y soporte.

Notas

• La tabla de organizaciones es paginada.

id: partners-admin app: internal nombre: Administración de partners estado: admin permiso: admin o superadmin

Administración de partners

Herramientas internas para revisar partners, su atribución de clientes, comisiones, pagos y desempeño.

Para que sirve

• Revisar y aprobar solicitudes de agencias y afiliados.
• Atribuir organizaciones cliente a partners y verificar sus relaciones.
• Auditar comisiones y decidir qué retiros de partners se procesan.
• Ejecutar y seguir pagos de partners en Wise.
• Medir crecimiento, activación, churn, concentración y economía del programa.
• Identificar organizaciones Implementor y su situación dentro del programa.

Que lo hace diferente

• La atribución de clientes, comisiones y payouts se conectan en el mismo flujo operativo.
• Los payouts se ejecutan en Wise y se concilian por webhook y proceso programado; no se marcan manualmente como pagados.
• Un reintento de financiación reutiliza la transferencia pendiente, evitando duplicar pagos.
• La analítica distingue el tipo de partner desde el cliente referido, evitando una clasificación errónea en el ledger.
• El programa reúne agencias y afiliados bajo una operación común, conservando sus datos de referencia y economía.

Acceso

• Ruta principal: /internal/partners
• Como se llega: Header app switcher > Internal > Partners
• Permiso requerido: rol de plataforma admin o superadmin; algunas vistas requieren superadmin

Alcance tecnico

• Frontend: src/app/(internal)/internal/partners/ y src/components/internal/partners/
• Backend: partners-agency-applications, partners-transactions, partners-payouts, partner-payout-accounts, partners-metrics y reports
• Superficies publicas: ninguna en esta consola
• Integraciones externas: Wise para ejecución de payouts

Funcionalidades internas

Relaciones

• Depende de: Organizations, Stripe Billing y Wallet.
• Usado por: Agencies & Affiliates y Support Admin.

Limitaciones y notas

• El pago efectivo lo confirma Wise mediante webhooks y conciliación; no se puede marcar manualmente como procesado o pagado.

id: partner-analytics modulo: partners-admin app: internal nombre: Analítica de partners tipo: vista

Analítica de partners

Mide el rendimiento global del programa de agencias y afiliados.

Que se logra

• Resultado: El equipo mide crecimiento, activación, concentración, churn, margen y economía del programa.
• Caso de uso: La dirección compara la productividad de agencias y afiliados durante 12 meses para ajustar el programa.
• Se combina con: Clientes, comisiones, payouts, Stripe Billing y Wallet.

Donde esta

• Ruta: /internal/partners/analytics
• Acceso en UI: Internal > Partners > Analytics
• Componente(s): PartnersAnalytics.tsx, PartnersAnalyticsSections.tsx

Como funciona

1. Se escoge el periodo de 6, 12 o 24 meses.
2. Se navega entre Overview, Growth, Network y Economics.
3. Refresh vuelve a obtener los datos de la vista activa.

Reglas y validaciones

• Los indicadores comparan el mes en curso con el mismo tramo transcurrido del mes anterior.
• El backend admite entre 1 y 36 meses.

Backend

• Servicios: reports (get: partnersAnalyticsOverview, partnersAnalyticsGrowth, partnersAnalyticsNetwork, partnersAnalyticsEconomics).
• Efectos: ninguno.

Relaciones

• Requiere: Partners, Stripe Billing y Wallet.
• Dispara / afecta: decisiones de operación del programa.

Notas

• Los resultados se almacenan temporalmente por vista y periodo en la interfaz.

id: partner-applications modulo: partners-admin app: internal nombre: Revisión de aplicaciones de partner tipo: accion

Revisión de aplicaciones de partner

Permite revisar solicitudes de agencia o afiliado y decidir su estado.

Que se logra

• Resultado: Las solicitudes de agencia o afiliado avanzan por un proceso de revisión con estado visible.
• Caso de uso: El equipo revisa la propuesta y documentación de una agencia y la aprueba para activar su condición de partner.
• Se combina con: Directorio y perfil de partners.

Donde esta

• Ruta: /internal/partners/applications y /internal/partners/applications/[applicationId]
• Acceso en UI: Internal > Partners > Applications
• Componente(s): PartnersApplicationsList.tsx, PartnerApplicationDetail.tsx

Como funciona

1. Se filtran y abren las aplicaciones.
2. El detalle muestra organización, datos de promoción, expectativa de clientes e información adicional.
3. Se selecciona pending, reviewing, approved o denied y se guarda el cambio.
4. Si existe, se abre el documento W-8BEN asociado.

Reglas y validaciones

• Solo se aceptan los cuatro estados mostrados en el selector.

Backend

• Servicios: partners-agency-applications (find/get/patch), reports (get: partnerApplicationsList).
• Efectos: al aprobar se sincroniza el estado de agencia de la organización.

Relaciones

• Requiere: Organizations.
• Dispara / afecta: directorio de partners.

Notas

• El formulario público de solicitud está fuera de esta consola.

id: partner-clients modulo: partners-admin app: internal nombre: Clientes referidos tipo: accion

Clientes referidos

Administra qué organizaciones cliente se atribuyen a un partner.

Que se logra

• Resultado: La atribución de clientes determina de forma explícita quién recibe las comisiones futuras.
• Caso de uso: Operaciones asigna una organización recién captada a la agencia que la refirió y puede revertir una atribución errónea.
• Se combina con: Perfil y comisiones de partner.

Donde esta

• Ruta: /internal/partners/directory/[orgId]/clients
• Acceso en UI: Internal > Partners > Directory > partner > Clients
• Componente(s): PartnerClientsSection

Como funciona

1. Se revisan los clientes y sus ingresos de suscripción, IA y comisión acumulada.
2. Assign client busca organizaciones sin partner asignado.
3. Se elige una organización y se confirma la asignación.
4. Unassign solicita confirmación antes de desvincularla.

Reglas y validaciones

• No se puede asignar el partner a sí mismo ni una organización ya atribuida.

Backend

• Servicios: reports (get: partnerClientsList, partnerAssignReferral), organizations (find).
• Efectos: la atribución modifica qué partner recibe comisiones futuras.

Relaciones

• Requiere: perfil de partner y Organizations.
• Dispara / afecta: comisiones de partner.

Notas

• El listado carga hasta 50 clientes por consulta.

id: partner-commissions modulo: partners-admin app: internal nombre: Comisiones de partner tipo: vista

Comisiones de partner

Consulta el ledger de comisiones de un partner y su progreso hacia pago.

Que se logra

• Resultado: El equipo puede explicar el origen, estado y avance hacia pago de cada comisión.
• Caso de uso: Finanzas revisa las comisiones elegibles de una agencia antes de validar su retiro.
• Se combina con: Clientes y cola de payouts.

Donde esta

• Ruta: /internal/partners/directory/[orgId]/commissions
• Acceso en UI: Internal > Partners > Directory > partner > Commissions
• Componente(s): PartnerCommissionsSection

Como funciona

1. Se elige un origen: All, suscripción, uso de IA o administración.
2. Las tarjetas permiten filtrar por estado.
3. La tabla muestra cliente, fecha, tasa, base, importe y estado.
4. Se pagina el resultado.

Reglas y validaciones

• Los estados disponibles son pending, eligible, paid y cancelled.
• Las comisiones canceladas se excluyen de los agregados de ingresos y costes.

Backend

• Servicios: reports (get: partnerCommissions), partners-transactions (ledger).
• Efectos: ninguno.

Relaciones

• Requiere: Clientes referidos.
• Dispara / afecta: solicitudes de payout.

Notas

• La clasificación agencia/afiliado se determina por el tipo del cliente referido, no por el tipo registrado en la transacción.

id: partner-directory modulo: partners-admin app: internal nombre: Directorio de partners tipo: vista

Directorio de partners

Localiza organizaciones del programa de partners y abre su ficha administrativa.

Que se logra

• Resultado: El equipo localiza rápidamente un partner y accede a sus relaciones, comisiones y pagos.
• Caso de uso: Operaciones busca una agencia antes de revisar los clientes que refirió y los retiros que tiene pendientes.
• Se combina con: Perfil, clientes, comisiones y payouts de partner.

Donde esta

• Ruta: /internal/partners/directory
• Acceso en UI: Internal > Partners > Directory
• Componente(s): PartnersDirectoryList.tsx

Como funciona

1. El administrador consulta el listado y sus filtros.
2. Abre una organización para ver sus pestañas de detalle.

Reglas y validaciones

• La ficha usa el identificador de organización en la ruta.

Backend

• Servicios: reports (get: partnerOrganizationsByIds y vistas de partner), organizations (find/get).
• Efectos: ninguno.

Relaciones

• Requiere: Organizations.
• Dispara / afecta: perfil de partner.

Notas

• La ruta de detalle es /internal/partners/directory/[orgId]/overview.

id: partner-implementors modulo: partners-admin app: internal nombre: Implementadores tipo: vista

Implementadores

Consulta las organizaciones clasificadas como implementadoras dentro del programa de partners.

Que se logra

• Resultado: La operación identifica organizaciones del plan Implementor y su avance dentro del programa de partners.
• Caso de uso: El equipo filtra implementadores que aún no son partners o tienen una solicitud pendiente para dar seguimiento.
• Se combina con: Directorio y aplicaciones de partners.

Donde esta

• Ruta: /internal/partners/implementors
• Acceso en UI: Internal > Partners > Implementors
• Componente(s): PartnersImplementorsList.tsx

Como funciona

1. Se abre el listado de implementadores.
2. Se filtra o navega por los resultados disponibles.

Reglas y validaciones

• El listado se basa en organizaciones con el plan Implementor y permite filtrar por situación de partner o solicitud.

Backend

• Servicios: reports (get: partnerImplementorsList).
• Efectos: ninguno.

Relaciones

• Requiere: Organizations y programa de partners.
• Dispara / afecta: ninguna funcionalidad identificada.

Notas

• admin-recruitment está asignado al alcance, pero no se localizó una ruta o componente interno equivalente en las rutas solicitadas.

id: partner-overview modulo: partners-admin app: internal nombre: Perfil de partner tipo: vista

Perfil de partner

Muestra el estado de partner, plan, tarifas de comisión y organización que lo refirió.

Que se logra

• Resultado: La operación obtiene una visión unificada de la situación comercial y de referencia de cada partner.
• Caso de uso: Un responsable comprueba el plan, las tasas habituales y la organización que refirió a un partner antes de atender una consulta.
• Se combina con: Clientes, comisiones, cuentas de payout y equipo.

Donde esta

• Ruta: /internal/partners/directory/[orgId]/overview
• Acceso en UI: Internal > Partners > Directory > partner > Overview
• Componente(s): PartnerOverviewSection

Como funciona

1. Se abre un partner desde el directorio.
2. Overview muestra su estado, plan, tarifas típicas, antigüedad y relación de referencia.
3. Se puede abrir el partner que lo refirió cuando existe.

Reglas y validaciones

• Las tarifas típicas dependen de los clientes referidos; pueden no estar disponibles sin clientes.

Backend

• Servicios: reports (get: partnerOverview).
• Efectos: ninguno.

Relaciones

• Requiere: Directorio de partners.
• Dispara / afecta: clientes, comisiones y payouts del partner.

Notas

• Esta vista incluye una pestaña Application para consultar la solicitud asociada.

id: partner-payout-accounts modulo: partners-admin app: internal nombre: Cuentas de payout tipo: vista

Cuentas de payout

Consulta las cuentas de cobro que un partner ha registrado para recibir payouts.

Que se logra

• Resultado: El equipo verifica que un payout se dirija a una cuenta activa sin revelar información bancaria sensible.
• Caso de uso: Antes de aprobar un retiro, operaciones confirma la moneda, país y cuenta predeterminada del partner.
• Se combina con: Perfil y ejecución de payouts.

Donde esta

• Ruta: /internal/partners/directory/[orgId]/payout-accounts
• Acceso en UI: Internal > Partners > Directory > partner > Payout accounts
• Componente(s): PartnerPayoutAccountsSection

Como funciona

1. Se abre la pestaña de cuentas de payout del partner.
2. Se consultan identificador, etiqueta, moneda, país, estado y cuenta predeterminada.

Reglas y validaciones

• La consola muestra detalles enmascarados; no expone datos bancarios sin proteger.

Backend

• Servicios: partner-payout-accounts (find).
• Efectos: ninguno.

Relaciones

• Requiere: perfil de partner.
• Dispara / afecta: ejecución de payouts.

Notas

• La creación de cuentas ocurre en la superficie del partner, no en esta vista.

id: partner-payout-execution modulo: partners-admin app: internal nombre: Ejecución y conciliación de payouts tipo: integracion

Ejecución y conciliación de payouts

Permite aprobar y gestionar ejecuciones reales de payout con Wise.

Que se logra

• Resultado: Los payouts se ejecutan en Wise y sus resultados vuelven conciliados con las comisiones reservadas.
• Caso de uso: Finanzas aprueba un retiro; si Wise espera fondos, reintenta su financiación sin crear una transferencia duplicada.
• Se combina con: Cola de payouts, comisiones y notificaciones de payout.

Donde esta

• Ruta: /internal/partners/payouts/[payoutId] (también /internal/partner-payouts)
• Acceso en UI: Internal > Partner Payouts > payout
• Componente(s): PartnerPayoutDetailDialog.tsx, PartnerPayoutDetailPage.tsx

Como funciona

1. Se abre el payout y se revisan importe fuente, fee, importe objetivo, tasa y estado de Wise.
2. Approve & execute solicita una confirmación explícita y envía la ejecución.
3. Según el estado se puede Reject, Cancel payout, Reopen as pending, Retry execution o Retry funding.
4. Tras aprobar o financiar de nuevo, la interfaz consulta el payout hasta que cambie de estado.

Reglas y validaciones

• admin y superadmin de plataforma pueden hacer patch sin pertenecer a la organización del partner; el partner solo puede pedir el retiro si es miembro de su org.
• pending puede aprobarse, rechazarse o cancelarse; rejected puede volver a pendiente.
• processing y paid solo los actualizan Wise y la conciliación programada.
• Retry funding reutiliza la transferencia cuando Wise espera fondos; no crea una segunda transferencia.
• Un payout fallido conserva sus comisiones reservadas; solo cancelarlo las libera.
• Fallos amount_mismatch y charged_back requieren investigación manual y no admiten reintento automático.

Backend

• Servicios: partners-payouts (patch).
• Hooks relevantes: al aprobar ejecuta el payout; los cambios sincronizan comisiones y envían notificaciones.
• Efectos: crea o financia transferencias Wise; el webhook y cron-reconcile-partner-payouts actualizan el resultado.

Relaciones

• Requiere: Cola de payouts y cuenta de payout activa.
• Dispara / afecta: ledger de comisiones y notificaciones de payout.

Notas

• La comisión de Wise se descuenta del importe que recibirá el partner.

id: partner-payout-review modulo: partners-admin app: internal nombre: Cola de payouts tipo: vista

Cola de payouts

Permite revisar solicitudes de retiro de partners antes y después de su ejecución.

Que se logra

• Resultado: La operación tiene una cola única para priorizar retiros y comprobar su estado antes o después de ejecutarlos.
• Caso de uso: Finanzas filtra los retiros pendientes y abre uno para validar las comisiones y el destino de pago.
• Se combina con: Comisiones, cuentas y ejecución de payouts.

Donde esta

• Ruta: /internal/partner-payouts y /internal/partners/payouts
• Acceso en UI: Internal > Partner Payouts
• Componente(s): PartnerPayoutsReviewList.tsx, PartnerPayoutDetailDialog.tsx

Como funciona

1. Se elige una pestaña de estado: All, Pending, Approved, Processing, Paid o Failed.
2. Se revisan partner, importe, transacciones, fecha y datos de ejecución de Wise.
3. Se abre una fila para ver el detalle y acciones permitidas.
4. Refresh actualiza la cola.

Reglas y validaciones

• El filtro inicial es Pending.
• rejected y cancelled existen pero no tienen pestaña propia.

Backend

• Servicios: partners-payouts (find/get), reports (get: partnerOrganizationsByIds).
• Efectos: ninguno al consultar.

Relaciones

• Requiere: Comisiones de partner y cuentas de payout.
• Dispara / afecta: Ejecución y conciliación Wise.

Notas

• La lista usa paginación de 50 elementos.

id: partner-team modulo: partners-admin app: internal nombre: Equipo de partner tipo: vista

Equipo de partner

Consulta los miembros de una organización partner y sus roles.

Que se logra

• Resultado: La operación sabe quién integra un partner y con qué rol, sin modificar su equipo.
• Caso de uso: Soporte identifica al contacto adecuado de una agencia antes de atender una incidencia de pagos.
• Se combina con: Perfil y Administración de soporte.

Donde esta

• Ruta: /internal/partners/directory/[orgId]/team
• Acceso en UI: Internal > Partners > Directory > partner > Team
• Componente(s): PartnerTeamSection

Como funciona

1. Se abre la ficha de una organización.
2. La pestaña Team muestra nombre, correo y rol de cada integrante.

Reglas y validaciones

• Es una vista de consulta; no expone acciones para cambiar miembros.

Backend

• Servicios: organizations-users (find).
• Efectos: ninguno.

Relaciones

• Requiere: Organizations.
• Dispara / afecta: ninguna funcionalidad identificada.

Notas

• Carga hasta 50 miembros por consulta.

id: reports app: internal nombre: Informes internos estado: admin permiso: superadmin

Informes internos

Informes globales de plataforma, incluidos el constructor asistido por IA y las vistas administrativas de wallet, suscripciones y afiliados.

Para que sirve

• Crear páginas globales para vigilar la operación de toda la plataforma.
• Construir gráficos, tablas y métricas sobre suscripciones, wallet, partners u otros datos internos.
• Pedir a la IA que cree o modifique informes desde una descripción en lenguaje natural.
• Aplicar filtros por página solo a los widgets que los necesitan.
• Consultar reportes administrativos preexistentes de wallet, suscripciones y afiliados.

Que lo hace diferente

• El constructor con IA crea y ajusta páginas y widgets internos después de probar sus consultas.
• Los informes son globales y no se limitan automáticamente a una organización.
• El modelo de filtros enlaza explícitamente cada widget, evitando cambios no deseados en una página.
• Conviven un lienzo configurable por IA y reportes administrativos especializados de wallet, suscripciones y afiliados.
• El acceso es exclusivo de superadmin, separado de los informes de cada organización.

Acceso

• Ruta principal: /internal/reports
• Como se llega: Header app switcher > Internal > Reports
• Permiso requerido: rol de plataforma superadmin; las rutas /reports/* son reportes administrativos separados

Alcance tecnico

• Frontend: src/app/(internal)/internal/reports/, src/components/internal/reports/ y src/app/(reports)/reports/
• Backend: internal-report-pages, internal-report-widgets, internal-report-widget-data, internal-ai-report-builder y reports
• Superficies publicas: ninguna
• Integraciones externas: OpenRouter para el constructor asistido

Funcionalidades internas

Relaciones

• Depende de: Organizations, Wallet, Stripe Billing y Partners.
• Usado por: personal de plataforma.

Limitaciones y notas

• Los informes internos son globales y no se limitan automáticamente a una organización.

id: active-subscriptions modulo: reports app: internal nombre: Suscripciones activas tipo: vista

Suscripciones activas

Permite consultar y filtrar el reporte de suscripciones activas de la plataforma.

Que se logra

• Resultado: La plataforma dispone de una lista filtrable de suscripciones activas para seguimiento comercial y operativo.
• Caso de uso: El equipo filtra por plan y estado para revisar las cuentas activas de una oferta concreta.
• Se combina con: Stripe Billing e Informes internos.

Donde esta

• Ruta: /reports/subscriptions/active
• Acceso en UI: Reports > Subscriptions > Active
• Componente(s): src/app/(reports)/reports/subscriptions/active/page.tsx

Como funciona

1. La página carga opciones de planes y estados.
2. El administrador aplica los filtros disponibles.
3. Se consulta y muestra el listado de suscripciones activas.

Reglas y validaciones

• La página carga opciones de planes y estados antes de consultar el listado.

Backend

• Servicios: reports/activeSubscriptions, reports/subscriptionPlans, reports/subscriptionStatuses.
• Efectos: ninguno.

Relaciones

• Requiere: Stripe Billing.
• Dispara / afecta: ninguna funcionalidad identificada.

Notas

• Es un reporte administrativo independiente de los widgets internos.

id: affiliate-reports modulo: reports app: internal nombre: Reportes de afiliados tipo: vista

Reportes de afiliados

Reúne vistas administrativas de resumen, listado y transacciones de afiliados.

Que se logra

• Resultado: El equipo revisa la deuda, pagos y transacciones del canal de afiliados desde vistas separadas.
• Caso de uso: Finanzas consulta las transacciones de un afiliado y exporta el detalle para una conciliación interna.
• Se combina con: Administración y analítica de partners.

Donde esta

• Ruta: /reports/affiliates/overview, /reports/affiliates/list y /reports/affiliates/transactions
• Acceso en UI: Reports > Affiliates
• Componente(s): páginas bajo src/app/(reports)/reports/affiliates/

Como funciona

1. Se elige el resumen, listado o transacciones.
2. La vista consulta los datos administrativos correspondientes.

Reglas y validaciones

• La vista de transacciones permite filtrar por afiliado, estado, tipo, origen y fechas, y exportar el resultado.

Backend

• Servicios: reports, partners-transactions.
• Efectos: ninguno.

Relaciones

• Requiere: Administración de partners.
• Dispara / afecta: ninguna funcionalidad identificada.

Notas

• No confundir estas vistas globales con la analítica de partners en /internal/partners/analytics.

id: ai-report-builder modulo: reports app: internal nombre: Constructor de informes con IA tipo: automatizacion

Constructor de informes con IA

Permite pedir en lenguaje natural la creación o modificación de páginas y widgets de informes internos.

Que se logra

• Resultado: El equipo crea o ajusta informes de plataforma desde una solicitud en lenguaje natural con consultas probadas.
• Caso de uso: Un superadministrador pide una vista de ingresos por partner y la IA añade los widgets a la página seleccionada.
• Se combina con: Páginas, widgets y filtros de informes.

Donde esta

• Ruta: /internal/reports
• Acceso en UI: Internal > Reports > Add with AI
• Componente(s): InternalReportsAddSheet.tsx, useInternalAIReportBuilder.ts

Como funciona

1. Se abre Add with AI.
2. El administrador describe el informe o cambio solicitado.
3. Nova analiza el esquema disponible, prueba las consultas necesarias y crea o modifica páginas y widgets.
4. El lienzo vuelve a cargar las piezas afectadas.

Reglas y validaciones

• Las consultas guardadas deben ser solo de lectura y se prueban antes de guardar un widget.
• El constructor opera con datos globales de plataforma.

Backend

• Servicios: internal-ai-report-builder (create), internal-report-pages y internal-report-widgets.
• Efectos: puede crear, actualizar o eliminar páginas y widgets.

Relaciones

• Requiere: Páginas de informe y Widgets y diseño.
• Dispara / afecta: datos mostrados en el lienzo.

Notas

• El progreso se entrega por usuario, no por organización.

id: report-filters modulo: reports app: internal nombre: Filtros de informe tipo: configuracion

Filtros de informe

Permite definir filtros de una página y elegir qué widgets responden a ellos.

Que se logra

• Resultado: Cada página entrega a sus widgets solo los filtros que correspondan, sin alterar los demás resultados.
• Caso de uso: Un superadministrador aplica un rango de fechas y actualiza únicamente los gráficos vinculados a ese filtro.
• Se combina con: Páginas y widgets de informes.

Donde esta

• Ruta: /internal/reports
• Acceso en UI: Internal > Reports > página > filtros
• Componente(s): ReportFilterBar.tsx, InternalReportsCanvasView.tsx

Como funciona

1. Se definen filtros para la página al crearla o mediante el constructor con IA.
2. Cada widget vincula de forma explícita los filtros que debe recibir.
3. El usuario aplica valores en la barra de filtros.
4. Solo los widgets vinculados recargan sus datos.

Reglas y validaciones

• Un filtro sin vínculo no afecta al widget.
• Los filtros pueden ser de fecha, selección, selección múltiple, rango numérico, texto o booleano.

Backend

• Servicios: internal-report-pages (patch), internal-report-widgets (patch), internal-report-widget-data (create).
• Efectos: modifica el conjunto de datos mostrado por los widgets vinculados.

Relaciones

• Requiere: Páginas de informe y Widgets y diseño.
• Dispara / afecta: ejecución de datos de widgets.

Notas

• Los filtros fijos de un widget no se exponen al lector del informe.

id: report-pages modulo: reports app: internal nombre: Páginas de informe internas tipo: configuracion

Páginas de informe internas

Organiza los informes globales de plataforma en páginas seleccionables desde una barra lateral.

Que se logra

• Resultado: Los informes globales se agrupan en páginas reutilizables y enlazables para la operación de plataforma.
• Caso de uso: Un superadministrador crea una página de crecimiento y comparte su enlace interno con el equipo directivo.
• Se combina con: Widgets, filtros y constructor de informes con IA.

Donde esta

• Ruta: /internal/reports
• Acceso en UI: Internal > Reports > New report
• Componente(s): ReportsSidebar.tsx, InternalReportsProvider.tsx

Como funciona

1. New report crea una nueva página.
2. La barra lateral permite seleccionarla.
3. La URL conserva la página seleccionada para enlaces directos.
4. El nombre se puede editar directamente en el lienzo.

Reglas y validaciones

• Solo superadmin puede acceder a Informes internos.

Backend

• Servicios: internal-report-pages (find/create/patch/remove).
• Efectos: al seleccionar una página se cargan sus widgets.

Relaciones

• Requiere: Widgets y diseño.
• Dispara / afecta: Constructor de informes con IA.

Notas

• Las páginas son globales, no pertenecen a una organización.

id: report-widgets modulo: reports app: internal nombre: Widgets y diseño de informes tipo: configuracion

Widgets y diseño de informes

Presenta visualizaciones y bloques de contenido en un lienzo que se puede mover y redimensionar.

Que se logra

• Resultado: Una página de informe presenta métricas, gráficos, tablas y contenido en un diseño adaptable.
• Caso de uso: Operaciones reorganiza los widgets de una página para revisar primero suscripciones y después consumo de wallet.
• Se combina con: Páginas, filtros y constructor de informes con IA.

Donde esta

• Ruta: /internal/reports
• Acceso en UI: Internal > Reports > página seleccionada
• Componente(s): InternalReportsCanvasView.tsx, ReportCanvasGrid.tsx, ReportCanvasWidget.tsx, ReportWidgetChart.tsx

Como funciona

1. Al elegir una página se cargan sus widgets.
2. Se arrastra o redimensiona un widget para ajustar el diseño.
3. Se edita el título en línea o se elimina desde sus acciones.
4. Los widgets con consulta actualizan sus datos al cambiar filtros vinculados o refrescar.

Reglas y validaciones

• Los tipos disponibles incluyen métricas, gráficos, tablas y bloques de diseño.
• El diseño se guarda por widget.

Backend

• Servicios: internal-report-widgets (find/create/patch/remove), internal-report-widget-data (create).
• Efectos: ejecuta la consulta guardada de cada widget al obtener sus datos.

Relaciones

• Requiere: Páginas de informe y Filtros de informe.
• Dispara / afecta: Constructor de informes con IA.

Notas

• Un widget sin consulta puede funcionar como bloque de diseño.

id: wallet-breakdowns modulo: reports app: internal nombre: Desgloses de wallet tipo: vista

Desgloses de wallet

Ofrece cortes administrativos de wallet por día, mes, concepto y organización.

Que se logra

• Resultado: El equipo puede localizar variaciones de consumo de wallet por tiempo, concepto u organización.
• Caso de uso: Finanzas detecta un aumento mensual y lo desglosa por concepto para ubicar el origen.
• Se combina con: Resumen de wallet e Informes internos.

Donde esta

• Ruta: /reports/wallet/daily, /reports/wallet/monthly, /reports/wallet/by-concept y /reports/wallet/by-organization
• Acceso en UI: Reports > Wallet
• Componente(s): páginas de wallet bajo src/app/(reports)/reports/wallet/

Como funciona

1. Se abre el desglose necesario.
2. Las vistas diaria y mensual cargan los conceptos disponibles.
3. Se aplican los filtros de la página para consultar el corte.

Reglas y validaciones

• Las vistas diaria y mensual cargan los conceptos disponibles antes de aplicar sus filtros.

Backend

• Servicios: reports/daily, reports/monthly, reports/by-concept, reports/walletConcepts.
• Efectos: ninguno.

Relaciones

• Requiere: Wallet y Organizations.
• Dispara / afecta: ninguna funcionalidad identificada.

Notas

• Son vistas administrativas separadas del constructor de informes internos.

id: wallet-overview modulo: reports app: internal nombre: Resumen de wallet tipo: vista

Resumen de wallet

Muestra el informe administrativo de resumen de movimientos y saldo de wallet.

Que se logra

• Resultado: La operación obtiene una visión consolidada del consumo y los movimientos de wallet de la plataforma.
• Caso de uso: Finanzas abre el resumen para revisar el consumo de wallet y exportar el resultado del periodo.
• Se combina con: Desgloses de wallet e Informes internos.

Donde esta

• Ruta: /reports/wallet/overview
• Acceso en UI: Reports > Wallet > Overview
• Componente(s): src/app/(reports)/reports/wallet/overview/page.tsx

Como funciona

1. El administrador abre el resumen de wallet.
2. Consulta los indicadores y resultados que devuelve el reporte.

Reglas y validaciones

• La vista permite exportar el resumen de consumo de wallet en CSV.

Backend

• Servicios: reports.
• Efectos: ninguno.

Relaciones

• Requiere: Wallet.
• Dispara / afecta: ninguna funcionalidad identificada.

Notas

• Los desgloses complementarios se documentan por separado.