Uso de IA · Compras y proveedores

    @Tool(name = "consultar_orden_compra",
          description = "Devuelve una orden de compra por su identificador UUID: proveedor, moneda, líneas, cantidades recibidas, subtotales y estatus.")
    public String consultarOrdenCompra(
            @ToolParam(description = "Identificador UUID de la orden de compra", required = true) String ordenId) {
        RegistroHerramientasUsadas.registrar("consultar_orden_compra");
        String cuerpo = gateway.get()
                .uri(constructor -> constructor.path(RUTA_BASE + "/ordenes-compra/{id}").build(UUID.fromString(ordenId.trim())))
                .retrieve()
                .body(String.class);
        return FiltroDatosSensibles.redactar(cuerpo).texto();
    }

    @Tool(name = "crear_orden_compra",
          description = "Prepara una orden de compra en borrador para un proveedor, con una sola línea. "
                  + "NO la crea: devuelve un resumen y un accion_id. El usuario debe confirmarlo en la aplicación. "
                  + "Solo COMPRAS puede usarla.")
    public String crearOrdenCompra(
            @ToolParam(description = "Identificador UUID del proveedor", required = true) String proveedorId,
            @ToolParam(description = "Moneda ISO, por ejemplo MXN", required = true) String moneda,
            @ToolParam(description = "SKU del artículo", required = true) String articuloSku,
            @ToolParam(description = "Cantidad mayor a cero, hasta 3 decimales", required = true) String cantidad,
            @ToolParam(description = "Precio unitario, hasta 2 decimales", required = true) String precioUnitario) {
        RegistroHerramientasUsadas.registrar("crear_orden_compra");
        if (acciones == null) {
            return NO_DISPONIBLE;
        }
        UUID id = identificador(proveedorId);
        if (id == null) {
            return "El identificador del proveedor no es válido.";
        }
        String monedaLimpia = normalizar(moneda);
        if (monedaLimpia.isEmpty() || monedaLimpia.length() > 3) {
            return "La moneda debe ser un código ISO de hasta 3 letras, por ejemplo MXN.";
        }
        if (vacio(articuloSku) || articuloSku.trim().length() > 40) {
            return "El SKU es obligatorio y de hasta 40 caracteres.";
        }
        BigDecimal cant = decimal(cantidad, 3, 9);
        if (cant == null || cant.signum() <= 0) {
            return "La cantidad debe ser mayor a cero, con hasta 3 decimales y 9 dígitos enteros.";
        }
        BigDecimal precio = decimal(precioUnitario, 2, 10);
        if (precio == null || precio.signum() < 0) {
            return "El precio unitario no es válido: debe ser cero o positivo, con hasta 2 decimales.";
        }
        if (recurso(RUTA_BASE + "/proveedores/" + id) == null) {
            return "No encontré ese proveedor.";
        }
        Map<String, Object> linea = new LinkedHashMap<>();
        linea.put("articuloSku", articuloSku.trim());
        linea.put("cantidad", cant);
        linea.put("precioUnitario", precio);
        Map<String, Object> cuerpo = new LinkedHashMap<>();
        cuerpo.put("proveedorId", id.toString());
        cuerpo.put("moneda", monedaLimpia);
        cuerpo.put("lineas", java.util.List.of(linea));
        String resumen = "Orden de compra al proveedor " + id + ": " + cant.stripTrailingZeros().toPlainString()
                + " x " + articuloSku.trim() + " a " + precio.toPlainString() + " " + monedaLimpia;
        return guardar(AccionesPendientes.TIPO_ORDEN_COMPRA_CREAR, cuerpo, resumen, "Orden preparada, no creada.");
    }

    static final String RUTA_BASE = "/compras-proveedores-ms/v1";