A1 · Qué administra cada componente
Esta extensión complementa el Manual de usuario. Está dirigida a personas que mantienen permisos, fuentes y seguimiento del agente. Para conversar, generar archivos, proyectos, biblioteca y memoria se siguen los pasos del manual principal.
| Responsable / componente | Responsabilidad |
|---|---|
| Portal ToolsDimaint | Autenticación corporativa y asignación del rol de la aplicación al usuario. |
| Administración del agente | Configurar qué capacidades, servicios, documentos y ámbito de inventario corresponde a cada ID de rol. |
| Fuentes Odoo, Snipe-IT y Jira | Mantener cuentas, datos, permisos y relaciones correctos en cada sistema. |
| Infraestructura | Configurar variables privadas, hosts permitidos, modelos, conectividad, respaldos y despliegue. |
- Entra al agente web con una cuenta autorizada.
- Abre Administración en la barra lateral. Requiere
settings.manage. - Selecciona la pestaña correspondiente: Roles, Servicios, Integraciones, Acceso a rama, Documentos, Consumo, Auditoría o Consultas.
- Revisa los valores antes de guardar. Los cambios de acceso se reevalúan en las operaciones y pueden bloquear historial y archivos previamente accesibles.
A2 · Crear o actualizar un rol
- Abre Administración → Roles. Selecciona un rol o pulsa + Agregar.
- Define el ID en configuración exactamente igual al rol recibido del portal, incluidas mayúsculas/minúsculas. El nombre visible es una etiqueta; no concede permisos por sí mismo. El ID de un rol existente es de solo lectura.
- Marca las capacidades necesarias. Para usar un servicio interno se necesita acceso organizacional, su permiso específico y el ID del servicio autorizado, además del ámbito/dependencias correspondientes.
- Escribe los Servicios autorizados y Documentos autorizados como IDs separados por comas.
*incluye todas las fuentes presentes y futuras de esa categoría; úsalo solo cuando ese alcance esté aprobado. - Selecciona el Ámbito de inventario y, cuando corresponda, limita empresas Odoo y Snipe-IT.
- Pulsa Guardar configuración. Pide validar con una cuenta del rol afectado que solo acceda a lo previsto.
| Capacidad / grupo | Qué habilita |
|---|---|
| Ver chats propios / Crear y escribir chats | Leer y generar conversaciones propias. Un rol llamado visor no es automáticamente de solo lectura si tiene escritura habilitada. |
| Consulta organizacional | Habilita el modo interno; no concede por sí solo acceso a cada fuente. |
| Generar documentos / Generar imágenes | Archivos exportables y generación de imágenes según modelo/proveedor configurado. |
| Editar documentación | Modificar documentos organizacionales autorizados. |
| Administrar configuración | Gestionar roles y configuración del agente. |
| Ver consumo global / Ver auditoría | Desglose global de uso y evidencia institucional correspondiente. |
| Inventario y personal | Permisos separados para asignaciones, personal, equipos disponibles y licencias. |
| CRM, actividades, tareas | Permisos separados para datos propios de Odoo. |
| jira.tickets.read / jira.tickets.create | Consultar tickets propios y preparar/confirmar solicitudes, respectivamente. |
A3 · Roles iniciales y ámbitos
| Nombre inicial | ID exacto | Ámbito inicial de inventario |
|---|---|---|
| Administrador | admin | Conserva la configuración administrativa inicial; revisar permisos efectivos. |
| Administrativo | administrativo | Global. |
| UsuarioCore | core | Sin acceso a inventario. |
| Colaborador | colaborador | Solo sus asignaciones. |
| Manager | manager | Personal directo. |
Este es el catálogo inicial de la versión 0.6.1. Una actualización conserva configuraciones existentes, por lo que pueden aparecer roles heredados como TI u otros nombres. La captura muestra la configuración de la instalación consultada, no una matriz universal de permisos.
| Ámbito | Efecto |
|---|---|
| Sin acceso al inventario | No autoriza consultas de inventario. |
| Solo sus asignaciones | Equipos y licencias directamente asociados a la identidad del solicitante. |
| Personal directo | Consulta lo propio y el personal directo de Odoo; la rama ampliada requiere una concesión. |
| Consulta global | Permite consultas organizacionales dentro de las fuentes/empresas autorizadas. No significa que todo el personal dependa del solicitante. |
A4 · Depurar y eliminar roles
- Revisa qué ID seguirá usando cada usuario en el mecanismo de asignación del portal. La versión 0.6.1 no consulta esas asignaciones desde el agente.
- En Administración → Roles, selecciona el rol que deseas retirar. Revisa su ID y etiqueta.
- Desplázate al final del editor y pulsa Eliminar rol.
- Lee la confirmación y acepta solo si corresponde retirar esa configuración.
- Comprueba que desaparezca de la lista. El borrado se conserva tras reinicios y queda registrado como
role.deleteen auditoría.
A5 · Configurar servicios de consulta
- En Administración → Servicios, selecciona el contrato o pulsa + Agregar.
- Define ID, nombre y una descripción clara del alcance para que el agente elija correctamente la herramienta.
- Selecciona Ejecutor y Método de consulta. Usa la URL HTTPS del servicio permitido por infraestructura. Los contratos generales son de lectura; POST para consultar Odoo no equivale a permiso de escritura.
- Configura el JSON Schema de parámetros y los campos devueltos permitidos. En contratos JSON, revisa también ejecución, proyección, paginación, autorización y dependencias.
- Establece el prompt específico y los límites. En Variable de credencial escribe solo el nombre de la variable del servidor, nunca el secreto. El ID de prompt publicado es opcional.
- Marca Disponible para el agente solo en herramientas que deban exponerse. Una dependencia privada debe permanecer fuera del catálogo visible.
- Guarda el contrato revisado y habilítalo cuando esté listo. Autoriza su ID en los roles correspondientes y prueba una consulta con el alcance esperado.
| Campo | Criterio operativo |
|---|---|
| URL y credencial | El host debe estar permitido en SERVICE_ALLOWED_HOSTS; la variable de credencial debe existir en el entorno de la API. Estos valores los prepara infraestructura. |
| Parámetros y campos | Declara solo las entradas y salidas necesarias. Una descripción no reemplaza los filtros de autorización del servidor. |
| Autorización y dependencias | Conserva las vinculaciones de identidad, directorio y ámbito. Cambiarlas requiere conocer el contrato de la integración. |
| Habilitado / Disponible para el agente | Habilitado permite ejecución; Disponible controla exposición al modelo. Una dependencia puede estar habilitada sin mostrarse al usuario. |
| Prompt específico | Describe la función y cómo responder ante datos ausentes. No amplía permisos ni autoriza nuevas URLs. |
A6 · Preparar y verificar integraciones
- Abre Administración → Integraciones. Comprueba qué contratos están habilitados y si su credencial aparece configurada.
- En una instalación nueva, confirma la URL HTTPS de Odoo y el nombre real de su base; añade Snipe-IT si corresponde y usa Crear contratos iniciales. No se sustituyen contratos existentes desde ese formulario.
- Para agregar consultas propias de trabajo, pulsa Crear consultas de CRM, actividades y tareas. Se crean borradores deshabilitados sin conceder permisos ni reemplazar el inventario existente.
- Revisa cada borrador en Servicios, incluidas sus dependencias; habilita únicamente lo aprobado.
- Usa Probar conexión en las dependencias disponibles para comprobar conectividad y una muestra acotada. La prueba no llama a OpenAI ni habilita servicios automáticamente.
- Autoriza los permisos y servicios en Roles; recarga la interfaz de la cuenta destinataria y realiza una consulta de comprobación.
A7 · Habilitar tickets de TI
La integración de Jira permanece deshabilitada por defecto y no concede permisos automáticamente. Infraestructura configura en la API JIRA_ENABLED, origen HTTPS, correo y token de integración, proyecto, mesa de servicio y tipo de solicitud, además del host permitido. No se colocan credenciales en el catálogo ni en el chat.
- Confirma con la administración de Jira que la cuenta técnica pueda buscar usuarios por correo, consultar solicitudes y crear en nombre del usuario en la mesa/tipo elegidos.
- Verifica que el correo corporativo permita vincular una única cuenta Jira activa. No se autoriza por coincidencia de nombre.
- Concede
chat.internal,jira.tickets.ready servicios de lectura. Para creación, agregajira.tickets.createy herramientas de preparar/crear. - Comprueba con una cuenta autorizada: listado propio, detalle propio, denegación de ticket ajeno y preparación de un borrador. Si realizas una prueba de creación, confirma expresamente su contenido y revisa la clave devuelta.
- Ante un envío incierto, revisa Jira antes de repetir con otro borrador. La aplicación no reenvía automáticamente estados inciertos.
| Herramienta | Permiso |
|---|---|
| jira-mis-tickets / jira-detalle-ticket | jira.tickets.read |
| jira-preparar-ticket / jira-crear-ticket | jira.tickets.create |
Para el operador del servidor, desde el directorio del paquete offline, el registro requiere un rol explícito. Ejemplo para un rol existente y aprobado:
docker compose --env-file .env -f compose.production.yaml exec -T api python - --grant-role colaborador --create < scripts/register-jira.pySin --create se concede solo consulta. Sustituye colaborador por el ID aprobado y conserva el resto de los permisos existentes. Este comando cambia la configuración del agente; no la asignación de roles del portal.
A8 · Conceder o revocar acceso a rama
- En Administración → Acceso a rama, revisa las decisiones existentes.
- Introduce el Email corporativo del responsable y selecciona Conceder toda la rama o Personal directo · revocar rama.
- Describe el motivo de la decisión.
- Pulsa Guardar decisión y verifica el registro. Comprueba después el alcance con la cuenta correspondiente.
A9 · Mantener documentación organizacional
- Abre Administración → Documentos y selecciona un documento o + Agregar.
- Define un ID estable, título y contenido de texto. Marca Habilitado cuando esté listo para usarse.
- Pulsa Guardar configuración.
- En Roles, autoriza el ID del documento a los perfiles destinatarios. Para editarlo, también requieren la capacidad correspondiente.
- Verifica Documentación → Mis documentos con una cuenta autorizada y realiza una consulta interna.
A10 · Revisar consumo, auditoría y consultas
| Pestaña | Qué revisar |
|---|---|
| Consumo | Entrada, salida y total propios; desglose global por usuario/modelo cuando se tiene usage.read. Incluye cada llamada de procesamiento y herramientas. |
| Auditoría | Fecha, usuario, rol, operación y resultado de las operaciones retenidas durante 30 días. Requiere audit.read. |
| Consultas | Contenido de preguntas y respuestas para auditoría durante 30 días. Eliminar un chat del historial no borra inmediatamente esta evidencia. Requiere audit.read. |
- Selecciona la pestaña y revisa el periodo retenido.
- Relaciona el usuario y la hora del incidente con la operación o consulta correspondiente.
- Si se necesita diagnóstico técnico, entrega al operador el mensaje y momento del error; consulta las trazas privadas del servidor con el procedimiento interno.
- Evita interpretar tokens como costo monetario o una respuesta fallida como ausencia de consumo.
A11 · Diagnóstico y continuidad operativa
| Síntoma | Revisión administrativa |
|---|---|
| Acceso denegado al módulo | ID exacto del rol recibido del portal y existencia de su configuración; comprobar si el rol fue eliminado. |
| No aparece una herramienta | Permiso organizacional, capacidad del dominio, ID autorizado, habilitación, exposición y dependencias. Recargar la interfaz tras cambios. |
| Datos propios no vinculados | Correo firmado frente al correo exacto/único y cuenta activa en la fuente correspondiente. No cambiar la identidad desde el chat. |
| Datos de equipo o personal incompletos | Jerarquía Odoo, empresas permitidas, ámbito y reglas de lectura de la cuenta técnica. Revisar integridad del resultado antes de presentar totales. |
| Falla una conexión | Host HTTPS permitido, variable de credencial transmitida a la API, permisos y disponibilidad del servicio. Configurar variables requiere reinicio/recreación de la API por infraestructura. |
| Un chat/archivo protegido dejó de abrir | Revocación de permiso, fuente, contrato, vinculación o relación jerárquica; puede ser una denegación esperada. |
| El integrado no carga en una aplicación externa | Sesión del portal, orígenes HTTPS autorizados para el iframe y configuración del wrapper. No desactivar controles del navegador para resolverlo. |
| No se ve el borrador Jira en una instalación anterior | Comprobar la versión desplegada y que API y web correspondan; la corrección de presentación del borrador está incluida en 0.6.1. |
| Un script de paquete no encuentra módulos | Comprobar que imagen instalada, versión del paquete y scripts correspondan. No mezclar scripts nuevos con una imagen antigua. |
Infraestructura debe conservar la base exclusiva del agente y los archivos persistentes de artefactos y Biblioteca en un respaldo consistente. Las credenciales, despliegue offline y restauración siguen los procedimientos técnicos del proyecto; este manual no cambia la instalación. La versión actual opera con una réplica y un worker de API: escalar requiere trabajo técnico adicional.