Uso de IA · Clientes

    @Tool(name = "obtener_cliente",
          description = "Devuelve el detalle de un cliente por su identificador (UUID).")
    public String obtenerCliente(
            @ToolParam(description = "Identificador UUID del cliente", required = true) String id) {
        RegistroHerramientasUsadas.registrar("obtener_cliente");
        String cuerpo = gateway.get()
                .uri(RUTA_BASE + "/{id}", id)
                .retrieve()
                .body(String.class);
        return redactar(cuerpo);
    }

    @Tool(name = "crear_cliente",
          description = "Prepara el alta de un cliente con su contacto principal. NO lo crea: devuelve un resumen y un accion_id. "
                  + "El usuario debe confirmarlo en la aplicación. Solo ADMIN puede usarla.")
    public String crearCliente(
            @ToolParam(description = "Razón social del cliente", required = true) String razonSocial,
            @ToolParam(description = "RFC del cliente, en mayúsculas", required = true) String rfc,
            @ToolParam(description = "Nombre del contacto principal", required = true) String contactoNombre,
            @ToolParam(description = "Correo electrónico del contacto principal", required = true) String contactoCorreo,
            @ToolParam(description = "Rol del contacto: COMPRAS, PAGOS o ASISTENCIA", required = true) String contactoRol) {
        RegistroHerramientasUsadas.registrar("crear_cliente");
        if (acciones == null) {
            return NO_DISPONIBLE;
        }
        if (vacio(razonSocial) || razonSocial.trim().length() > 250) {
            return "La razón social es obligatoria y de hasta 250 caracteres.";
        }
        String rfcNormalizado = rfc == null ? "" : rfc.trim().toUpperCase();
        if (!RFC.matcher(rfcNormalizado).matches()) {
            return "El RFC no tiene un formato válido.";
        }
        String rol = normalizar(contactoRol);
        if (!ROLES_CONTACTO.contains(rol)) {
            return "El rol del contacto debe ser COMPRAS, PAGOS o ASISTENCIA.";
        }
        if (!correoValido(contactoCorreo)) {
            return "El correo del contacto no es válido.";
        }
        if (vacio(contactoNombre) || contactoNombre.trim().length() > 200) {
            return "El nombre del contacto es obligatorio y de hasta 200 caracteres.";
        }
        Map<String, Object> contacto = new LinkedHashMap<>();
        contacto.put("nombre", contactoNombre.trim());
        contacto.put("correo", contactoCorreo.trim());
        contacto.put("rol", rol);
        Map<String, Object> cuerpo = new LinkedHashMap<>();
        cuerpo.put("razonSocial", razonSocial.trim());
        cuerpo.put("rfc", rfcNormalizado);
        cuerpo.put("contactoPrincipal", contacto);
        String resumen = "Alta de cliente " + razonSocial.trim() + " (RFC " + rfcNormalizado + ")";
        return guardarAccion(AccionesPendientes.TIPO_CLIENTE_CREAR, cuerpo, resumen, "Alta preparada, no creada.");
    }

    static final String RUTA_BASE = "/clientes-ms/v1/clientes";